Grant Negotiation and Authorization Protocol Resource Server Connections
Extracted elements (29)
The specification deliberately separates the access token model (Section 2.1) from the wire format (Section 2.2) and the introspection API (Section 3.3), because both structured and reference-style tokens are valid and can be combined: structured tokens carry one class of information while introspection carries another. This avoids mandating a single approach across all GNAP deployments.
Token chaining (Section 4) is designed so the RS uses the standard GNAP grant endpoint rather than a bespoke chaining API. Because the RS acts as its own client instance, the same request and response structure applies, limiting the scope of new protocol surface area.
The resource_reference returned by the AS from resource set registration is opaque to both the RS and the client. Implementations that embed structured data or predictable patterns in resource references risk creating hidden dependencies that break separation of concerns between GNAP roles.
A client instance MUST take steps to differentiate continuation and token management access tokens from regular RS-bound access tokens, for example by storing them separately, to prevent using them at wrong endpoints.
In all places where the token format is listed explicitly (discovery, resource registration, introspection response), it MUST be one of the registered values in the 'GNAP Token Formats' registry.
The AS MUST separate AS-specific access tokens (continuation, token management, resource server management) from other access tokens used at RSs, using flags, special internal access rights, or other means. The AS MUST NOT return an active value of true for AS-specific access tokens to the RS.
The AS MUST validate the access token value and determine if the token is active, taking all provided request parameters into account. If the AS is unable to process part of the request (e.g., an unrecognized access field), the AS MUST NOT indicate the token as active.
The introspection response MUST NOT include the access token value itself. The access array in the response MAY be filtered for the identified RS, including being an empty array indicating no explicit access rights can be disclosed.
The RS MUST identify itself with its own key and sign the resource registration request. If the AS does not support any of the RS's requested token formats or introspection, the AS MUST return an error.
Unless otherwise specified, the RS MUST protect its calls to the AS using any of the signature methods defined in Section 7 of [GNAP]. The RS MAY identify itself by key value or by reference (instance identifier).
When deriving a downstream token, the RS MUST identify itself with its own key in the client field and sign the request. The AS MUST determine that the token being presented is appropriate for use at the RS making the token chaining request.
Access token contents may include personal information (e.g., medical record numbers) that gets exposed to every RS that validates the token, even RSs with no need for that data. Mitigations include per-RS token sections in structured formats or limited introspection responses scoped to each RS.
An RS that reveals its protecting AS (e.g., via discovery) allows an unauthorized client to infer facts about the protected resource—such as associating a medical record with a personal AS—without accessing the resource itself.
When an RS calls the introspection endpoint, the AS learns which tokens are being used at which RSs, enabling the AS to infer end-user behavior patterns that it would not otherwise observe. This is an inherent disclosure in the introspection model.
A GNAP AS offering RS-facing services publishes a discovery document at the well-known path /.well-known/gnap-as-rs (same scheme and authority as the grant request endpoint). The JSON document includes fields for grant_request_endpoint (REQUIRED), introspection_endpoint, token_formats_supported, resource_registration_endpoint, and key_proofs_supported.
An RS can derive a downstream token for a chained RS by calling the AS's grant endpoint with the existing_access_token field set to the incoming token value and identifying itself in the client field with its own key. The AS issues a new, scoped token for use at the secondary RS.
The RS can register a resource set with the AS by POSTing an access array and resource_server identifier to the resource_registration_endpoint. The AS responds with a resource_reference string that the RS can share with clients as a compact access rights reference.
Token introspection allows an RS to validate that an access token was issued by the AS, is currently valid, has not been revoked, and is appropriate for the calling RS. The RS signs the introspection request with its own key (not the client or token key) and sends the token value in the access_token field.
IANA created the 'GNAP Resource Set Registration Request Parameters' and 'GNAP Resource Set Registration Response Parameters' registries (Expert Review policy). Initial request fields: access, resource_server, token_formats_supported, token_introspection_required. Initial response fields: resource_reference, instance_id, introspection_endpoint.
IANA created the 'GNAP RS-Facing Discovery Document Fields' registry (Expert Review policy) and the 'GNAP RS-Facing Error Codes' registry (Specification Required policy). Initial error codes are invalid_request, invalid_resource_server, and invalid_access.
IANA created the 'GNAP Token Formats' registry (Specification Required policy) with initial entries: jwt-signed, jwt-encrypted, macaroon, biscuit, and zcap. Each entry has Name, Status, Description, and Reference fields.
IANA created the 'GNAP Token Introspection Request' registry (Specification Required policy) and the 'GNAP Token Introspection Response' registry, both for extensible introspection message fields. Initial request fields: access_token, proof, resource_server, access. Initial response fields include active, access, key, flags, exp, iat, nbf, aud, sub, iss, instance_id.
All RS-to-AS and client-to-RS requests over untrusted networks MUST be made over TLS as per BCP 195 to prevent manipulation and interception. This applies to all requests in the RS-facing API.
Caching token validation results trades performance against liveness: a cached revoked token could be accepted during the cache window. Key proof validation results MUST NOT be cached across separate requests, as aspects of each call may vary.
Introspection responses should be limited to information relevant to the requesting RS, following the principle of least disclosure. A compromised RS could otherwise learn about the broader system by receiving the full token contents intended for other RSs.
Since the RS sees the raw token value, a compromised RS can leak it to an attacker. Bearer tokens and symmetric-key-bound tokens are especially at risk because the RS holds all information needed to replay the token. RSs should exchange incoming tokens for derived, RS-specific tokens as described in Section 4.
Symmetric key binding divulges the full key to the RS via introspection, giving the RS the same token-reuse capability as a bearer token. Symmetric keys should only be used when the RS can be fully trusted not to create new requests with the presented token.
The RS must validate that an access token is intended for this RS (audience restriction), is presented with the appropriate bound key, identifies an authorized subject, and was issued by a trusted AS. Validating key proofing alone is insufficient; an attacker with a compromised key could otherwise make arbitrary calls.
The introspection request is a JSON object with fields: access_token (string, REQUIRED), proof (string, RECOMMENDED), resource_server (object/string, REQUIRED), and access (array, OPTIONAL). The response includes active (boolean, REQUIRED) and, if active, fields including access, key, flags, exp, iat, nbf, aud, sub, iss, and instance_id.