Movatterモバイル変換

RFC 9767	GNAP RS Connections	April 2025
Richer & Imbault	Standards Track	[Page]

2.Access Tokens

Access tokens are used as a mechanism for an AS to provide a client instance limited access to an RS. These access tokens are artifacts representing a particular set of access rights granted to the client instance to act on behalf of the RO. While the format of access tokens varies in different systems (see discussion inSection 2.2), the concept of an access token is consistent across all GNAP systems.¶

2.1.General-Purpose Access Token Model

The core GNAP specification[GNAP] focuses on the relationship between the client and the AS. Since the access token is opaque to the client, the core specification does not define a token model. However, the AS will need to create tokens, and the RS will need to understand tokens. To facilitate a level of structural interoperability, a common access token model is presented here. Access tokens represent a common set of aspects across different GNAP deployments. This list is not intended to be universal or comprehensive but rather serves as guidance to implementers in developing data structures and associated systems across a GNAP deployment. These data structures are communicated between the AS and RS by using either a structured token or an API-like mechanism such as token introspection (seeSection 3.3).¶

This general-purpose data model does not assume either approach; in fact, both approaches can be used together to convey different pieces of information. Where possible, mappings to the JSON Web Token (JWT)[JWT] standard format are provided for each item in the model.¶

2.1.1.Value

All access tokens have avalue, which is the string that is passed on the wire between parties.In order for different access tokens to be differentiated at runtime, the value of a token needs to be uniquewithin a security domain (such as all systems controlled by an AS). Otherwise, two separate tokens would be confused for each other, which would lead to security issues.The AS chooses the value, which can be structured (seeSection 2.2) or unstructured. When the token isstructured, the token value also has aformat known to the AS and RS, and the other itemsin this token model are contained within the token's value in some fashion.When the token is unstructured, the values are usually retrieved by the RS using a service such as token introspection described inSection 3.3.¶

The access token value is conveyed in thevalue field of anaccess_token response; seeSection 3.2 of [GNAP].¶

The format and content of the access token value is opaque to the client software.While the client software needs to be able to carry and present the access tokenvalue, the client software is never expected nor intended to be able to understandthe token value itself.¶

If structured tokens like those in[JWT] are used, the value of the token might not be stored by the AS. Instead,a token identifier can be used along with protection by an AS-generated signature to validate andidentify an individual token.¶

2.1.2.Issuer

The access token is issued by the AS as defined in[GNAP]. The AS willneed to identify itself in order to allow an RS to recognize tokens that the AS has issued, particularlyin cases where tokens from multiple different ASs could be presented to the same RS.¶

This information is not usually conveyed directly to the client instance, since the client instance should know this information based on where it receives the token from.¶

In the payload of a JSON Web Token[JWT] or a token introspection response, this corresponds to theiss claim.¶

2.1.3.Audience

The access token is intended for use at one or more RSs. The AS can list a token's intended RSs to allow each RS to ensure that the RS is not receiving a token intended for someone else.The AS and RS have to agree on the nature of any audience identifiers represented by the token,but the URIs of the RS are a common pattern.¶

In the payload of a JSON Web Token[JWT] or token introspection response, this corresponds to theaud claim.¶

In cases where more complex access is required, thelocation field of objects in theaccessarray can also convey audience information.In such cases, the client instance might need to know the audience information in order to differentiate betweenpossible RSs to present the token to.¶

2.1.4.Key Binding

Access tokens in GNAP are bound to the client instance's registered or presented key, except incases where the access token is a bearer token. For all tokens bound to a key, the AS and RS need tobe able to identify which key the token is bound to; otherwise, an attacker could substitute theirown key during presentation of the token. In the case of an asymmetric algorithm, theAS and RS need to know only the public key, while the client instance will also need to know the privatekey in order to present the token. In the case of a symmetric algorithm, all partieswill need to either know or be able to derive the shared key.¶

The source of this key information can vary depending on deployment decisions. For example, an AScould decide that all tokens issued to a client instance are always bound to that client instance's current key.When the key needs to be dereferenced, the AS looks up the client instance to which the token was issuedand finds the key information there. Alternatively, the AS could bind each token to a specific key that is managed separately from client instanceinformation. In such a case, the AS determines the key information directly. This approach allows the clientinstance to use a different key for each request or allows the AS to issue a key for the client instanceto use with the particular token.¶

In all cases, the key binding also includes a proofing mechanism, along with any parameters needed for thatmechanism such as a signing or digest algorithm. If such information is not included with the proofing key, an attacker couldpresent a token with a seemingly valid key using an insecure and incorrect proofing mechanism.¶

This value is conveyed to the client instance in thekey field of theaccess_token response inSection 3.2 of [GNAP].Since the common case is that the token is bound to the client instance's registered key, this field can be omitted in this casesince the client will be aware of its own key.¶

In the payload of a JSON Web Token[JWT], this corresponds to thecnf (confirmation) claim. In a token introspection response, this corresponds to thekey claim.¶

In the case of a bearer token, all parties need to know that a token has no key bound to it and will therefore reject any attempts to use the bearer token with a key in an undefined way.¶

2.1.5.Flags

GNAP access tokens can have multiple associated data flags that indicate special processing or considerations for a token. For example, the data flags can indicate whether a token is a bearer token or should be expected to be durable across grant updates.¶

The client can request a set of flags using theflags field of theaccess_token grant request parameter inSection 2.1.1 of [GNAP].¶

These flags are conveyed from the AS to the client in theflags field of theaccess_token section of the grant response inSection 3.2 of [GNAP].¶

For token introspection, flags are returned in theflags field of the response.¶

2.1.6.Access Rights

Access tokens are tied to a limited set of access rights. These rights specify in some detail what the tokencan be used for, how it can be used, and where it can be used. The internal structure of access rights is detailed inSection 8 of [GNAP].¶

