Skip to content

Commit

Permalink
Clarify token terminology throughout to resolve #2414
Browse files Browse the repository at this point in the history
  • Loading branch information
@tghosth
tghosth committed Dec 5, 2024
1 parent 41f7d9a commit 7c4c41d
Show file tree
Hide file tree
Showing 4 changed files with 43 additions and 42 deletions.
6 changes: 3 additions & 3 deletions 5.0/en/0x12-V3-Session-management.md
View file
Original file line number Diff line number Diff line change
Expand Up @@ -35,8 +35,8 @@ Some of the requirements in this section relate to section [7.1](https://pages.n
| :---: | :--- | :---: | :---: | :---: | :---: |
| **3.1.1** | [DELETED, MERGED TO 8.3.1] | | | | |
| **3.1.2** | [ADDED] Verify that the application performs all session token verification using a trusted, back-end service. | ✓ | ✓ | ✓ | 603 |
| **3.1.3** | [MODIFIED, MOVED FROM 3.5.2, LEVEL L2 > L1] Verify that the application uses either cryptographically secured or random session tokens for session management. Static API secrets and keys should be avoided. | ✓ | ✓ | ✓ | 798 |
| **3.1.4** | [MODIFIED, MOVED FROM 3.2.2, MERGED FROM 3.2.4] Verify that if random tokens are used to represent user sessions, they are unique and generated using a cryptographically secure pseudo-random number generator (CSPRNG) and possess at least 128 bits of entropy. | ✓ | ✓ | ✓ | |
| **3.1.3** | [MODIFIED, MOVED FROM 3.5.2, LEVEL L2 > L1] Verify that the application uses either cryptographically secured or reference tokens for session management. Static API secrets and keys should be avoided. | ✓ | ✓ | ✓ | 798 |
| **3.1.4** | [MODIFIED, MOVED FROM 3.2.2, MERGED FROM 3.2.4] Verify that if reference tokens are used to represent user sessions, they are unique and generated using a cryptographically secure pseudo-random number generator (CSPRNG) and possess at least 128 bits of entropy. | ✓ | ✓ | ✓ | |

## V3.2 Session Binding

Expand Down Expand Up @@ -108,7 +108,7 @@ Session termination may be handled either by the application itself or by the SS

Session termination should result in requiring re-authentication and be effective across the application, federated login (if present), and any relying parties.

For stateful session mechanisms, this should just require invalidating the session at the backend. If a stateless session mechanism with signed tokens is being used, a way to revoke these tokens will be needed.
For stateful session mechanisms, this should just require invalidating the session at the backend. If self-contained tokens are being used, a way to revoke these tokens will be needed.

Some of the requirements in this section relate to section [7.1](https://pages.nist.gov/800-63-3/sp800-63b.html#71-session-bindings) of [NIST's Guidance](https://pages.nist.gov/800-63-3/sp800-63b.html).

Expand Down
2 changes: 1 addition & 1 deletion 5.0/en/0x12-V4-Access-Control.md
View file
Original file line number Diff line number Diff line change
Expand Up @@ -46,7 +46,7 @@ The immediate application of access control changes in the appropriate tier of a
| **4.2.2** | [MOVED TO 50.3.1] | | | | |
| **4.2.3** | [MODIFIED, MOVED FROM 4.1.1] Verify that the application enforces access control rules at a trusted service layer and doesn't rely on controls that an untrusted consumer could manipulate, such as client-side JavaScript. | ✓ | ✓ | ✓ | 602 |
| **4.2.4** | [ADDED] Verify that changes to values on which access control decisions are made are applied immediately. Where changes cannot be applied immediately, (such as when relying on data in cryptographically secured tokens), there must be mitigating controls to alert when a consumer performs an action when they should no longer be able to do so and revert the change. Note that this would be unable to mitigate information leakage. | | ✓ | ✓ | |
| **4.2.5** | [ADDED] Verify that access to an object is based on the originating subject's (e.g. consumer's) permissions, not on the permissions of any intermediary or service acting on their behalf. For example, if a consumer calls a web service using a signed token for authentication, and the service then requests data from a different service, the second service should use the consumer's signed token, rather than a machine-to-machine token from the first service, to make permission decisions. | | | ✓ | 441 |
| **4.2.5** | [ADDED] Verify that access to an object is based on the originating subject's (e.g. consumer's) permissions, not on the permissions of any intermediary or service acting on their behalf. For example, if a consumer calls a web service using a cryptographically secured token for authentication, and the service then requests data from a different service, the second service should use the consumer's token, rather than a machine-to-machine token from the first service, to make permission decisions. | | | ✓ | 441 |

