Grant Negotiation and Authorization Protocol (GNAP)
Extracted elements (32)
GNAP is a stateful protocol by design: the grant request moves through defined states (Processing, Pending, Approved, Finalized) managed by the AS. Stateless AS deployments must implement secure, deterministic state management without relying on client software to track state, since clients are not trusted to maintain authoritative grant state.
GNAP is explicitly not an extension of OAuth 2.0 and is not intended to be directly compatible with it. GNAP addresses use cases that OAuth 2.0 cannot easily handle (such as key-bound tokens by default, rich delegation negotiation, and multi-party authorization), while allowing GNAP and OAuth 2.0 to coexist in parallel deployments with defined mapping paths.
GNAP separates the roles of end user and resource owner as distinct concepts that may or may not be fulfilled by the same person. This separation enables advanced use cases such as cross-user authentication (where a call-center agent requests access to a customer's data) and asynchronous authorization without assuming the end user is always the authorizing party.
GNAP provides defined mechanisms to map OAuth 2.0 concepts such as scopes and client IDs into GNAP constructs (Appendix B.5 and Appendix A). This allows deployments to support both protocols in parallel and facilitates migration from existing OAuth 2.0 systems to GNAP.
All Subject Identifiers in the sub_ids array of a subject information request MUST identify the same subject. If sub_ids is omitted, the AS SHOULD assume requests are about the current user and SHOULD require direct interaction or proof of presence before releasing information.
Flag values in an access token request MUST NOT be included more than once. If a flag is duplicated, the AS MUST return an invalid_flag error.
If the AS includes a label in the token request, the AS MUST include the same label in the token response. The label value is opaque to the AS and not intended to be exposed to or used by the end user.
If the bearer flag is omitted from an access token request, the resulting access token is bound to the key used by the client instance in the request (or that key's most recent rotation), and the token MUST be presented using the same key and proofing method.
The grant request MUST be sent as a JSON object in the body of an HTTP POST to the AS grant endpoint with Content-Type application/json. A key proofing mechanism MAY define an alternative content type as long as the content is formed from the JSON object.
When requesting multiple access tokens, each object in the array MUST include the label field and all label values MUST be unique within the request. If any label is missing or duplicated, the AS MUST return an invalid_request error.
When sending a new grant request, the client instance MUST identify itself by including its client information in the client field and MUST sign the request with its unique key as described in Section 7.3. The client field is not sent or accepted for continuation requests.
GNAP raises correlation risks: clients can correlate user activity across RS interactions using access tokens; RS can correlate across requests using the same token; AS can correlate all activity since it issues all tokens. The AS SHOULD issue distinct tokens for different RS contexts and SHOULD minimize information shared with each party.
Subject Identifiers returned to client instances can enable surveillance and tracking of users. The AS SHOULD allow users to control what subject information is released, SHOULD use pairwise identifiers where possible, and SHOULD NOT release more information than necessary for the declared purpose.
A GNAP grant request JSON object contains: access_token (REQUIRED if requesting API access), subject (REQUIRED if requesting subject information), client (REQUIRED, identifies the client instance and its key), user (OPTIONAL, identifies the end user), and interact (REQUIRED if interaction is supported). Extensions may add fields via the GNAP Grant Request Parameters registry.
An access token request object contains: access (array of objects/strings, REQUIRED, describes rights at the RS), label (string, REQUIRED for multiple-token requests, OPTIONAL otherwise), and flags (array of strings, OPTIONAL). The bearer flag requests a bearer token; absence means the token is key-bound.
GNAP defines four interaction start modes: redirect (client redirects user to arbitrary URI), app (client launches application URI), user_code (client displays short user code for entry at a known URI), and user_code_uri (client displays short code and URI). Each mode indicates a different capability of the client instance.
Interaction finish methods allow the AS to signal to the client instance that interaction is complete. Methods include redirect (browser redirect to callback URI with interaction reference and hash) and push (direct HTTP request to client's callback URI). Both include a client-supplied nonce and the AS-provided finish nonce for hash computation.
Key formats supported in GNAP include: jwk (JSON Web Key per RFC 7517), cert (X.509 certificate), cert#S256 (certificate thumbprint), and did (Decentralized Identifier). The key object also contains the required proof field indicating the proofing mechanism.
Key proofing methods defined for securing requests from the client instance include: httpsig (HTTP Message Signatures per RFC 9421), mtls (Mutual TLS), jwsd (Detached JWS), and jws (Attached JWS). The proofing method is declared in the key object's proof field.
The client instance field contains: key (object/string, REQUIRED, the client's public key or reference used to sign the request), class_id (string, OPTIONAL, identifies the client software class), and display (object, OPTIONAL, displayable information shown to the RO during authorization).
The grant continuation mechanism allows the client instance to continue, update, or revoke a pending grant by calling the continuation URI using the continuation access token. The continuation access token is always bound to the client instance's key and must be presented with the appropriate proofing method.
The subject information request object may contain: sub_id_formats (array, REQUIRED if Subject Identifiers are requested), assertion_formats (array, REQUIRED if assertions are requested, values include id_token and saml2), and sub_ids (array of Subject Identifier objects, OPTIONAL, identifies the subject for which information is requested).
RFC 9635 creates 16 IANA registries for GNAP: Grant Request Parameters, Access Token Flags, Subject Information Request Fields, Assertion Formats, Client Instance Fields, Client Instance Display Fields, Interaction Start Modes, Interaction Finish Methods, Interaction Hints, Grant Response Parameters, Interaction Mode Responses, Subject Information Response Fields, Error Codes, Key Proofing Methods, Key Formats, and Authorization Server Discovery Fields.
The GNAP Error Codes registry (Section 10.15) is created for AS error responses with initial values including: invalid_request, invalid_client, invalid_interaction, invalid_flag, invalid_rotation, key_rotation_not_supported, invalid_continuation, user_denied, request_denied, unknown_user, unknown_request, too_fast, too_many_attempts, and request_cancelled.
The GNAP Key Proofing Methods registry (Section 10.16) is created with initial values: httpsig, mtls, jwsd, and jws. Each entry requires a unique name, specification pointer, and notes on the proofing mechanism.
All GNAP protocol interactions MUST be protected by TLS. Bearer access tokens in particular are sensitive to interception, and the AS MUST enforce TLS on all endpoints. Key-bound tokens provide additional protection against token theft even when transport security is compromised.
An attacker can attempt Denial of Service by sending many polling continuation requests to the AS. The AS SHOULD enforce rate limiting, return the too_fast error when a client polls before the indicated wait time, and use the too_many_attempts error to signal excessive requests.
AS-mix-up attacks (Section 11.12) occur when a client sends a grant request to a malicious AS that then impersonates a legitimate AS. Clients MUST use the grant endpoint URI as the AS identifier and MUST validate that all components of the response (including continuation URIs) are from the expected AS.
Bearer access tokens carry inherent risk because any party possessing the token can use it. The AS SHOULD use short expiration times for bearer tokens, and implementations SHOULD prefer key-bound tokens where possible. Stolen bearer tokens can be replayed by an attacker without limitation until expiry.
Callback URI manipulation (Section 11.18) is a risk where an attacker substitutes or modifies the client's redirect URI. Clients MUST validate that incoming redirect parameters match those stored in their session, and the interaction hash provides cryptographic binding between the outgoing request and incoming callback.
The interaction hash (Section 4.2.3) is calculated from the interaction nonce, finish nonce, interaction reference, and grant endpoint URI, and MUST be validated by the client before continuing a grant after redirect-based interaction. This prevents interception and replay of redirect callbacks by a third party.
A GNAP grant request transitions through four states: _Processing_ (initial state when received or updated), _Pending_ (interaction/approval required, no tokens issued), _Approved_ (access tokens and subject info may be returned), and _Finalized_ (terminal state — no new tokens, interactions, or updates possible). The AS manages the authoritative state; clients track their own view.