The access rights associated with an access token are calculated from the rights available to the clientinstance making the request, the rights available to be approved by the RO, the rights actually approvedby the RO, and the rights corresponding to the RS in question. The rights for a specific access tokenare a subset of the overall rights in a grant request.¶

These rights are requested by the client instance in theaccess field of theaccess_token request; seeSection 2.1 of [GNAP].¶

The rights associated with an issued access token are conveyed to the client instance in theaccess field of theaccess_token response inSection 3.2 of [GNAP].¶

In token introspection responses, access rights correspond to theaccess claim.¶

2.1.7.Time Validity Window

The access token can be limited to a certain time window outside of which it is no longervalid for use at an RS. This window can be explicitly bounded by an expiration time and anot-before time, or it could be calculated based on the issuance time of the token. For example,an RS could decide that it will accept tokens for most calls within an hour of a token'sissuance, but only within five minutes of the token's issuance for certain high-value calls.¶

Since access tokens could be revoked at any time for any reason outside of a client instance's control,the client instance often does not know or concern itself with the validity time window ofan access token. However, this information can be made available to it by using theexpires_in fieldof an access token response; seeSection 3.2 of [GNAP].¶

The issuance time of the token is conveyed in theiat claim in the payload of a JSON Web Token[JWT] or a token introspection response.¶

The expiration time of a token, after which it is to be rejected, is conveyed in theexp claim in the payload of a JSON Web Token[JWT] or a token introspection response.¶

The starting time of a token's validity window, before which it is to be rejected, is conveyed in thenbf claim in the payload of a JSON Web Token[JWT] or a token introspection response.¶

2.1.8.Token Identifier

Individual access tokens often need a unique internal identifier to allow the AS to differentiatebetween multiple separate tokens. This value of the token can often be used as theidentifier, but in some cases, a separate identifier is used.¶

This separate identifier can be conveyed in thejti claim in the payload of a JSON Web Token[JWT] or a token introspection response.¶

This identifier is not usually exposed to the client instance using the token, because the clientinstance only needs to use the token by value.¶

2.1.9.Authorizing Resource Owner

Access tokens are approved on behalf of a resource owner (RO). The identity of this RO can be used bythe RS to determine exactly which resource to access or which kinds of access to allow. For example,an access token used to access identity information can hold a user identifier to allow the RS todetermine which profile information to return. The nature of this information is subject to agreementby the AS and RS.¶

This corresponds to thesub claim in the payload of a JSON Web Token[JWT] or a token introspection response.¶

Detailed RO information is not returned to the client instancewhen an access token is requested alone, and in many cases, returningthis information to the client instance would be a privacy violation on the part of the AS. Since theaccess token represents a specific delegated access, the client instance needs only to use the tokenat its target RS. Following the profile example, the client instance does not need to knowthe account identifier to get specific attributes about the account represented by the token.¶

GNAP does allow for the return of subject information separately from the access token, in the formof identifiers and assertions. These values are returned directly to the client separately from anyaccess tokens that are requested, though it's common that they represent the same party.¶

2.1.10.End User

The end user is the party operating the client software. The client instance can facilitate the end userinteracting with the AS in order to determine the end user's identity, gather authorization, and providethe results of that information back to the client instance.¶

In many instances, the end user is the same party as the resource owner. However, in some cases,the two roles can be fulfilled by different people, where the RO is consulted asynchronously.The token model should be able to reflect these kinds of situations by representing the end userand RO separately.For example, an end user can request a financial payment, but the RO is the holder of the accountthat the payment would be withdrawn from. The RO would be consulted for approval by the AS outsideof the flow of the GNAP request. A token in such circumstances would need to show both theRO and end user as separate entities.¶

2.1.11.Client Instance

Access tokens are issued to a specific client instance by the AS. The identity of this instance canbe used by the RS to allow specific kinds of access or other attributes about the access token.For example, an AS that binds all access tokens issued to a particular client instance to thatclient instance's most recent key rotation would need to be able to look up the client instancein order to find the key binding detail.¶

This corresponds to theclient_id claim in the payload of a JSON Web Token[JWT] or theinstance_id field of a token introspection response.¶

The client is not normally informed of this information separately, since a client instance canusually correctly assume that it is the client instance to which a token thatit receives was issued.¶

2.1.12.Label

When multiple access tokens are requested or a client instance uses token labels, the partieswill need to keep track of which labels were applied to each individual token. Since labels canbe reused across different grant requests, the token label alone is not sufficient touniquely identify a given access token in a system. However, within the context of a grantrequest, these labels are required to be unique.¶

A client instance can request a specific label using thelabel field of anaccess_token request; seeSection 2.1 of [GNAP].¶

The AS can inform the client instance of a token's label using thelabel field of anaccess_token response; seeSection 3.2 of [GNAP].¶

This corresponds to thelabel field of a token introspection response.¶

2.1.13.Parent Grant Request

All access tokens are issued in the context of a specific grant request from a client instance. Thegrant request itself represents a unique tuple of:¶

The AS processing the grant request¶
The client instance making the grant request¶
The RO (or set of ROs) approving the grant request (or needing to approve it)¶
The access rights granted by the RO¶
The current state of the grant request, as defined inSection 1.5 of [GNAP]¶

The AS can use this information to tie common information to a specific token. For instance,instead of specifying a client instance for every issued access token for a grant, the AScan store the client information in the grant itself and look it up by reference from theaccess token.¶

The AS can also use this information when a grant request is updated. For example, if the clientinstance asks for a new access token from an existing grant, the AS can use this link to revokeolder non-durable access tokens that had been previously issued under the grant.¶

A client instance will have its own model of an ongoing grant request, especially if thatgrant request can be continued using the API defined inSection 5 of [GNAP] where severalpieces of statefulness need to be kept in hand. The client instance might need to keep anassociation with the grant request that issued the token in case the access token expires ordoes not have sufficient access rights, so that the client instance can get a new accesstoken without having to restart the grant request process from scratch.¶

