Verifiable token-based authentication¶

Name¶

Verifiable token-based authentication

Summary¶

A subject is identified by the system based on a token provided by the subject that contains sufficient information to determine the correct principal. The system will typically not keep track of issued tokens, but does verify the validity of received tokens. A common example is JSON Web Tokens (JWT) that contain, for instance, the username and role of the subject, along with a digital signature or MAC to verify the token's integrity.

Parent¶

Authentication

Problem¶

See Authentication

Solution¶

In this pattern a subject is authenticated using a token that itself contains the necessary information to determine the principal of a subject. The task of the system receiving the token as part of an authentication comes down to verifying whether the token is actually valid, e.g. it was actually issued by system at some earlier point.

In order to protect the integrity of a token it should either be appended with a digital signature or a MAC. These mechanisms allow to verify whether the content of a token, e.g. principal and expiration date, was not modified after the token was issued.

Roles¶

Subject (: Entity) that requests the System to perform an action
Subject <- Authentication.Evidence provider
Enforcer (: Enforcement point) ensures the requested action is only performed if the Subject is successfully authenticated, this entity must be incorporated into the system
Verifier (: Decision point) manages the verification of whether a token is valid
Digitally signed tokens: Verifier <- Digital signature.EntityB; or
MAC token: Verifier <- Message authentication code.EntityB
Cryptographer (: Cryptographic primitive) provides the cryptographic primitives to verify the integrity of a token and generate the cryptographic element necessary for this verification when a token is generated
Digitally signed tokens: Cryptographer <- Digital signature.Signature verifier, Digital signature.Signature generator; or
MAC token: Cryptographer <- Message authentication code.MAC verifier, Message authentication code.MAC generator
Key manager (: Entity) manages the cryptographic keys necessary to generate and verify tokens
System (: Entity) contains the business logic corresponding to the requested action
Registrar (: Entity) provides the Subject a token if it can successfully prove its claimed identity
Token generator (: Entity) manages the generation of new tokens
Digitally signed tokens: Token generator <- Digital signature.EntityA; or
MAC token: Token generator <- Message authentication code.EntityA

Actions¶

action (: Action) that the Subject wants to perform
verify (: Action) the validity of the provided token
get_verification_key (: Action) retrieve the cryptographic key needed to verify a given token
get_key <- Authentication.get_evidence
verify_integrity (: Action) verify whether the provided token has not been tampered with
Digitally signed tokens: verify_integrity <- Digital signature.verify; or
MAC token: verify_integrity <- Message authentication code.verify
generate (: Action) construct a new token for the provided principal
Digitally signed tokens: generate <- Digital signature.generate; or
MAC token: generate <- Message authentication code.generate
get_generation_key (: Action) retrieve the cryptographic key that is currently used to construct new tokens

Data elements¶