## V4.3 Other Access Control Considerations

Expand Down
70 changes: 35 additions & 35 deletions 5.0/en/0x52-V52-Tokens.md
View file
Original file line number Diff line number Diff line change
@@ -1,35 +1,35 @@
# V52 Self-contained Tokens

## Control Objective

The concept of a self-contained token is mentioned in the original RFC 6749 OAuth 2.0 from 2012. It effectively refers to a token which contains data or claims which a receiving service will rely upon to make security decisions. This is to be differentiated from a token which is just an identifier which a receiving service will use to lookup data locally. The most common example of a self-contained token is a JSON Web Token (JWT) but a SAML assertion could also fall into this category.

The use of self-contained tokens has become very widespread, even outside of OIDC/OAuth. At the same time, the security of this mechanism relies on the ability to validate the integrity of the token and to ensure that the token is valid for a particular context. There are many pitfalls with this process and this chapter will provide specific details of the mechanisms that applications should have in place to prevent them.

## V52.1 Token source and integrity

Before inspecting the contents of a self-contained token, it is necessary to ensure that the token has been produced by a trusted party and that it has not been tampered with.

| # | Description | L1 | L2 | L3 | CWE |
| :---: | :--- | :---: | :---: | :---: | :---: |
| **52.1.1** | [MOVED FROM 3.5.3, MODIFIED, LEVEL L2 > L1] Verify that cryptographically secured tokens are validated using their digital signature or MAC to protect against tampering before accepting the token's contents. | ✓ | ✓ | ✓ | 345 |
| **52.1.2** | [ADDED] Verify that only algorithms on an allowlist can be used to create and verify cryptographically secured tokens, for a given context. The allowlist should include the permitted algorithms, ideally only either symmetric or asymmetric algorithms, and should not include the 'None' algorithm. If both symmetric and asymmetric are needed, additional controls should prevent key confusion. | ✓ | ✓ | ✓ | 757 |
| **52.1.3** | [ADDED] Verify that key material that is used to validate cryptographically secured tokens is from trusted pre-configured sources for the token issuer, preventing attackers from specifying untrusted sources and keys. For JWTs and other JWS structures, headers such as 'jku', 'x5u', and 'jwk' must be validated against an allowlist of trusted sources. | ✓ | ✓ | ✓ | |

## V52.2 Using token content

Before making security decisions based on the content of a self-contained token, it is necessary to validate that the token has been presented within it's validity period and that it is meant for use by the receiving service and for the purpose for which it was presented. This is to avoid insecure cross-usage between different services or with different token types from the same issuer.

Specific requirements for OAuth and OIDC are covered in the dedicated chapter.

| # | Description | L1 | L2 | L3 | CWE |
| :---: | :--- | :---: | :---: | :---: | :---: |
| **52.2.1** | [ADDED] Verify that, if a validity time span is present in the token data, the token and its content are accepted only if the verification time is within this validity time span. For example, for JWTs the claims 'nbf' and 'exp' must be verified. | ✓ | ✓ | ✓ | 613 |
| **52.2.2** | [ADDED] Verify that the service receiving a token validates the token to be the correct type and is meant for the intended purpose before accepting the token's contents. For example, only access tokens can be accepted for authorization decisions and only ID tokens can be used for proving user authentication. | ✓ | ✓ | ✓ | |
| **52.2.3** | [ADDED] Verify that the service only accepts tokens which are intended for use with that service (audience). For JWTs, this can be achieved by validating the 'aud' claim against an allowlist defined in the service. | ✓ | ✓ | ✓ | |

## References

For more information, see also:

* [OWASP Cheatsheet - JSON Web Token Cheat Sheet for Java](https://cheatsheetseries.owasp.org/cheatsheets/JSON_Web_Token_for_Java_Cheat_Sheet.html) (but has useful general guidance)
# V52 Cryptographically Secured Tokens

## Control Objective

In a cryptographically secured token, the authenticity of the token is validated using cryptography. This type of token may just contain a reference to data stored locally within a service or it might be a self-contained token. The concept of a self-contained token is mentioned in the original RFC 6749 OAuth 2.0 from 2012. It effectively refers to a cryptographically secured token which contains data or claims which a receiving service will rely upon to make security decisions. The most common example of a self-contained token is a JSON Web Token (JWT) but a SAML assertion could also fall into this category.

The use of self-contained tokens has become very widespread, even outside of OIDC/OAuth. At the same time, the security of this mechanism relies on the ability to validate the integrity of the token and to ensure that the token is valid for a particular context. There are many pitfalls with this process and this chapter will provide specific details of the mechanisms that applications should have in place to prevent them.

## V52.1 Token source and integrity

Before using a cryptographically secured token, it is necessary to ensure that the token has been produced by a trusted party and that it has not been tampered with.

| # | Description | L1 | L2 | L3 | CWE |
| :---: | :--- | :---: | :---: | :---: | :---: |
| **52.1.1** | [MOVED FROM 3.5.3, MODIFIED, LEVEL L2 > L1] Verify that cryptographically secured tokens are validated using their digital signature or MAC to protect against tampering before accepting the token's contents. | ✓ | ✓ | ✓ | 345 |
| **52.1.2** | [ADDED] Verify that only algorithms on an allowlist can be used to create and verify cryptographically secured tokens, for a given context. The allowlist should include the permitted algorithms, ideally only either symmetric or asymmetric algorithms, and should not include the 'None' algorithm. If both symmetric and asymmetric are needed, additional controls should prevent key confusion. | ✓ | ✓ | ✓ | 757 |
| **52.1.3** | [ADDED] Verify that key material that is used to validate cryptographically secured tokens is from trusted pre-configured sources for the token issuer, preventing attackers from specifying untrusted sources and keys. For JWTs and other JWS structures, headers such as 'jku', 'x5u', and 'jwk' must be validated against an allowlist of trusted sources. | ✓ | ✓ | ✓ | |

## V52.2 Using token content

For cryptographically secured tokens which are not self-contained tokens, validating the authenticity of the token will be sufficient. However, for a self-contained token, it is necessary to validate that the token has been presented within it's validity period and that it is meant for use by the receiving service and for the purpose for which it was presented, before making security decisions based on the content. This is to avoid insecure cross-usage between different services or with different token types from the same issuer.

Specific requirements for OAuth and OIDC are covered in the dedicated chapter.

| # | Description | L1 | L2 | L3 | CWE |
| :---: | :--- | :---: | :---: | :---: | :---: |
| **52.2.1** | [ADDED] Verify that, if a validity time span is present in the token data, the token and its content are accepted only if the verification time is within this validity time span. For example, for JWTs the claims 'nbf' and 'exp' must be verified. | ✓ | ✓ | ✓ | 613 |
| **52.2.2** | [ADDED] Verify that the service receiving a token validates the token to be the correct type and is meant for the intended purpose before accepting the token's contents. For example, only access tokens can be accepted for authorization decisions and only ID tokens can be used for proving user authentication. | ✓ | ✓ | ✓ | |
| **52.2.3** | [ADDED] Verify that the service only accepts tokens which are intended for use with that service (audience). For JWTs, this can be achieved by validating the 'aud' claim against an allowlist defined in the service. | ✓ | ✓ | ✓ | |

## References

For more information, see also:

* [OWASP Cheatsheet - JSON Web Token Cheat Sheet for Java](https://cheatsheetseries.owasp.org/cheatsheets/JSON_Web_Token_for_Java_Cheat_Sheet.html) (but has useful general guidance)
7 changes: 4 additions & 3 deletions 5.0/en/0x90-Appendix-A_Glossary.md
View file
Original file line number Diff line number Diff line change
Expand Up @@ -13,7 +13,7 @@
* **Credential Service Provider** (CSP) - Also called an Identity Provider (IdP). A source of user data which may be used as an authentication source by other applications.
* **Cross-Site Scripting** (XSS) – A security vulnerability typically found in web applications allowing the injection of client-side scripts into content.
* **Cryptographic module** – Hardware, software, and/or firmware that implements cryptographic algorithms and/or generates cryptographic keys.
* **Cryptographically Secured Token** - These tokens will generally contain claims or assertions encoded within the token structure, with cryptographic techniques such as signatures or message authentication codes (MAC) used to verify the authenticity and integrity of this data. The most common examples are SAML assertions and JWTs.
* **Cryptographically Secured Token** - A token protected using cryptographic techniques, such as digital signatures or message authentication codes (MACs), to ensure the authenticity, integrity, and in some cases the confidentiality of its data. These tokens can range from simple signed identifiers to more complex formats like JSON Web Tokens (JWTs).
* **Common Weakness Enumeration** (CWE) - A community-developed list of common software security weaknesses. It serves as a common language, a measuring stick for software security tools, and a baseline for weakness identification, mitigation, and prevention efforts.
* **Design Verification** – The technical assessment of the security architecture of an application.
* **Dynamic Application Security Testing** (DAST) - Technologies are designed to detect conditions indicative of a security vulnerability in an application in its running state.
Expand All @@ -26,7 +26,7 @@
* **Hibernate Query Language** (HQL) - A query language that is similar in appearance to SQL used by the Hibernate ORM library.
* **Inactivity Timeout** - This is the length of time a session can remain active in the absence of user interaction with the application. This is a component of session expiration.
* **Input Validation** – The canonicalization and validation of untrusted user input.
* **JSON Web Token** (JWT) - RFC 7519 defines a standard for a JSON data object made up of a header section which explains how to validate the object, a body section containing a set of claims, and a signature section which contains a digital signature which can be used to validate the contents of the body section.
* **JSON Web Token** (JWT) - RFC 7519 defines a standard for a JSON data object made up of a header section which explains how to validate the object, a body section containing a set of claims, and a signature section which contains a digital signature which can be used to validate the contents of the body section. It is a type of self-contained token.
* **Malicious Code** – Code introduced into an application during its development unbeknownst to the application owner, which circumvents the application's intended security policy. Not the same as malware such as a virus or worm!
* **Malware** – Executable code that is introduced into an application during runtime without the knowledge of the application user or administrator.
* **Multi-factor authentication** (MFA) - Authentication which includes two or more of the single factors.
Expand All @@ -38,14 +38,15 @@
* **Position-independent executable** (PIE) - A body of machine code that, being placed somewhere in the primary memory, executes properly regardless of its absolute address.
* **Public Key Infrastructure** (PKI) - An arrangement that binds public keys with respective identities of entities. The binding is established through a process of registration and issuance of certificates at and by a certificate authority (CA).
* **Public Switched Telephone Network** (PSTN) - The traditional telephone network that includes both fixed-line telephones and mobile telephones.
* **Random Session Token** - A random session token is randomly generated by the application as a session identifier to be issued to clients as part of a stateful session mechanism.
* **Reference Token** - A type of token that acts as a pointer or identifier to state or metadata stored on a server, sometimes refered to as random tokens or opaque tokens. Unlike self-contained tokens, which embed some of their relevant data within the token itself, reference tokens contain no intrinsic information, instead relying on the server for context. They may be simple random identifiers or cryptographically secured tokens.
* **Relying Party** (RP) - Generally an application which is relying on a user having authenticated against a separate authentication provider. The application relies on some sort of token or set of signed assertions provided by that authentication provider to trust that the user is who they say they are.
* **Security Assertion Markup Language** (SAML) - An open standard for single sign-on authentication based on passing signed assertions (usually XML objects) between the identity provider and the relying party.
* **Static application security testing** (SAST) - A set of technologies designed to analyze application source code, byte code and binaries for coding and design conditions that are indicative of security vulnerabilities. SAST solutions analyze an application from the “inside out” in a nonrunning state.
* **Software development lifecycle** (SDLC) - The step-by-step process by which software is developed going from the initial requirements to deployment and maintenance.
* **Security Architecture** – An abstraction of an application's design that identifies and describes where and how security controls are used, and also identifies and describes the location and sensitivity of both user and application data.
* **Security Configuration** – The runtime configuration of an application that affects how security controls are used.
* **Security Control** – A function or component that performs a security check (e.g. an access control check) or when called results in a security effect (e.g. generating an audit record).
* **Self-Contained Token** - A subset of cryptographically secured tokens which encapsulate one or more attributes that do not rely on server-side state or other external storage. The contained attributes (which are cryptographically secured), enable secure, "stateless" information exchange across systems. Examples include SAML assertions and JWTs.
* **Server-side Request Forgery** (SSRF) - An attack that abuses functionality on the server to read or update internal resources. The attacker supplies or modifies a URL, which the code running on the server will read or submit data to.
* **Single-factor authenticator** - A mechanism to check that a user is authenticated. It should either be something you know (memorized secrets, passwords, passphrases, PINs), something you are (biometrics, fingerprint, face scans), or something you have (OTP tokens, a cryptographic device such as a smart card).
* **Single Sign-on Authentication** (SSO) - This occurs when a user logs into one application and is then automatically logged into other applications without having to re-authenticate. For example, when you log into Google, you will be automatically logged into other Google services such as YouTube, Google Docs, and Gmail.
Expand Down

0 comments on commit 7c4c41d

Please sign in to comment.