Since the grant itself does not need to be identified in any of the protocol messages, GNAPdoes not define a specific grant identifier to be conveyed between any parties in the protocol.Only the AS needs to keep an explicit connection between an issued access token and theparent grant that issued it.¶

2.1.14.AS-Specific Access Tokens

When an access token is used for the grant continuation API defined inSection 5 of [GNAP] (the continuation access token),the token management API defined inSection 6 of [GNAP] (the token management access token),or the RS-facing API defined inSection 3 (the resource server management access token),the ASMUST separate these access tokens from other access tokens used at one or more RSs. The AS cando this through the use of a flag on the access token data structure, by using a special internalaccess right, or any other means at its disposal. Just like other access tokens in GNAP,the contents of these AS-specific access tokens are opaque to the software presenting the token. Unlike other access tokens, the contents of these AS-specific access tokens are also opaque to the RS.¶

The client instance is given continuation access tokens only as part of thecontinue fieldof the grant response inSection 3.1 of [GNAP].The client instance is given token management access tokens only as part of themanage fieldof the grant response inSection 3.2.1 of [GNAP].The means by which the RS is given resource server management access tokens is out ofscope of this specification, but methods could include preconfiguration of the token value with the RS software or granting the access token through a standard GNAP process.¶

For continuation access tokens and token management access tokens,a client instanceMUST take steps to differentiate these special-purpose access tokens fromaccess tokens used at one or more RSs.To facilitate this, a client instance can store AS-specific access tokens separately fromother access tokens in order to keep them from being confused with each other and used at thewrong endpoints.¶

An RS should never see an AS-specific access token presented, so any attempts to process oneMUSTfail. When introspection is used, the ASMUST NOT return anactive value oftrue forAS-specific access tokens to the RS. If an AS implements its protected endpoints in such a waythat it uses token introspection internally, the ASMUST differentiate these AS-specific access tokensfrom those issued for use at an external RS.¶

2.2.Access Token Formats

When the AS issues an access token for use at an RS, the RSneeds to have some means of understanding what the access token is forin order to determine how to respond to the request. The core GNAPprotocol makes neither assumptions nor demands on the format or contentsof the access token, and in fact, the token format and contents are opaqueto the client instance. However, such token formats can be the topic of agreementsbetween the AS and RS.¶

Self-contained structured token formats allow for the conveyanceof information between the AS and RS without requiring the RS tocall the AS at runtime as described inSection 3.3. Structured tokenscan also be used in combination with introspection, allowing the token itselfto carry one class of information and the introspection response to carryanother.¶

Some token formats, such as Macaroons[MACAROON] and Biscuits[BISCUIT], allow forthe RS to derive sub-tokens without having to call the ASas described inSection 4.¶

The supported token formats can be communicated dynamically at runtimebetween the AS and RS in several places:¶

The AS can declare its supported token formats as part of RS-facing discovery (Section 3.1).¶
The RS can require a specific token format be used to access a registered resource set (Section 3.4).¶
The AS can return the token's format in an introspection response (Section 3.3).¶

In all places where the token format is listed explicitly, itMUST be one of the registeredvalues in the "GNAP Token Formats" registrySection 5.3.¶

3.Resource-Server-Facing API

To facilitate runtime and dynamic connections with an RS, the AS can offer anRS-facing API consisting of one or more of the following optionalpieces:¶

Discovery¶
Introspection¶
Token chaining¶
Resource reference registration¶

3.1.RS-Facing AS Discovery

A GNAP AS offering RS-facing services can publish its featureson a well-known discovery document at the URL with the sameschema and authority as the grant request endpoint URL, atthe path/.well-known/gnap-as-rs.¶

The discovery response is a JSON document[RFC8259] consisting of a single JSON object with the following fields:¶

grant_request_endpoint (string):: The location of the AS's grant request endpoint defined bySection 9 of [GNAP]. This URLMUST be the same URL used by client instances in support of GNAP requests. The RS can use this to derive downstream access tokens, if supported by the AS. The locationMUST be a URL[RFC3986] with a scheme component thatMUST be https, a host component, and (optionally) port, path, and query components and no fragment components.REQUIRED. SeeSection 4.¶
introspection_endpoint (string):: The URL of the endpoint offering introspection. The locationMUST be a URL[RFC3986] with a scheme component thatMUST be https, a host component, and (optionally) port, path, and query components and no fragment components.REQUIRED if the AS supports introspection. An absent value indicates that the AS does not support introspection. SeeSection 3.3.¶
token_formats_supported (array of strings):: A list of token formats supported by this AS. The values in this listMUST be registered in the "GNAP Token Formats" registry perSection 5.3.OPTIONAL.¶
resource_registration_endpoint (string):: The URL of the endpoint offering resource registration. The locationMUST be a URL[RFC3986] with a scheme component thatMUST be https, a host component, and (optionally) port, path, and query components and no fragment components.REQUIRED if the AS supports dynamic resource registration. An absent value indicates that the AS does not support this feature. SeeSection 3.4.¶
key_proofs_supported (array of strings):: A list of the AS's supported key proofing mechanisms. The values of this list correspond to possible values of theproof field of the key section of the request. ValuesMUST be registered in the "GNAP Key Proofing Methods" registry established by[GNAP].OPTIONAL.¶

Additional fields are defined in the "GNAP RS-Facing Discovery Document Fields" registry; seeSection 5.8.¶

3.2.Protecting RS Requests to the AS

Unless otherwise specified, the RSMUST protect its calls to the AS using any of the signaturemethods defined inSection 7 of [GNAP].¶

The RSMAY present its keys by reference or by value ina similar fashion to a client instance calling the AS in the core protocolof GNAP, as described inSection 7.1 of [GNAP]. In the protocols defined here,this takes the form of the resource server identifying itself by using akey field orby passing an instance identifier directly.¶