token (: Data) provided by the Subject to authenticate itself, this token contains sufficient information to correctly determine the Subject's principal
Tags: Untampered, Secret
token <- Authentication.credential, Authentication.Evidence
args (: Data) any additional arguments provided by the Subject as part of its action request (optional)
principal (: Data) identifies a Subject as it is known to the System
Tags: Untampered
Digitally signed tokens: principal <- Digital signature.d; or
MAC token: principal <- Message authentication code.d
expDate (: Data) the date (and time) until the token is valid
Digitally signed tokens: expDate <- Digital signature.d; or
MAC token: expDate <- Message authentication code.d
tokInt (: Data) data element that allows to detect whether the information in the token has been tampered with, i.e. a MAC or digital signature
Tags: Untampered
Digitally signed tokens: tokInt <- Digital signature.sig; or
MAC token: tokInt <- Message authentication code.mac
verKeyInf (: Data) information on the key to be used to verify the integrity of a token
Digitally signed tokens:
- Tags: Untampered
- verKeyInf <- Digital signature.pubKeyInf
MAC token:
- Tags: Untampered[, Secret]
- verKeyInf <- Message authentication code.keyInfo
genKeyInf (: Data) used to generate new, fresh tokens
Digitally signed tokens:
- Tags: Untampered[, Secret]
- genKeyInf <- Digital signature.privKeyInf
MAC token:
- Tags: Untampered[, Secret]
- genKeyInf <- Message authentication code.keyInfo
reply (: Data) from the System to the Subject triggered by the requested action (optional)
error (: Data) message informing the receiving entity its request was not granted
credential (: Data) the credential used by the Subject to authenticate itself the Registrar in order to obtain a token
Tags: Secret, Untampered
t_args (: Data) any additional claims that can be added to the token (optional)
Digitally signed tokens: exp_date <- Digital signature.d; or
MAC token: exp_date <- Message authentication code.d

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 cryptographic key necessary to verify the token's integrity from the Key manager.
The Key manager retrieves the appropriate cryptographic key and replies it to the Verifier.
The Verifier forwards the received token and verification key to Cryptographer to verify the token's integrity, i.e. ensure it has not been tampered with.
Cryptographer performs the necessary check to ensure that the token was not tampered with, i.e. check the MAC or verify the digital signature.
If the token is untampered, the Verifier performs further check to ensure it is valid, e.g. ensure the token is not yet expired. If all checks succeed the Verifier extracts the Subject's principal, and if present also further arguments, from the token and returns it to the Enforcer.
The Enforcer forwards the Subject's action request, with the token now replaced by the associated principal, to the System for further processing.
The System may reply to the Subject, for example, to provide the result of the action or confirm the request was received and/or executed. This reply does not need to pass through the Enforcer. (Optional)

Verifiable token-based authentication

Role considerations¶

Token verification (Verifier)¶

The actual verification of a received token consists of several steps. First, the integrity (and authenticity) of the token should be verified, the details for this step depend on the chosen cryptographic method as explained below. Second, the Verifier should check whether the token is not yet expired based on the contained expiration date and, if used, check whether the token is not explicitly revoked (cf. Token lifetime). Finally, additional checks are possible depending on the further contents, i.e. t_args, of the token. For example, if a token is only valid after a certain starting date, this date should be contained in the token.

Key length (Key manager)¶

The general recommendation is to use cryptographic key(s) that provide at least 128 bits of entropy.² The minimal key length necessary to achieve this depends on the chosen token integrity verification mechanism (cf. Token integrity). Furthermore, all keys should be generated using a cryptographically secure random number generator.

Key rotation (Key manager)¶

The cryptographic key(s) used to generate and verify tokens are likely to change over time, e.g. because keys are leaked or longer keys are required due to increasing computing power. Consequently, one should design the Key manager such that it can deal with key rotation and manage multiple keys at a time. For instance, while a generation may be deprecated, the corresponding verification key is likely still necessary to verify already issued tokens.

Token storage (Subject)¶

Specialisation of Authentication.Evidence provider

Due to its usage the token will typically have to be stored by the Subject, this risks leaking it to an attacker which can reuse the token. Depending on the underlying platforms some additional measures can be taken to limit such vulnerabilities. For example, OWASP provides advice on how to store verifiable tokens in the context of web applications.

Resource usage (Enforcer, Verifier, Cryptographer, Key manager)¶

Specialisation of Authentication.Resource usage

Subject registration (Registrar)¶

Specialisation of Authentication.Subject registration

The registration process here consists of the Subject authenticating via some other means, e.g. by providing a username and password. If the authentication is successful a new, fresh token is generated for the Subject. This token must contain an identifier for the authenticated principal, an expiration date, and any additional valid arguments the Subject provides. Furthermore, to allow the integrity of the token to be verified when provided later by the Subject an appropriate cryptographic data element must be appended as well (cf. Token integrity).

Token change (Subject)¶

Specialisation of Authentication.Credential change

The integrity of a verifiable token is paramount to this authentication mechanism, under no circumstances should a token be accepted that was modified after its initial creation. In order to obtain a new token, the Subject should (re-)authenticate via the Registrar.

Token reset (Resetter)¶

Specialisation of Authentication.Credential reset

