Skip to content

Obscure token-based access control

Name

Obscure token-based control

Summary

A subject is both authenticated and authorised based on an obscure token it provides along with its request. An obscure token is typically used over a long time but might be less privileged than the subject's principal. Common examples are API tokens, Personal Access Token (PAT), and "secret" URLs as used in applications such as Google Documents.

Parent

Problem

Solution

In this solution a single, secret token is used to authenticate as well as authorise a subject's request. The token is thus used to both establish subject's principal and the associated privileges, which may be more limited than the full set of privileges associated with the principal. The token is generated by the system and typically only provided to the subject once. For example, platforms such as Gitlab and Github typically show a newly generated API token once on screen until the user confirms to have seen it.

Note

Typically, obscure tokens are used to authenticate and authorise client applications that act on behalf of a user, not the user itself.

Roles

  • Subject (: Entity) wants to perform an action on the system
    • Subject <- Authentication.Subject
    • Subject <- Authorisation.Subject
  • 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
    • Enforcer <- Authentication.Enforcer
    • Enforcer <- Authorisation.Enforcer
  • Validator (: Decision point) verifies whether the received token corresponds to a known principal, and whether the requested action is allowed with this token
    • Validator <- Authentication.Verifier
    • Validator <- Authorisation.Decider
  • Hasher (: Cryptographic primitive) calculates the hash value for a given input
  • Token manager (: Entity) keeps track of valid tokens and the principal(s) they belong to, possibly mapped to a set of privileges
    • Token manager <- Authentication.Evidence provider
    • Token manager <- Authorisation.Policy provider
  • Registrar (: Entity) generates new tokens and registers these with Principal provider
    • Registrar <- Authentication.Registrar
  • Token generator (: Cryptographic primitive) generates a new token when requested

Actions

  • action (: Action) that the Subject wants to perform
  • validate (: Action) whether the token is correct and is allows the requested action
    • validate <- Authentication.verify
    • validate <- Authorisation.authorise
  • get_information (: Action) retrieve the information known for the provided token, if any
    • get_information <- Authentication.get_evidence
    • get_information <- Authorisation.get_privileges
  • generate (: Action) request to generate a new obscure token
  • add (: Action) add a new token with a corresponding principal and, optionally, a set of privileges
  • next (: Action) request the next token to be generated

Data elements

  • token (: Data) used to match the requesting Subject to its principal
    • Tags: Secret, Untampered
    • token <- Authentication.credential
  • actionId (: Data) identifies the action that the Subject requested to execute
    • Tags: Identifier, Untamptered
  • hash(x) (: Data) the hash value calculated for data element x
  • principal (: Data) identifies a Subject as it is known to the System
    • Tags: Idenitifier, Untampered
  • privileges (: Data) overview of the privileges the Principal has (with respect to the required objects)
    • Tags: Untampered
    • privileges <- Authorisation.privileges
  • error (: Data) message to inform the receiver an check failed or action request could not be (correctly) executed
  • reply (: Data) from the System to the Subject triggered by the requested action (optional)

Behaviour

  1. The Subject requests an action from the System and provides a token as proof of its claimed identity and authorisation.
  2. The Enforcer intercepts the Subject's requests and forwards the token along with an id identifying the requested action to the Validator for verification.
  3. The Validator requests the Hasher to calculate the hash value for the received token.
  4. The Hasher calculates the hash value and replies it to the Validator.
  5. The Validator requests the principal and privileges that correspond to the received token from the Token manager.
  6. The Token manager retrieves information associated with the provided token and replies this to the Validator.
  7. The Validator decides whether the requested action is allowed based on the provided information and, if so, replies the received principal to the Enforcer as confirmation.
  8. The Enforcer forwards the Subject's action request, with the token now replaced by the associated principal, to the System for further processing.
  9. The System processes the action request and replies to the Subject. (Optional)

Obscure token-based access control

Role considerations

Token manager

Specialisation of Authentication.Evidence provider

Specialisation of Authorisation.Policy provider

The Token manager will keep track of at least the evidence, i.e. hash value calculated for a token, the corresponding principal, and possibly also any associated privileges. As obscure tokens are typically used over a long period of time, the Token manager most likely persistently stores this information. Appropriate measures should be taken to ensure that unauthorised entities cannot tamper with the stored information.

Hasher