POST /continue HTTP/1.1Host: server.example.comAuthorization: GNAP 80UPRY5NM33OMUKMKSKUSignature-Input: sig1=...Signature: sig1=...Content-Type: application/json"resource_server": {    "key": {        "proof": "httpsig",        "jwk": {            "kty": "EC",            "crv": "secp256k1",            "kid": "2021-07-06T20:22:03Z",            "x": "-J9OJIZj4nmopZbQN7T8xv3sbeS5-f_vBNSy_EHnBZc",            "y": "sjrS51pLtu3P4LUTVvyAIxRfDV_be2RYpI5_f-Yjivw"        }    }}

or by reference:¶

POST /continue HTTP/1.1Host: server.example.comSignature-Input: sig1=...Signature: sig1=...Content-Type: application/json{    "resource_server": "7C7C4AZ9KHRS6X63AJAO"}

The means by which an RS's keys are made known to the AS are outof the scope of this specification.The ASMAY require an RS to preregister its keys,or it could allow calls from arbitrary keys in a trust-on-first-usemodel.¶

The ASMAY issue access tokens, called "resource server management access tokens", to the RS to protect the RS-facing API endpoints.If such tokens are issued, the RSMUST present themto the RS-facing API endpoints along with the RS authentication.¶

POST /continue HTTP/1.1Host: server.example.comAuthorization: GNAP 80UPRY5NM33OMUKMKSKUSignature-Input: sig1=...Signature: sig1=...Content-Type: application/json{    "resource_server": "7C7C4AZ9KHRS6X63AJAO"}

3.3.Token Introspection

The AS issues access tokens representing a set of delegated access rightsto be used at one or more RSs. The AS can offer an introspection serviceto allow an RS to validate that a given access token:¶

has been issued by the AS¶
is valid at the current time¶
has not been revoked¶
is appropriate for the RS identified in the call¶

When the RS receives an access token, it can call the introspectionendpoint at the AS to get token information.¶

The client instance calls the RS with its access token.¶
The RS introspects the access token value at the AS. The RS signs the request with its own key (not the client instance's key or the token's key).¶
The AS validates the access token value and the RS's request and returns the introspection response for the token.¶
The RS fulfills the request from the client instance.¶

The RS signs the request with its own key and sends the value of the accesstoken in the body of the request as a JSON object with the following members:¶

access_token (string):: The access token value presented to the RS by the client instance.REQUIRED.¶
proof (string):: The proofing method used by the client instance to bind the token to the RS request. The valueMUST be registered in the "GNAP Key Proofing Methods" registry.RECOMMENDED.¶
resource_server (object/string):: The identification used to authenticate the resource server making this call, either by value or by reference as described inSection 3.2.REQUIRED.¶
access (array of strings/objects):: The minimum access rights required to fulfill the request. ThisMUST be in the format described inSection 8 of [GNAP].OPTIONAL.¶

Additional fields are defined in the "GNAP Token Introspection Request" registry (Section 5.4).¶

POST /introspect HTTP/1.1Host: server.example.comContent-Type: application/jsonSignature-Input: sig1=...Signature: sig1=...Digest: sha256=...{    "access_token": "OS9M2PMHKUR64TB8N6BW7OZB8CDFONP219RP1LT0",    "proof": "httpsig",    "resource_server": "7C7C4AZ9KHRS6X63AJAO"}

The ASMUST validate the access token value and determine if the token is active.The parameters of the request provide a context for the AS to evaluate the access token,and the ASMUST take all provided parameters into account when evaluating if the token is active.If the AS is unable to process part of the request, such as not understanding part oftheaccess field presented, the ASMUST NOT indicate the token as active.¶

An active access token is defined as a token that is all of the following:¶

was issued by the processing AS,¶
has not been revoked,¶
has not expired,¶
is bound using theproof method indicated,¶
is appropriate for presentation at the identified RS, and¶
is appropriate for theaccess indicated (if present).¶

The AS responds with a data structure describing the token'scurrent state and any information the RS would need to validate thetoken's presentation, such as its intended proofing mechanism and keymaterial.¶

active (boolean):: Iftrue, the access token presented is active, as defined above. If any of the criteria for an active token are not true, or if the AS is unable to make a determination (such as the token is not found), the value is set tofalse and other fields are omitted.REQUIRED.¶

If the access token is active, additional fields from the single access tokenresponse structure defined inSection 3.2.1 of [GNAP] are included. Inparticular, these include the following:¶

access (array of strings/objects):: The access rights associated with this access token. ThisMUST be in the format described inSection 8 of [GNAP]. This arrayMAY be filtered or otherwise limited for consumption by the identified RS, including being an empty array, which indicates that the token has no explicit access rights that can be disclosed to the RS.REQUIRED.¶
key (object/string):: if the token is bound. The key bound to the access token, to allow the RS to validate the signature of the request from the client instance. If the access token is a bearer token, thisMUST NOT be included.REQUIRED¶
flags (array of strings):: The set of flags associated with the access token.OPTIONAL.¶
exp (integer):: The timestamp after which this token is no longer valid. Expressed as integer seconds from UNIX Epoch.OPTIONAL.¶
iat (integer):: The timestamp at which this token was issued by the AS. Expressed as integer seconds from UNIX Epoch.OPTIONAL.¶
nbf (integer):: The timestamp before which this token is not valid. Expressed as integer seconds from UNIX Epoch.OPTIONAL.¶
aud (string or array of strings):: Identifiers for the resource servers this token can be accepted at.OPTIONAL.¶
sub (string):: Identifier of the resource owner who authorized this token.OPTIONAL.¶
iss (string):: Grant endpoint URL of the AS that issued this token.REQUIRED.¶
instance_id (string):: The instance identifier of the client instance that the token was issued to.OPTIONAL.¶

Additional fields are defined in the "GNAP Token Introspection Response" registry (Section 5.5).¶

The responseMAY include any additional fields defined in an accesstoken response andMUST NOT include the access tokenvalue itself.¶