Verifiable tokens should never be reset upon request by the Subject. If the Subject needs to acquire a new token, the Subject should (re-)authenticate via the Registrar.

Data considerations¶

Token selection¶

Specialisation of Authentication.Selection of credential and evidence

The principal corresponding to the Subjectis both proven by and derived from the token provided by the Subject, this token thus acts as credential as well as evidence. Consequently, every token must contain sufficient information to establish a Subjects principal, e.g. username or email address. The exact information required depends on the system at hand.

It is possible to include additional, non-identifying, information in a token. For example, for a shopping application, the Subject's payment information can be included in the token such that the system itself does not need to keep track of this. If such additional information is sensitive, as is case with payment information, additional attentions should be given to keep the token confidential during transmission or storage. It is important to protect the integrity of all additionally included information (cf. Token integrity).

Token lifetime¶

The longer a token is valid, the more likely is becomes that it can be used by an attacker to, for example, impersonate a legitimate Subject. Therefore, each token should contain information indicating over which period it is valid, e.g. an explicit expiration data or the date at which it was issued so that the receiving system can determine whether it still wants to process the token. The exact period depends on the system at hand and its security value but it is advised to keep this sufficiently short.³

As the system itself does not keep track of which tokens are valid at any time, tokens can only become invalid when they expire. This makes it difficult to revoke a token upon the Subject's request, e.g. when a user explicitly logs out of the system. A possible solution here is to keep a list of revoked, but not yet expired, tokens against which each incoming token can be verified.¹

Token integrity¶

It must be ensured that a malicious Subject, or other attacker, cannot tamper with the contents of a token without it being detected. One of two methods can be used to achieve this, either digitally sign the token or append a message authentication code (MAC) to the token. Which one is best suited depends on the system at hand.² Digital signatures allow to (more easily) verify that a token was actually issued by the Registrar, as the public key used to verify a token must match the private key used to generate the token. This is beneficial especially if the Registrar and Token generator are uncontrolled entities, e.g. when relying on an external identity provider. Note that this does require a reliable way to obtain the Registrar's public key. A similar check on who issued a token in the MAC case relies wholly on the issuer and verifier to share the same secret key and this key actually remaining secret to all other parties.

Whichever method to assess token integrity is used, it must be ensured that all information contained in the token is protected it. This includes the contained principal, as well as any other additional information such as expiration date and/or state information contained in the token.

Generation key (genKeyInf)¶

The cryptographic key used to generate tokens should at all times be kept secret and it should be protected against tampering, irrelevant of the integrity verification method. An attacker that obtains a valid generation key or can influence which generation key is used, is likely able to generate its own valid tokens or modify existing without it being detected by the Verifier or Cryptographer. Therefore, the necessary measures should be taken to ensure the secrecy and integrity of the generation key when it is transmitted over an uncontrolled channel and when it is stored by an entity, e.g. by the Key manager.

Verification key (verKeyInf)¶

A token's integrity verification depends on using the correct verification key, consequently it should be ensured that an attacker cannot modify or change the used verification key. For example, an attacker might tamper with the verification transmitted between Key manager and Verifier. Such a modification likely results in the token at hand being incorrectly considered as invalid, denying a legitimate Subject to perform its request action.

Token scope¶

Specialisation of Authentication.Credential scope

Implementations¶

A verifiable token can be created using either

References¶

An overview of libraries for JSON web tokens (JWT)

OWASP, ‘JSON Web Token Cheat Sheet for Java’, OWASP Cheat Sheet Series. https://cheatsheetseries.owasp.org/cheatsheets/JSON_Web_Token_for_Java_Cheat_Sheet.html ↩
M. Jones, J. Bradley, and N. Sakimura, ‘JSON Web Signatures (JWS)’, IETF, rfc 7515, May 2015. [Online]. Available: https://www.rfc-editor.org/rfc/rfc7515 ↩↩
OWASP, ‘OWASP Top 10: A01:2021 - Broken Access Control’, 2021. https://owasp.org/Top10/A01_2021-Broken_Access_Control/ ↩

Last update: March 22, 2023