| Internet-Draft | -Nonce Endpoint | -April 2024 | -
| Marco & Steele | -Expires 20 October 2024 | -[Page] | -
This document defines a Nonce Endpoint and details how a Server generates and issues opaque Nonces and how a client can learn about this endpoint to obtain the Nonce.¶
-This note is to be removed before publishing as an RFC.¶
-- The latest revision of this draft can be found at https://peppelinux.github.io/draft-demarco-oauth-nonce-endpoint/draft-demarco-oauth-nonce-endpoint.html. - Status information for this document may be found at https://datatracker.ietf.org/doc/draft-demarco-oauth-nonce-endpoint/.¶
-Source for this draft and an issue tracker can be found at - https://github.com/peppelinux/draft-demarco-oauth-nonce-endpoint.¶
-- This Internet-Draft is submitted in full conformance with the - provisions of BCP 78 and BCP 79.¶
-- Internet-Drafts are working documents of the Internet Engineering Task - Force (IETF). Note that other groups may also distribute working - documents as Internet-Drafts. The list of current Internet-Drafts is - at https://datatracker.ietf.org/drafts/current/.¶
-- Internet-Drafts are draft documents valid for a maximum of six months - and may be updated, replaced, or obsoleted by other documents at any - time. It is inappropriate to use Internet-Drafts as reference - material or to cite them other than as "work in progress."¶
-- This Internet-Draft will expire on 20 October 2024.¶
-- Copyright (c) 2024 IETF Trust and the persons identified as the - document authors. All rights reserved.¶
-- This document is subject to BCP 78 and the IETF Trust's Legal - Provisions Relating to IETF Documents - (https://trustee.ietf.org/license-info) in effect on the date of - publication of this document. Please review these documents - carefully, as they describe your rights and restrictions with - respect to this document. Code Components extracted from this - document must include Revised BSD License text as described in - Section 4.e of the Trust Legal Provisions and are provided without - warranty as described in the Revised BSD License.¶
-This specification presents a comprehensive guide to the Nonce endpoint. It describes in detail how a client can request and receive a server-generated Nonce, which is a unique, one-time use, opaque string. This document provides in-depth insights into the cryptographic methods used in generating Nonces to protect the confidentiality of the information associated with them. In addition, it serves as a resource for developers and system architects who aim to enhance the scalability, security, and efficiency of their systems.¶
-The key words "MUST", "MUST NOT", "REQUIRED", "SHALL", "SHALL NOT", "SHOULD", "SHOULD NOT", "RECOMMENDED", "NOT RECOMMENDED", -"MAY", and "OPTIONAL" in this document are to be interpreted as -described in BCP 14 [RFC2119] [RFC8174] when, and only when, they -appear in all capitals, as shown here.¶
-A random or pseudo-random number that is generated for a specific use, typically for cryptographic communication. The Nonce is used to protect against replay attacks by ensuring that a message or data cannot be reused or retransmitted. The term "Nonce" stands for "number used once" and it MUST be unique within some scope.¶
-The entity that generates and provides the Nonce. The Nonce Issuer would typically be the Authorization Server.¶
-The HTTP endpoint provided by the Nonce Issuer for the issuance of the Nonces.¶
-The Nonce Endpoint MUST satisfy the following requirements:¶
- -The Nonce MUST satisfy the following requirements:¶
-It MUST be opaque to receiving Clients.¶
-It MUST be made unguessable through the use of cryptographic randomness.¶
-It MUST be used once.¶
-It MUST have a short validity period.¶
-The Nonce Issuer MUST satisfy the following requirements:¶
-Generate a unique Nonce for each request to ensure the Nonce Issuer never produces identical Nonces, regardless of whether they occur simultaneously or at different times;¶
-Encrypt the Nonce with an encryption key that:¶
- -The audiences of the Nonces satisfies the following requirements:¶
-The servers, within the Nonce Issuer's domain, SHOULD decrypt the Nonce and access its decrypted contents. No other entity might decrypt or know the decrypted contents of the Nonce.¶
-When a Client needs a Nonce, it sends an HTTP GET request to the Nonce Endpoint.¶
-Below is a non normative example of the HTTP Request made by a Client to the Nonce Endpoint.¶
--GET /nonce HTTP/1.1 -Host: server.example.com -¶ -
Below a sequence diagram represents the proactive approach of obtaining a Nonce from the Nonce endpoint -before making a request to the server, thus avoiding the error case where the server requires a -nonce that the Client did not provide. This approach illustrated below ensures a smoother -interaction flow and enhances the understanding of the Nonce acquisition process.¶
--Client Nonce Endpoint Server - | | | - |--- GET /nonce ----------->| | - |<-- Nonce -----------------| | - | | | - |--- Request with Nonce --->|----------------------->| - | | |-- Check - > - | | |<-- OK ----| - | |<-----------------------| - | | | -¶ -
The Nonce Endpoint provides a Nonce to the Client, encapsulated within a JSON object [RFC7159].
-The response MUST use the HTTP Header Content-Type value set to application/json and MUST provide in the response message a JSON object with the member nonce.¶
Below is a non-normative example of the response given by a Nonce Endpoint:¶
-
-HTTP/1.1 200 OK
-Content-Type: application/json
-
-{
- "nonce": "d2JhY2NhbG91cmVqdWFuZGFt"
-}
-¶
-When an Authorization Server requires the use of a Nonce in the request for a specific resource and the Client does not provide it in its request,
-the Authorization Server MUST return an HTTP response with the HTTP status code 400 and an error field with the value set to "nonce_required".¶
This response MUST also contain the Nonce-Endpoint-URI HTTP header, with the value set to the URL corresponding to the Nonce Endpoint, where the Client SHOULD request and fetch a new Nonce. Once the Nonce is received, the Client MAY renew the request to the Authorization Server, including the obtained Nonce.¶
Below is a non-normative example of an error response issued by an Authorization Server that requires the Nonce in the Client request, the response informs the Client about the Nonce Endpoint where the Nonce should be requested:¶
-
-HTTP/1.1 400 Bad Request
-Nonce-Endpoint-URI: https://server.example.org/nonce-endpoint
-
-{
- "error": "nonce_required",
- "error_description":
- "Authorization server requires the nonce in the request"
-}
-¶
-In cases where, for some reasons, a correctly issued Nonce can no longer be considered valid by the Authorization Server that receives it, the Authorization Server MUST return the generic error "nonce_required" reporting the same description as "error_description", as if the Nonce had not been received. The cases when an issued Nonce is considered no longer valid MAY be caused by the rotation of the encryption keys, its expiration or other specific conditions internal to an implementation.¶
The decrypted Nonce payload MAY use different formats and encodings, according to the different implementation requirements and contain any kind of implementation-specific claims, such as the issuance time, the time of expiration, the audiences and others where needed.¶
-Below are provided some non-normative examples, describing how a decrypted and JSON serialized Nonce payload MAY appear:¶
-
-{
- "jti": "0452767d-549d-4765-bd43-a0bcc2a6659a",
- "iss": "https://server.example.org",
- "iat": 1615908701,
- "exp": 1615995101,
- "source_endpoint": "https://server.example.org/nonce-endpoint",
- "aud": [
- "https://service.example.com/endpoint",
- "https://another.example.com/cb"
- ]
-}
-¶
-Please note that the values represented in the previous examples are informative.¶
-In any case, the payload MUST include some unique value ("jti" on the example above), typically generated using a pseudo-random number generator with sufficient entropy [RFC4086], to ensure that the encrypted digest (the actual Nonce) is also unique.¶
The Nonce Endpoint MUST be protected by TLS to prevent eavesdropping and man-in-the-middle attacks, therefore the practices defined in [BCP195] should be followed.¶
-The Nonce Issuer MUST securely generate and store the encryption key used to encrypt the Nonce. The robustness of the encryption key plays a crucial role in the security of the Nonce Endpoint. The following considerations MUST be taken into account:¶
-Key Strength: The cryptographic key used to encrypt the Nonce requires sufficient length to withstand brute-force attacks. A key length of 256 bits has been proposed as a common practice to ensure a minimum level of security.¶
-Key Management: The cryptographic key requires secure management, which includes secure generation, storage, and revocation. Access to the key necessitates strict control, with access granted only to authorized entities.¶
-Key Rotation: Regular key rotation is a good practice to mitigate the risk of key compromise. The frequency of key rotation depends on the specific requirements and threat model, but a common practice is to rotate keys frequently.¶
-Randomness: To assure the randomness of the cryptographic key, it requires the usage of a safe random number generator. Attackers can simply guess predictable keys.¶
-Secure Transmission: If the cryptographic key needs to be transmitted over a network and within the Nonce Issuer domain, it requires the usage of secure protocols such as TLS.¶
-Backup and Recovery: Cryptographic keys require secure backup and recovery mechanisms. This ensures that the key can be retrieved in the event of its loss while also prohibiting unauthorised access to the backup.¶
-The security of the Nonce Endpoint is only as strong as the security of the encryption key. Therefore, proper key management practices are essential.¶
-This section provides some thought about the main differences and scopes of the Nonce in compared to the jti claim defined in [RFC7519].¶
Both jti and Nonces are used to prevent replay attacks, however Nonces offer more implementation flexibility and are considered best practice. They can be created and managed stateless (e.g., by issuing the hmac over the current time as the Nonce), as this document outlines.¶
The main differences between the use of the jti and the Nonces can be summarized as follows:¶
Generation: Nonces are generated by the server, while jti is generated by the Client.¶
Storage: Nonces can be self-authenticating and self-contained and therefore need not be stored. A common way to achieve this is for the Nonce to contain content encrypted to the Authorization Server that creates it. On the other hand, checking jti properly definitely requires a store that is shared across all domains that the associated JWT can be presented in.¶
Lifetime: The life span difference between a Nonce and a jti is significant. Nonces are kept just until the Client responds, which happens practically immediately after they are obtained, resulting in a very short lifespan. A jti, on the other hand, must be stored until the expiration window of its associated JWT expires, which is a substantially longer length than that of a Nonce.¶
Security: Nonces prevent replay attacks by ensuring that the proof of possession is fresh. On the other hand, jti does not guarantee freshness and using client-generated timestamps has problems, even for non-attacking Clients (e.g. devices with incorrect time-zones or daylight saving settings).¶
This document has no IANA actions.¶
-| Nonce Endpoint | -plain text | -same as main | -
The entity that generates and provides the Nonce. The Nonce Issuer would typically be the Authorization Server.¶
+The entity that generates and provides the Nonce.¶
Below is an example of how the Authorization Server Metadata might include the nonce_endpoint:¶
Below is an example of how an OAuth 2.0 Authorization Server Metadata might include the nonce_endpoint:¶
{
@@ -1396,10 +1396,10 @@
8. Nonce Endpoint Discovery
-
When an Authorization Server requires the use of a Nonce in the request for a specific resource and the Client does not provide it in its request,
-the Authorization Server MUST return an HTTP response with the HTTP status code 400 and an error field with the value set to "nonce_required".¶
-This response MUST also contain the Nonce-Endpoint-URI HTTP header, with the value set to the URL corresponding to the Nonce Endpoint, where the Client SHOULD request and fetch a new Nonce. Once the Nonce is received, the Client MAY renew the request to the Authorization Server, including the obtained Nonce.¶
-Below is a non-normative example of an error response issued by an Authorization Server that requires the Nonce in the Client request, the response informs the Client about the Nonce Endpoint where the Nonce should be requested:¶
+When a server requires the use of a Nonce in the request for a specific resource and the Client does not provide it in its request,
+the server MUST return an HTTP response with the HTTP status code 400 and an error field with the value set to "nonce_required".¶
+This response MUST also contain the Nonce-Endpoint-URI HTTP header, with the value set to the URL corresponding to the Nonce Endpoint, where the Client SHOULD request and fetch a new Nonce. Once the Nonce is received, the Client MAY renew the request to the server, including the obtained Nonce.¶
+Below is a non-normative example of an error response issued by an server that requires the Nonce in the Client request, the response informs the Client about the Nonce Endpoint where the Nonce should be requested:¶
HTTP/1.1 400 Bad Request
@@ -1408,11 +1408,11 @@
{
"error": "nonce_required",
"error_description":
- "Authorization server requires the nonce in the request"
+ "Server requires the nonce in the request"
}
¶
-In cases where, for some reasons, a correctly issued Nonce can no longer be considered valid by the Authorization Server that receives it, the Authorization Server MUST return the generic error "nonce_required" reporting the same description as "error_description", as if the Nonce had not been received. The cases when an issued Nonce is considered no longer valid MAY be caused by the rotation of the encryption keys, its expiration or other specific conditions internal to an implementation.¶
+In cases where, for some reasons, a correctly issued Nonce can no longer be considered valid by the server that receives it, the server MUST return the generic error "nonce_required" reporting the same description as "error_description", as if the Nonce had not been received. The cases when an issued Nonce is considered no longer valid MAY be caused by the rotation of the encryption keys, its expiration or other specific conditions internal to an implementation.¶
The main differences between the use of the jti and the Nonces can be summarized as follows:¶
Generation: Nonces are generated by the server, while jti is generated by the Client.¶
Generation: Nonces and jti can be are generated both by the server and the client.¶
Storage: Nonces can be self-authenticating and self-contained and therefore need not be stored. A common way to achieve this is for the Nonce to contain content encrypted to the Authorization Server that creates it. On the other hand, checking jti properly definitely requires a store that is shared across all domains that the associated JWT can be presented in.¶
Lifetime: The life span difference between a Nonce and a jti is significant. Nonces are kept just until the Client responds, which happens practically immediately after they are obtained, resulting in a very short lifespan. A jti, on the other hand, must be stored until the expiration window of its associated JWT expires, which is a substantially longer length than that of a Nonce.¶
Lifetime: The life span difference between a Nonce and a jti is significant. Nonces are kept just until the Client responds, which happens practically immediately after they are obtained, resulting in a very short lifespan. A jti, on the other hand, must be stored until the expiration window of its associated JWT expires, which is a substantially longer length than that of a Nonce.¶
Security: Nonces prevent replay attacks by ensuring that the proof of possession is fresh. On the other hand, jti does not guarantee freshness and using client-generated timestamps has problems, even for non-attacking Clients (e.g. devices with incorrect time-zones or daylight saving settings).¶
Freshness: Nonces prevent replay attacks by ensuring that the proof of possession is fresh. On the other hand, jti does not guarantee freshness and using client-generated timestamps has problems, even for non-attacking Clients (e.g. devices with incorrect time-zones or daylight saving settings).¶
| Nonce Endpoint | -plain text | -diff with main | -
| Nonce Endpoint | -plain text | -diff with main | -