HTTP/1.1 200 OKContent-Type: application/jsonCache-Control: no-store{    "active": true,    "access": [        "dolphin-metadata", "some other thing"    ],    "key": {        "proof": "httpsig",        "jwk": {                "kty": "RSA",                "e": "AQAB",                "kid": "xyz-1",                "alg": "RS256",                "n": "kOB5rR4Jv0GMeL...."        }    }}

When processing the results of the introspection response, the RSMUST determine theappropriate course of action. For instance, if the RS determines that the access token'saccess rights are not sufficient for the request to which the token was attached, the RScan return an error or a public resource, as appropriate for the RS.In all cases, the final determination of the response is at the discretion of the RS.¶

3.4.Registering a Resource Set

If the RS needs to, it can post a set of resources, as described in Section8 ("Resource Access Rights") of[GNAP], to the AS's resource registration endpoint along with information aboutwhat the RS will need to validate the request.¶

access (array of objects/strings):: The list of access rights associated with the request in the format described in Section8 ("Resource Access Rights") of[GNAP].REQUIRED.¶
resource_server (object/string):: The identification used to authenticate the resource server making this call, either by value or by reference as described inSection 3.2.REQUIRED.¶
token_formats_supported (array of strings):: The list of token formats that the RS is able to process. The values in this arrayMUST be registered in the "GNAP Token Formats" registry perSection 5.3. If the field is omitted, the token format is at the discretion of the AS. If the AS does not support any of the requested token formats, the ASMUST return an error to the RS.OPTIONAL.¶
token_introspection_required (boolean):: If present and set totrue, the RS expects to make a token introspection request as described inSection 3.3. If absent or set tofalse, the RS does not anticipate needing to make an introspection request for tokens relating to this resource set. If the AS does not support token introspection for this RS, the ASMUST return an error to the RS.OPTIONAL.¶

Additional fields are defined in the "GNAP Resource Set Registration Request Parameters" registry (Section 5.6).¶

The RSMUST identify itself with its own key and sign therequest.¶

POST /resource HTTP/1.1Host: server.example.comContent-Type: application/jsonSignature-Input: sig1=...Signature: sig1=...Digest: ...{    "access": [        {            "actions": [                "read",                "write",                "dolphin"            ],            "locations": [                "https://server.example.net/",                "https://resource.local/other"            ],            "datatypes": [                "metadata",                "images"            ]        },        "dolphin-metadata"    ],    "resource_server": "7C7C4AZ9KHRS6X63AJAO"}

The AS responds with a reference appropriate to represent theresources list that the RS presented in its request as well asany additional information the RS might need in future requests.¶

resource_reference (string):: A single string representing the list of resources registered in the request. The RSMAY make this handle available to a client instance as part of a discovery response as described inSection 9.1 of [GNAP] or as documentation to client software developers.REQUIRED.¶
instance_id (string):: An instance identifier that the RS can use to refer to itself in future calls to the AS, in lieu of sending its key by value. SeeSection 3.2.OPTIONAL.¶
introspection_endpoint (string):: The introspection endpoint of this AS that is used to allow the RS to perform token introspection. SeeSection 3.3.OPTIONAL.¶

Additional fields are defined in the "GNAP Resource Set Registration Response Parameters" registry (Section 5.7).¶

HTTP/1.1 200 OKContent-Type: application/jsonCache-Control: no-store{    "resource_reference": "FWWIKYBQ6U56NL1"}

If a resource was previously registered, the ASMAY return the same resource reference value as in previous responses.¶

If the registration fails, the AS returns HTTP status code 400 (Bad Request) to theRS, indicating that the registration was not successful.¶

The client instance can then use theresource_reference value as a string-type accessreference as defined inSection 8.1 of [GNAP]. This valueMAY be combined with any otheradditional access rights requested by the client instance.¶

{    "access_token": {        "access": [            "FWWIKYBQ6U56NL1",            {                "type": "photo-api",                "actions": [                    "read",                    "write",                    "dolphin"                ],                "locations": [                    "https://server.example.net/",                    "https://resource.local/other"                ],                "datatypes": [                    "metadata",                    "images"                ]            },            "dolphin-metadata"        ]    },    "client": "client-12351.bdxqf"}

3.5.Error Responses

In the case of an error from the RS-facing API, the AS responds to the RS with HTTP status code 400 (Bad Request) and a JSON object consisting of a singleerror field, which is either an object or a string.¶

When returned as a string, the error value is the error code:¶

{    error: "invalid_access"}

When returned as an object, the error object contains the following fields:¶

code (string):: A single ASCII error code defining the error.REQUIRED.¶
description (string):: A human-readable string description of the error intended for thedeveloper of the client.OPTIONAL.¶

{  "error": {    "code": "invalid_access",    "description": "Access to 'foo' is not permitted for this RS."  }}

This specification defines the following error code values:¶

"invalid_request":: The request is missing a required parameter, includes an invalid parameter value, or is otherwise malformed.¶
"invalid_resource_server":: The request was made from an RS that was not recognized or allowed by the AS, or the RS's signature validation failed.¶
"invalid_access": The RS is not permitted to register or introspect for the requested "access" value.¶

Additional error codes can be defined in the "GNAP RS-Facing Error Codes" registry (Section 5.9).¶

5.IANA Considerations

IANA has added values to existing registries and created five registries under the "Grant Negotiation and Authorization Protocol (GNAP)" registry group.¶

5.1.Well-Known URIs

The "gnap-as-rs" URI suffix is registered in the "Well-Known URIs" registry to support RS-facing discovery of the AS.¶

URI Suffix:: gnap-as-rs¶
Change Controller:: IETF¶
Specification Document:: Section 3.1 of RFC 9767¶
Status:: Permanent¶

5.2.GNAP Grant Request Parameters

The following parameter is registered in the "GNAP Grant Request Parameters" registry:¶

Name:: existing_access_token¶
Type:: string¶
Reference:: Section 4 of RFC 9767¶

