Tokens

Tokens in OAuth 2.0: Authorization Codes, Access Tokens, and Refresh Tokens

Tokens play a pivotal role in the OAuth 2.0 authorization framework, acting as digital keys that grant access to resources. This article delves into the types of tokens used in OAuth 2.0—Authorization Codes, Access Tokens (specifically JWTs), and Refresh Tokens—explaining their purpose, structure, and usage. Understanding these tokens is crucial for implementing secure authentication and authorization processes.

Authorization Code

The process for obtaining secure access to resources starts when a user authenticates by logging in, which triggers their redirection to the Authorization Server's login page.

After a successful login, the Authorization Server grants an Authorization Code. This short-lived token, which remains valid for 5 minutes, is designed to be exchanged for an Access Token. The use of an Authorization Code adds a security layer to the OAuth 2.0 process by ensuring that the user's credentials are kept secure and are not directly exposed to the client application.

Access Tokens

Following the retrieval of an Authorization Code, the client application requests an Access Token from the Authorization Server. Access Tokens, particularly in the form of JSON Web Tokens (JWTs), contain claims that convey information about the user and the granted permissions.

This is the structure of the JWT Access Token provided by the authorization server:

{
  "iss": "https://api.perceive.eu",
  "exp": 1708604570,
  "iat": 1708600970,
  "aud": ["identity_service_api", "data_service_api", "orchestrator_api", "metadata_service_api"],
  "scope": "identity_management data_management metadata_management",
  "jti": "2d6108d0-3878-4418-b921-3d09c267fbb3",
  "oi_prst": "the-client",
  "oi_au_id": "376c4b4e-d405-4ce1-a3f3-ded819ea181f",
  "sub": "4c41016e-02d1-4ad4-874d-fe637ba735c0",
  "name": "username",
  "preferred_username": "username",
  "role": "Visitor",
  "client_id": "the-client",
  "oi_tkn_id": "fa35c944-4323-44de-811f-a8c65643f19d"
}

This token includes essential information such as the issuer (iss), the audience (aud), the issued and expiration times (iat and exp), and the user's roles and permissions (scope, role). Access Tokens are valid for 5 minutes, to minimize the risk in case of token exposure, and the ability to revoke access. The client has to request a new access token using the refresh token to continue making requests.

Refresh Tokens

To maintain access without requiring the user to log in again once the Access Token expires, Refresh Tokens are used. A Refresh Token is issued alongside the Access Token and can be used to obtain a new Access Token and Refresh Token pair.

This token is valid for 31 days and implements a rolling refresh mechanism, where each time a new Access Token is requested, a new Refresh Token is also provided (which is again valid for 31 days).

This approach ensures that users remain authenticated in a secure manner, without frequent login prompts, while also mitigating the risk of long-lived tokens being compromised. For more details on the implementation, please refer to Frontend implementation.

Token Validity

Token and code validity periods are as follows:

Authorization Code: 5 minutes
Access Token: 5 minutes
Refresh Token: 31 days

Security Considerations for Token Handling

Please read the following security considerations

Secure Token Storage

Tokens MUST be stored securely to prevent unauthorized access and potential security breaches. Specifically, Access Tokens and Refresh Tokens MUST NOT be stored in local storage or session storage within web applications due to the risk of Cross-Site Scripting (XSS) attacks.
Secure, HttpOnly cookies SHALL be used to store tokens, preventing access by malicious scripts. Furthermore, these cookies MUST have the Secure attribute set, ensuring they are transmitted only over HTTPS connections.
The SameSite cookie attribute SHOULD be used to mitigate the risk of Cross-Site Request Forgery (CSRF) attacks. It is RECOMMENDED to set this attribute to Strict or Lax depending on the application's requirements for cross-site usage.

Token Transmission Security

All token transmissions MUST occur over HTTPS to protect the tokens in transit against Man-In-The-Middle (MITM) attacks. This REQUIREMENT ensures the encryption of data between the client and the server, providing a secure channel for sensitive information.
Token Validation and Revocation
Each time a token is presented to a server, it MUST be validated for its integrity and authenticity. This involves checking the signature of the token, validating the issuer, the intended audience, and ensuring that the token has not expired.
Implementations MUST provide mechanisms to revoke tokens when necessary, such as when a user logs out, changes their password, or if the token is believed to be compromised. This practice is crucial for limiting the potential damage from stolen or leaked tokens.

Adherence to Standards and Best Practices

Following the OAuth 2.0 Security Best Current Practice document is MANDATORY. This document offers up-to-date security guidelines for OAuth 2.0 implementations, addressing contemporary threats and outlining recommended mitigations.
Adhering to the Open Web Application Security Project (OWASP) recommendations for securely handling tokens is HIGHLY RECOMMENDED. OWASP's guidelines on secure storage, transmission, and validation of tokens can significantly bolster the security of an application.
Conducting regular security audits and penetration testing to identify and mitigate potential vulnerabilities in the token handling process is STRONGLY ADVISED. This SHOULD include a thorough review of the implementation of token storage, transmission, and validation mechanisms.

Last modified: 28 March 2024