Opaque token-based authentication¶

Name¶

Opaque token-based authentication

Summary¶

A subject is authenticated by the system based on a unique, opaque token the subject provides along with its action request. As the token is the sole piece of information used to establish the subject's principal, the secrecy of this token is crucial to this authentication pattern. A common example of this pattern is the use of session identifiers to (re-)authenticate a subject that previously authenticated through other means.

Parent¶

Authentication

Problem¶

See Authentication

Solution¶

In this solution the principal of a subject is determined based on a token provided by that subject. The system issues tokens and keeps a map of which tokens are valid at any time associated with their corresponding principal. It is the system's responsibility to manage the lifecycle of the tokens it issues.

Roles¶

Subject (: Entity) wants to perform an action on the system
Enforcer (: Enforcement point) ensures the token provided by the Subject is verified before the requested action is processed, this entity must be incorporated into the system
Verifier (: Decision point) verifies whether the received token corresponds to a known principal
Principal provider (: Entity) keeps track of valid tokens and the principal(s) they belong to
- Principal provider <- Authentication.Evidence provider
Registrar (: Entity) handles the registration of tokens for principals
Token generator (: Cryptographic primitive) generates a new token when requested

Actions¶

action (: Action) that the Subject wants to perform
verify (: Action) the validity of the provided token
get_principal (: Action) retrieve the principal to which the provided token belongs, if any
- get_principal <- Authentication.get_evidence
next (: Action) request the next token to be generated
add (: Action) request a new token for the given principal

Data elements¶

token (: Data) used to match the requesting Subject to its principal
- token <- Authentication.credential
- Tags: Secret, Untampered
principal (: Data) identifies a Subject as it is known to the System
- Tags: Untampered
error (: Data) message indicate a check failed or an action could not be (correctly) executed
reply (: Data) from the System to the Subject triggered by the requested action (optional)

Behaviour¶

The Subject requests an action from the System and provides a token as proof of its claimed identity
The Enforcer intercepts the Subject's requests and forwards the token to the Verifier for verification
The Verifier requests the principal that matches the received token from the Principal provider
The Principal provider retrieves the principal associated with the provided token.
The Verifier replies the received principal to the Enforcer as confirmation that the provided token is valid.
The Enforcer forwards the Subject's action request, with the token now replaced by the associated principal, to the System for further processing.

Opaque token-based authentication

Role considerations¶

Resource usage (Enforcer, Verifier, Principal provider)¶

Specialisation of Authentication.Resource usage

Subject registration (Registrar)¶

Specialisation of Authentication.Subject registration

The registration of a new opaque token is triggered by the Subject successfully authenticating through other means, e.g. using its username and password. After a successful authentication, the Registrar requests the Principal provider to add a new token for the given principal. The Principal provider will obtain a new token from the Token generator (cf. Token generation). In order to avoid duplicate active tokens, i.e. two principals are associated with the same token, the Principal provider should check the new token against active ones and, if necessary, request another new token. The Principal provider will inform the Registrar of the token registered for the principal, which in turn forwards this token to the Subject for further use. The Principal provider is responsible to keep track of all valid tokens and their associated principals (cf. Token lifetime).

If any additional information stored alongside the token and principal is sensitive additional security measures should be taken.¹ For example, in an online shopping application it might be necessary to keep track of payment information associated with a session, in such a case this data should be encrypted and access to the Principal provider should be protected.

In most cases, when a Subject authenticates via the Registrar, the Principal provider should deactivate any tokens already registered for the corresponding principal. An exception here are systems that, for instance, allow a user to have multiple active sessions for the same account. For example, some media services allow customers to access content from several devices simultaneously.

Token generation (Token generator)¶

An opaque token has to be unpredictable, i.e. sufficiently random, to avoid that an attacker is able to guess or enumerate it. This should hold true even if an attacker can observe one or more valid tokens, e.g. because the attacker can obtain tokens for his or her own principal. A token, on its own, should thus be meaningless, and never contain any (sensitive) information such as, for example, the Subject's principal or IP address.¹ Any information associating a token with a principal should only be kept at the back-end, i.e. by the Principal provider, and should never be deducible from the token itself.

