This is another iteration on top of the previous sub-tokens work. Essentially,
the concept of a "parent token" has been replaced with the concept of a
"grant" to which all tokens now belong. The grant does not have any tokens
when first created, but the create_token() call can add them.
Properties of sub-tokens:
- They share the same id as their parent token
- Sub-tokens may not have their own sub-tokens (but may have sibling tokens)
- They always have the same or shorter lifetime compared to their parent token
- Revoking a parent token revokes all sub-tokens
- Sub-tokens always have the same JID as the parent token
- They do not have their own 'accessed' property - accessing a sub-token
updates the parent token's accessed time
Although this is a generic API, it is designed to at least fill the needs of
OAuth2 refresh + access tokens (where the parent token is the refresh token
and the sub-tokens are access tokens).
The new format has the following properties:
- 5 bytes longer than the previous format
- The token now has separate 'id' and 'secret' parts - the token itself is no
longer stored in the DB, and the secret part is hashed
- The only variable length field (JID) has been moved to the end
- The 'secret-token:' prefix (RFC 8959) is now included
Compatibility with the old token format was not maintained, and all previously
issued tokens are invalid after this commit (they will be removed from the DB
if used).
RFC 6120 states that
> If the initiating entity does not wish to act on behalf of another
> entity, it MUST NOT provide an authorization identity.
Thus it seems weird to require it here. We can instead expect an
username from the token data passed back from the profile.
This follows the practice of util.sasl.external where the profile
callback returns the selected username, making the authentication module
responsible for extracting the username from the token.
This allows tokens to be tied to specific purposes/protocols. For example, we
shouldn't (without specific consideration) allow an OAuth token to be dropped
into a slot expecting a FAST token.
While FAST doesn't currently use mod_tokenauth, it and others may do in the
future. It's better to be explicit about what kind of token code is issuing or
expecting.
This is a security improvement, to ensure that sessions authenticated using a
token (note: not currently possible in stock Prosody) are invalidated just
like password-authenticated sessions are.
These changes to the API (hopefully the last) introduce a cleaner separation
between the user's primary (default) role, and their secondary (optional)
roles.
To keep the code sane and reduce complexity, a data migration is needed for
people using stored roles in 0.12. This can be performed with
prosodyctl mod_authz_internal migrate <host>
This also updates the module to the new role API, and improves support for
scope/role selection (currently treated as the same thing, which they almost
are).
