Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

🔒 SASL: Clarify usage of username vs authcid vs authzid #187

Merged
merged 5 commits into from
Oct 20, 2023

Conversation

nevans
Copy link
Collaborator

@nevans nevans commented Oct 3, 2023

Different SASL mechanisms use the term "username" differently. In general the pattern seems to be the following:

  • Some mechanisms avoid using the term username at all, and instead use the terms Authentication Identity (authcid) and Authorization Identity (authzid).
  • Some mechanisms do not distinguish clearly between authcid and authzid. username may be semantically equivalent to authcid, authzid, or both.
  • When the mechanism supports an explicit authcid) and an Authorization Identity authzid, username commonly refers to the authcid.
  • When the authentication identity is derived from the credentials, username commonly refers to the authzid

Every mechanism's keyword arguments, positional arguments, and documentation has been updated to match this terminology. Aliases have been added from username to authcid or authzid—or in the other direction, from authcid or authzd to username

Instead of raising an exception, conflicting arguments are treated like silently ignored. This allows more specific argument (like authcid or a keyword argument) to be used like an override to more generic terms (like username or a positional argument). This could simplify using a single hash of keyword arguments with multiple SASL mechanisms, which could facilitate dynamically negotiating the mechanism, or automatically retrying multiple acceptable mechanisms.

OAuthBearerAuthenticator was updated to allow two arguments, in order to match the common auth(username, secret) parameter style. In my opinion, this makes the API a little bit more confusing. But the mechanism only requires one argument, so it's natural to allow a single argument version. And this two argument version matches with how many clients and applications seem to assume the SASL mechanisms always work.

@nevans nevans marked this pull request as draft October 3, 2023 13:51
@nevans nevans requested review from hsbt and shugo October 3, 2023 13:52
@nevans nevans force-pushed the sasl/username-vs-authcid-vs-authzid branch from 71ea9fd to 56459e1 Compare October 4, 2023 16:54
@nevans nevans added the SASL 🔒 Authentication and authentication mechanisms label Oct 5, 2023
@nevans nevans force-pushed the sasl/username-vs-authcid-vs-authzid branch from 56459e1 to 2576cad Compare October 8, 2023 03:27
@nevans nevans marked this pull request as ready for review October 10, 2023 03:07
@nevans nevans force-pushed the sasl/username-vs-authcid-vs-authzid branch from 2576cad to edb6040 Compare October 10, 2023 03:19
Harmonized the formatting and language of SASL mechanism parameters.
Made a few corrections (e.g. where `PLAIN` should have been `XOAUTH2`).
Added some RFC reference links.  Etc.
Different SASL mechanisms use the term "username" differently. In
general the pattern seems to be the following:

* Some mechanisms avoid using the term `username` at all, and instead
  use the terms Authentication Identity (`authcid`) and Authorization
  Identity (`authzid`).
* Older or non-standard mechanisms may not distinguish clearly between
  `authcid` and `authzid`. `username` may be semantically equivalent to
  `authcid`, `authzid`, or both.
* When the mechanism supports an explicit `authcid` and an `authzid`,
  `username` commonly refers to the `authcid`.
* When the authentication identity is derived from other credentials,
  `username` commonly refers to the `authzid`.

Every mechanism's keyword arguments, positional arguments, and
documentation is updated to match this terminology.  Aliases have been
added from `username` to `authcid` or `authzid`—or in the other
direction, from `authcid` or `authzd` to `username`.
`OAuthBearerAuthenticator` was updated to allow two arguments, in order
to match the common `auth(username, secret)` parameter style.  In my
opinion, this makes the API a little bit confusing.  But the mechanism
only requires one argument, so it's natural to allow a single argument
version.  And this two argument version matches with how many clients
and applications seem to_assume_ the SASL mechanisms _always_ work.
Instead of raising an exception, conflicting arguments are silently
ignored.  This allows more specific argument (like `authcid` or a
keyword argument) to be used like an override to more generic terms
(like `username` or a positional argument).  It should also simplify
using a single set of keyword credentials with multiple SASL mechanisms,
which could facilitate dynamically negotiating the mechanism, or
automatically retrying multiple acceptable mechanisms.
These are added to give _all_ mechanisms the same basic argument
semantics.  If it were just for `Net::IMAP`, I'd say it's not worth it.
However, to make this `SASL` implementation fully compatible with
others—such as `net-smtp`.
@nevans nevans force-pushed the sasl/username-vs-authcid-vs-authzid branch from 70c0311 to 34e4662 Compare October 19, 2023 23:44
@nevans nevans merged commit ca7f3c3 into ruby:master Oct 20, 2023
11 checks passed
@nevans nevans deleted the sasl/username-vs-authcid-vs-authzid branch October 20, 2023 01:52
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment
Labels
SASL 🔒 Authentication and authentication mechanisms
Development

Successfully merging this pull request may close these issues.

1 participant