5.3.GNAP Token Formats

This document defines a GNAP token format, for which IANA has created and maintains a new registry titled "GNAP Token Formats". Initial values for this registry are given inSection 5.3.2. Future assignments and modifications to existing assignment are to be made through the Specification Required registration policy[RFC8126].¶

The designated expert (DE) is expected to ensure that:¶

all registrations follow the template presented inSection 5.3.1.¶
the format's definition is sufficiently unique from other formats provided by existing parameters.¶
the format's definition specifies the format of the access token in sufficient detail to allow for the AS and RS to be able to communicate the token information.¶

5.3.1.Registry Template

Name:: The name of the format.¶
Status:: Whether or not the format is in active use. Possible values are Active and Deprecated.¶
Description:: The human-readable description of the access token format.¶
Reference:: The specification that defines the token format.¶

5.3.2.Initial Registry Contents

Table 1:Initial Contents of the GNAP Token Formats Registry
Name	Status	Description	Reference
`jwt-signed`	Active	JSON Web Token, signed with JWS	[JWT]
`jwt-encrypted`	Active	JSON Web Token, encrypted with JWE	[JWT]
`macaroon`	Active	Macaroon	[MACAROON]
`biscuit`	Active	Biscuit	[BISCUIT]
`zcap`	Active	ZCAP	[ZCAPLD]

5.4.GNAP Token Introspection Request

This document defines GNAP token introspection, for which IANA has created and maintains a new registry titled "GNAP Token Introspection Request". Initial values for this registry are given inSection 5.4.2. Future assignments and modifications to existing assignment are to be made through the Specification Required registration policy[RFC8126].¶

The DE is expected to ensure that:¶

all registrations follow the template presented inSection 5.4.1.¶
the claim's definition is sufficiently orthogonal to other claims defined in the registry so as avoid overlapping functionality.¶
the claim's definition specifies the syntax and semantics of the claim in sufficient detail to allow for the AS and RS to be able to communicate the token values.¶

5.4.1.Registry Template

Name:: The name of the claim.¶
Type:: The JSON data type of the claim value.¶
Reference:: The specification that defines the claim.¶

5.4.2.Initial Registry Contents

The table below contains the initial contents of the "GNAP Token Introspection Request" registry.¶

Table 2:Initial Contents of the GNAP Token Introspection Request Registry
Name	Type	Reference
access_token	string	Section 3.3 of RFC 9767
proof	string	Section 3.3 of RFC 9767
resource_server	object/string	Section 3.3 of RFC 9767
access	array of strings/objects	Section 3.3 of RFC 9767

5.5.GNAP Token Introspection Response

This document defines GNAP token introspection, for which IANA has created and maintains a new registry titled "GNAP Token Introspection Response". Initial values for this registry are given inSection 5.5.2. Future assignments and modifications to existing assignment are to be made through the Specification Required registration policy[RFC8126].¶

The DE is expected to ensure that:¶

all registrations follow the template presented inSection 5.5.1.¶
the claim's definition is sufficiently orthogonal to other claims defined in the registry so as avoid overlapping functionality.¶
the claim's definition specifies the syntax and semantics of the claim in sufficient detail to allow for the AS and RS to be able to communicate the token values.¶

5.5.1.Registry Template

Name:: The name of the claim.¶
Type:: The JSON data type of the claim value.¶
Reference:: The specification that defines the claim.¶

5.5.2.Initial Registry Contents

The table below contains the initial contents of the "GNAP Token Introspection Response" registry.¶

Table 3:Initial Contents of the GNAP Token Introspection Response Registry
Name	Type	Reference
active	boolean	Section 3.3 of RFC 9767
access	array of strings/objects	Section 3.3 of RFC 9767
key	object/string	Section 3.3 of RFC 9767
flags	array of strings	Section 3.3 of RFC 9767
exp	integer	Section 3.3 of RFC 9767
iat	integer	Section 3.3 of RFC 9767
nbf	integer	Section 3.3 of RFC 9767
aud	string or array of strings	Section 3.3 of RFC 9767
sub	string	Section 3.3 of RFC 9767
iss	string	Section 3.3 of RFC 9767
instance_id	string	Section 3.3 of RFC 9767

5.6.GNAP Resource Set Registration Request Parameters

This document defines a means to register a resource set for a GNAP AS, for which IANA has created and maintains a new registry titled "GNAP Resource Set Registration Request Parameters". Initial values for this registry are given inSection 5.6.2. Future assignments and modifications to existing assignment are to be made through the Expert Review registration policy[RFC8126].¶

The DE is expected to ensure that:¶

all registrations follow the template presented inSection 5.6.1.¶
the parameter's definition is sufficiently orthogonal to other parameters defined in the registry so as avoid overlapping functionality.¶
the parameter's definition specifies the syntax and semantics of the parameter in sufficient detail to allow for the AS and RS to be able to communicate the resource set.¶

5.6.1.Registry Template

Name:: The name of the parameter.¶
Type:: The JSON data type of the parameter value.¶
Reference:: The specification that defines the token.¶

5.6.2.Initial Registry Contents

The table below contains the initial contents of the "GNAP Resource Set Registration Request Parameters" registry.¶

Table 4:Initial Contents of the GNAP Resource Set Registration Request Parameters Registry
Name	Type	Reference
access	array of strings/objects	Section 3.4 of RFC 9767
resource_server	object/string	Section 3.4 of RFC 9767
token_formats_supported	array of strings	Section 3.4 of RFC 9767
token_introspection_required	boolean	Section 3.4 of RFC 9767

5.7.GNAP Resource Set Registration Response Parameters

This document defines a means to register a resource set for a GNAP AS, for which IANA has created and maintains a new registry titled "GNAP Resource Set Registration Response Parameters". Initial values for this registry are given inSection 5.7.2. Future assignments and modifications to existing assignment are to be made through the Expert Review registration policy[RFC8126].¶