As mentioned, the hash value for a token is used as evidence in the authentication process. As the token is generated by the system and not the Subject it should be guaranteed that it is sufficiently random (cf. Token generation). Consequently, a general-purpose hash value calculation algorithm, e.g. SHA256, can be used to calculate the hash values.

Subject registration (Registrar)

Specialisation of Authentication.Subject registration

The generation and registration of a new obscure token is triggered by such a request from the Subject. Before executing such a request the Subject must be properly authenticated, e.g. by providing its username and password, to ensure it is the actual owner of the principal for which a token will be created. If the Subject is properly authenticated a new token is registered and the token is replied to the Subject.

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.1 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.1 3 To obtain such tokens, it is advised to use a cryptographically secure pseudo-random number generator to generate tokens of at least 128 bits.1 2 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 (Registrar, Token manager)

In order to limit the possibility of a token being compromised the system should keep track of it as is, but after providing it to he Subject only keep the calculated hash value. For example, source code platforms such as Gitlab typically show a token only once to the user upon generation, after which it is the responsibility of the user to remember the plaintext token.

A Subject should always be able to, after being properly authenticated, revoke previously registered tokens. For example, if a token is (suspected to be) compromised or is no longer in active use. Furthermore, an expiration date can be set, either the Subject or Registrar, after which a token can no longer be used to be authenticated. In this case the Token manager should take care to invalidate a token upon reaching its expiration data. The appropriate period after which a token should be invalidated a depends strongly on the context in which the token is used.

Token change (Token manager)

Specialisation of Authentication.Token change

An obscure token should not be changed upon request of the Subject. The Subject should request a new token via the Registrar (cf. Subject registration and, if necessary, revoke the current token(s).

Token reset (Resetter)

Specialisation of Authentication.Credential reset

An obscure token should not be reset upon request of the Subject. The Subject should request a new token via the Registrar (cf. Subject registration and, if necessary, revoke the current token(s).

Error messages (Enforcer)

Specialisation of Authentication.Error messagesx

Sensitive actions (Enforcer)

Specialisation of Authentication.Sensitive actions

The actions that can be authorised based on a token should be a subset of the actions allowed for the corresponding subset. The exact subset can be determined using token-specific privileges. For example, when authenticating with a token only read access to certain data is authorised, while a fully authentication principal may also having write access.

Furthermore, a token should not be considered an appropriate credential to perform security-sensitive actions impacting the corresponding principal. For example, authenticating using a token should not allow a Subject to generate new tokens for its principal or to change the principal's password. For such actions explicit authentication using the credential(s) set when originally registering the principal, e.g. username and password, should be enforced.

Authorise after authentication (Validator)

Specialisation of Authorisation.Authorise after authentication

The Validator performs the authentication as well as authorisation of the received request. Under no circumstances should the Validator allow a request if the token (no longer) corresponds to a principal in the Token manager.

Resource usage (Enforcer, Validator, Token manager, Hasher)

Specialisation of Authentication.Resource usage

Specialisation of Authorisation.Resource absorption

Log authentication and authorisation failures (Validator)

Specialisation of Authentication.Log authentication failures

Specialisation of Authorisation.Log authorisation failures

Data considerations

Selection of credential and evidence

Specialisation of Authentication.Selection of credential and evidence

In this pattern the token is used as credential where its hash value (cf. Token manager) is used as evidence. The token is always determined by the system (cf. Token generation), never by the Subject.

token

Specialisation of Authentication.credential

principal

Specialisation of Authentication.principal

hash(token)

The hash value of the token is crucial for correctly validating the Subject's request. Appropriate measures should be taken to prevent any undetected tampering when it is transmitted over an uncontrolled channel and while it is stored in the Token manager. Any attacker that can change the hash value to correspond to a token they possess may gain unauthorised access to the system.

Token scope

Specialisation of Authentication.Credential scope

privileges

Specialisation of Authorisation.privileges

objectId

Specialisation of Authorisation.ObjectId

actionId

Specialisation of Authorisation.actionId

Implementations

None

References

Example candidates for Hasher - Libsodium generic hash - MessageDigest in Java - Python Hashlib

  1. R. Siles, ‘Session Management Cheat Sheet’, OWASP Cheat Sheet Series. https://cheatsheetseries.owasp.org/cheatsheets/Session_Management_Cheat_Sheet.html ↩↩↩

  2. G. Heartsfield, ‘Insufficient Session-ID Length’. https://owasp.org/www-community/vulnerabilities/Insufficient_Session-ID_Length ↩

  3. 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 ↩

Last update: February 7, 2022