As a rule of thumb, to prevent guessing attacks, a token should provide at least 64 bits of entropy.¹ ³ To obtain such tokens, it is advised to use a cryptographically secure pseudo-random number generator to generate tokens of at least 128 bits.¹ ² Most programming languages provide such a generator, typically as part of their security or cryptography libraries. OWASP provides an overview of cryptographically secure generators for some common languages.

Token lifetime (Principal provider)¶

The longer an opaque token is valid, the more likely it becomes that it leaks or that an attacker is able to guess it, even if tokens are sufficiently random. Therefore, the duration for which a token is valid should be limited, where the exact duration depends on the nature of the System under design. It is advised to enforce a timeout period based on the Subject's activity as well as an absolute maximum duration for which a token can be valid.¹

The activity-based timeout period should be relatively short, typically in the order of a few minutes to half an hour.¹ For example, in a high-value application this timeout should be very short, e.g. 2 to 3 minutes. For less critical or low-value applications longer ranges, e.g. 15 to 30 minutes, can be used. This timeout does mean that a Subject that is inactive for a long enough time has to acquire a new token before it can request any further actions. Determining the right timeout value should thus strive to balance security and usability.

Furthermore, an appropriate absolute, maximum validity duration should be set, any token older than this has to be invalidated irrelevant of the Subject's activity. The exact time period can be longer than the activity-based timeout, e.g. in the order of a few hours, and should be chosen as a balance usability and security.

Finally, if a Subject signals it will no longer use a token it should be immediately invalidated. This happens, for example, when a Subject logs out of a system. Similarly, if a Subject requests a new token, by (re-)authenticating via the Registrar, any existing token should be invalidated.

Token change (Principal provider)¶

Specialisation of Authentication.Credential change

An opaque token is used as a short-term and should not be changed upon request of the Subject. In some situations the system should force a token renewal though, i.e. invalidate the current token and replace it with a new one. For example, if the privileges of a Subject change after it re-authenticated before performing one or more sensitive operations.¹ Such forced token changes help in preventing session fixation attacks⁴ in which the attacker is able to set the token used by the Subject.

Token reset (Resetter)¶

Specialisation of Authentication.Credential reset

An opaque token acts as a short-term credential and should not be reset upon request by the Subject. Consequently, a system should not provide explicit functionality to reset a lost token to the Subject. A Subject that loses its token should instead re-authenticate via the Registrar to obtain a new token. If a Subject re-authenticates, any active token for that Subject should be invalidated before issuing a new token.

Data considerations¶

Selection of credential and evidence¶

Specialisation of Authentication.Selection of credential and evidence

An opaque token on its own acts as the credential from the parent pattern and should be considered a factor you have. For example, the token might be stored in a cookie managed by the browser used by the Subject. As evidence the fact whether or not a principal is associated with a token is used, i.e. whether the Evidence provider returns a principal or an error.

token¶

Specialisation of Authentication.credential

principal¶

Specialisation of Authentication.principal

Token scope¶

Specialisation of Authentication.Credential scope

Implementations¶

Session-based access control combines opaques tokens with authorisation to allow subjects to perform multiple actions without having to obtain a new token

References¶

Pointers for possible Token generator can be found in the Token generation consideration.

R. Siles, ‘Session Management Cheat Sheet’, OWASP Cheat Sheet Series. https://cheatsheetseries.owasp.org/cheatsheets/Session_Management_Cheat_Sheet.html ↩↩↩↩↩↩↩
G. Heartsfield, ‘Insufficient Session-ID Length’. https://owasp.org/www-community/vulnerabilities/Insufficient_Session-ID_Length ↩
P. A. Grassi et al., ‘Digital Identity Guidelines - Authentication and Lifecycle Management (Section 7)’, NIST, 800–63B, Jun. 2017. [Online]. Available: https://doi.org/10.6028/NIST.SP.800-63b ↩
M. Kolšek, ‘Session Fixation Vulnerability in Web-based Applications’, ACROS Security, Dec. 2002. [Online]. Available: http://www.acrossecurity.com/papers/session_fixation.pdf ↩

Last update: February 4, 2022