The DE is expected to ensure that:¶

all registrations follow the template presented inSection 5.7.1.¶
the parameter's definition is sufficiently orthogonal to other claims defined in the registry so as avoid overlapping functionality.¶
the parameter's definition specifies the syntax and semantics of the claim in sufficient detail to allow for the AS and RS to be able to communicate the resource set.¶

5.7.1.Registry Template

Name:: The name of the parameter.¶
Type:: The JSON data type of the parameter value.¶
Reference:: The specification that defines the parameter.¶

5.7.2.Initial Registry Contents

The table below contains the initial contents of the "GNAP Resource Set Registration Response Parameters" registry.¶

Table 5:Initial Contents of the GNAP Resource Set Registration Response Parameters Registry
Name	Type	Reference
resource_reference	string	Section 3.4 of RFC 9767
instance_id	string	Section 3.4 of RFC 9767
introspection_endpoint	string	Section 3.4 of RFC 9767

5.8.GNAP RS-Facing Discovery Document Fields

This document defines a means to for a GNAP AS to be discovered by a GNAP RS, for which IANA has created and maintains a new registry titled "GNAP RS-Facing Discovery Document Fields". Initial values for this registry are given inSection 5.8.2. Future assignments and modifications to existing assignment are to be made through the Expert Review registration policy[RFC8126].¶

The DE is expected to ensure that:¶

all registrations follow the template presented inSection 5.8.1.¶
the field's definition is sufficiently orthogonal to other fields defined in the registry so as avoid overlapping functionality.¶
the field's definition specifies the syntax and semantics of the fields in sufficient detail to allow for the RS to be able to communicate with the AS.¶

5.8.1.Registry Template

Name:: The name of the field.¶
Type:: The JSON data type of the field value.¶
Reference:: The specification that defines the field.¶

5.8.2.Initial Registry Contents

The table below contains the initial contents of the "GNAP RS-Facing Discovery Document Fields" registry.¶

Table 6:Initial Contents of the GNAP RS-Facing Discovery Document Fields Registry
Name	Type	Reference
introspection_endpoint	string	Section 3.1 of RFC 9767
token_formats_supported	array of strings	Section 3.1 of RFC 9767
resource_registration_endpoint	string	Section 3.1 of RFC 9767
grant_request_endpoint	string	Section 3.1 of RFC 9767
key_proofs_supported	array of strings	Section 3.1 of RFC 9767

5.9.GNAP RS-Facing Error Codes

This document defines a set of errors that the AS can return to the RS, for which IANA has created and maintains a new registry titled "GNAP RS-Facing Error Codes". Initial values for this registry are given inSection 5.9.2. Future assignments and modifications to existing assignments are to be made through the Specification Required registration policy[RFC8126].¶

The DE is expected to ensure that:¶

all registrations follow the template presented inSection 5.9.1.¶
the error response is sufficiently unique from other errors to provide actionable information to the client instance.¶
the definition of the error response specifies all conditions in which the error response is returned and what the client instance's expected action is.¶

5.9.1.Registration Template

Error:: A unique string code for the error.¶
Reference:: Reference to the document(s) that specifies the value, preferably including a URI that can be used to retrieve a copy of the document(s). An indication of the relevant sections may also be included but is not required.¶

5.9.2.Initial Contents

Table 7:Initial Contents of the GNAP RS-Facing Error Codes Registry
Error	Reference
invalid_request	Section 3.5 of RFC 9767
invalid_resource_server	Section 3.5 of RFC 9767
invalid_access	Section 3.5 of RFC 9767

6.Security Considerations

In addition to the normative requirements in this document and in[GNAP], implementers arestrongly encouraged to consider the following additional security considerations in implementationsand deployments of GNAP.¶

6.1.TLS Protection in Transit

All requests in GNAP made over untrusted network connections have to be made over TLS as outlined in[BCP195]to protect the contents of the request and response from manipulation and interception by an attacker.This includes all requests from a client instance to the RS and all requests from the RS to an AS.¶

6.2.Token Validation

The RS has a responsibility to validate the incoming access token in a manner consistent with its deployment.For self-contained stateless tokens such as those described inSection 2.2, this consists of actions suchas validating the token's signature and ensuring the relevant fields and results are appropriate for therequest being made. For reference-style tokens or tokens that are otherwise opaque to the RS, the token introspectionRS-facing API can be used to provide updated information about the state of the token, as described inSection 3.3.¶

The RS needs to validate that a token:¶

is intended for this RS (audience restriction)¶
is presented using the appropriate key for the token (see alsoSection 6.4)¶
identifies an appropriate subject to access the resource (usually this is the resource owner who authorized the token's issuance)¶
is issued by a trusted AS for this resource¶

Even though key proofing mechanisms have to cover the value of the token, validating the key proofing aloneis not sufficient to protect a request to an RS.If an RS validates only the presentation method as described inSection 6.4 without validating thetoken itself, an attacker could use a compromised key or a confused deputy to make arbitrary calls to the RSbeyond what has been authorized by the RO.¶

6.3.Caching Token Validation Result

Since token validation can be an expensive process, requiring either cryptographic operations or network calls to an introspectionservice as described inSection 3.3, an RS could cache the results of token validation for a particular token.The trade-off for using a cached validation for a token presents an important decision space for implementers: relying on a cached validation resultincreases performance and lowers processing overhead, but it comes at the expense of the liveness and accuracy of the informationin the cache. While a cached value is in use at the RS, an attacker could present a revoked token and have it accepted by the RS.¶

As with any cache, the consistency of this cache can be managed in a variety of ways. One of the most simplemethods is managing the lifetime of the cache in order to balance the performance and security properties.If the cache is too long, an attacker has a larger window in which to use a revoked token. If the window is too short, the benefits of using the cache are diminished.It is also possible that an AS could send a proactive signal to the RS to invalidate revoked access tokens, though such a mechanismis outside the scope of this specification.¶

6.4.Key Proof Validation

For key-bound access tokens, the proofing method needs to be validated alongside the value of the token itself, as described inSection 6.2.The process of validation is defined by the key proofing method, as described inSection 7.3 of [GNAP].¶

If the proofing method is not validated, an attacker could use a compromised token without access to the token's bound key.¶

The RS also needs to ensure that the proofing method is appropriate for the key associated with the token, including any choice of algorithm or identifiers.¶

The proofing should be validated independently on each request to the RS, particularly as aspects of the call could vary.As such, the RS should never cache the results of a proof validation from one message and apply it to a subsequent message.¶

6.5.Token Exfiltration

Since the RS sees the token value, it is possible for a compromised RS to leak that value to an attacker.As such, the RS needs to protect token values as sensitive information and protect them from exfiltration.¶

This is especially problematic with bearer tokens and tokens bound to a shared key, since an RS has accessto all information necessary to create a new, valid request using the token in question.¶

6.6.Token Reuse by an RS

If the access token is a bearer token, or the RS has access to the key material needed to present the token,the RS could be tricked into reusing an access token presented to it by a client. While it is possible to builda system that makes use of this artifact as a feature, it is safer to exchange the incoming access token foranother contextual token for use by the RS, as described inSection 4. This access token can be boundto the RS's own keys and limited to access needed by the RS, instead of the full set of rights associated withthe token issued to the client instance.¶

6.7.Token Format Considerations

With formatted tokens, the format of the token is likely to have its own considerations, and the RS needsto follow any such considerations during the token validation process. The application and scope ofthese considerations is specific to the format and outside the scope of this specification.¶

6.8.Oversharing Token Contents

The contents of the access token model divulge information about the access token's context and rights to the RS.This is true whether the contents are parsed from the token itself or sent in an introspection response.¶

It's likely that every RS does not need to know all details of the token model, especially in systems wherea single access token is usable across multiple RSs. An attacker could use this to gain information aboutthe larger system by compromising only one RS. By limiting the information available to onlythat which is relevant to a specific RS, such as using a limited introspection reply as defined inSection 3.3,a system can follow the principle of least disclosure to each RS.¶

6.9.Resource References

Resource references, as returned by the protocol inSection 3.4, are intended to be opaque toboth the RS and the client. However, since they are under the control of the AS, the AS can put whatever contentit wants into the reference value. This value could unintentionally disclose system structure or other internaldetails if it was processed by an unintended party. Furthermore, such patterns could lead to the client software andRS depending on certain structures being present in the reference value, which diminishes the separation of concernsof the different roles in a GNAP system.¶

To mitigate this, the AS should only use fully random or encrypted values for resource references.¶

6.10.Token Reissuance from an Untrusted AS

It is possible for an attacker's client instance to issue its own tokens to another client instance, acting asan AS that the second client instance has chosen to trust. If the token is a bearer token or the reissuanceis bound using an AS-provided key, the target client instance will not be able to tell that the token was originallyissued by the valid AS. This process allows an attacker to insert their own session and rights into an unsuspectingclient instance in the guise of a valid token for the attacker that appears to have been issued to the targetclient instance on behalf of its own RO.¶

This attack is predicated on a misconfiguration with the targeted client, as it has been configured to get tokensfrom the attacker's AS and use those tokens with the target RS, which has no association with the attacker's AS.However, since the token is ultimately coming from the trusted AS and is being presented with a valid key,the RS has no way of telling that the token was passed through an intermediary.¶

To mitigate this, the RS can publish its association with the trusted AS through either discovery or documentation.Therefore, a client properly following this association would only go directly to the trusted RS for access tokens for the RS.¶

Furthermore, limiting the use of bearer tokens and AS-provided keys to only highly trusted ASs in certain circumstances prevents the attacker from being able to willingly exfiltrate their token to an unsuspecting client instance.¶

6.11.Introspection of Token Keys

The introspection response defined inSection 3.3 provides a means for the AS to tell the RS what key material is needed to validate the key proof of the request. Capture of the introspection response can exposethese security keys to an attacker. In the case of asymmetric cryptography, only the public key is exposed,and the token cannot be reused by the attacker based on this result alone. This could potentially divulgeinformation about the client instance that was unknown otherwise.¶

If an access token is bound to a symmetric key, the RS will need access to the full key value in order to validatethe key proof of the request, as described inSection 6.4. However, divulging the keymaterial to the RS also gives the RS the ability to create a new request with the token.In this circumstance, the RS is under similar risk of token exfiltration andreuse as a bearer token, as described inSection 6.6. Consequently, symmetrickeys should only be used in systems where the RS can be fully trusted to not create a new request withtokens presented to it.¶

6.12.RS Registration and Management

Most functions of the RS-facing API inSection 3 are protected by requiring the RS topresent proof of a signing key along with the request, in order to identify the RS making thecall, potentially coupled with an AS-specific access token.This practice allows the AS to differentially respond to API calls to different RSs, such asanswering introspection calls with only the access rights relevant to a given RS instead ofall access rights an access token could be good for.¶

While the means by which an RS and its keys become known to the AS is out of scope for thisspecification, it is anticipated that common practice will be to statically register anRS, allowing it to protect specific resources or certain classes of resources.Fundamentally, the RS can only offer the resources that it serves. However, a rogue AS couldattempt to register a set of resources that mimics a different RS in order to solicit an accesstoken that is usable at the target RS. If the access token is a bearer token or is bound to a symmetrickey that is known to the RS, then the attacker's RS gains the ability and knowledge neededto use that token elsewhere.¶

In some ecosystems, dynamic registration of an RS and its associated resources is feasible.In such systems, the identity of the RS could be conveyed by a URI passed in thelocation fieldof an access rights request, thereby allowing the AS to limit the view the RS has into thelarger system.¶

Movatterモバイル変換

RFC 9767

Grant Negotiation and Authorization Protocol Resource Server Connections