]> Bespoke Engineering

ietf@justin.richer.org https://bspk.io/

acert.io

fabien.imbault@acert.io https://acert.io/

Security GNAP Internet-Draft GNAP defines a mechanism for delegating authorization to a piece of software, and conveying that delegation to the software. This extension defines methods for resource servers (RS) to connect with authorization servers (AS) in an interoperable fashion.

Introduction The core GNAP specification () defines distinct roles for the authorization server (AS) and the resource server (RS). However, the core specification does not define how the RS answers important questions, such as whether a given access token is still valid or what set of access rights the access token is approved for. While it's possible for the AS and RS to be tightly coupled, such as a single deployed server with a shared storage system, GNAP does not presume or require such a tight coupling. It is increasingly common for the AS and RS to be run and managed separately, particularly in cases where a single AS protects multiple RS's simultaneously. This specification defines a set of RS-facing APIs that an AS can make available for advanced loosely-coupled deployments. Additionally, this document defines a general-purpose model for access tokens, which can be used in structured, formatted access tokens or in the API. This specification also defines a method for an RS to derive a downstream token for calling another chained RS. The means of the authorization server issuing the access token to the client instance and the means of the client instance presenting the access token to the resource server are the subject of the core GNAP specification .

Terminology 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 when, and only when, they appear in all capitals, as shown here. This document contains non-normative examples of partial and complete HTTP messages, JSON structures, URLs, query components, keys, and other elements. Some examples use a single trailing backslash \ to indicate line wrapping for long values, as per . The \ character and leading spaces on wrapped lines are not part of the value. Terminology specific to GNAP is defined in the terminology section of the core specification , and provides definitions for the protocol roles: authorization server (AS), client, resource server (RS), resource owner (RO), end user; as well as the protocol elements: attribute, access token, grant, privilege, protected resource, right, subject, subject information. The same definitions are used in this document.

Access Tokens Access tokens are 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 in ), the concept of an access token is consistent across all GNAP systems.

General-purpose Access Token Model Access tokens represent a common set of aspects across different GNAP deployments. This is not intended to be a universal or comprehensive list, but instead to provide guidance to implementors when developing data structures and associated systems across a GNAP deployment. These data structures are communicated between the AS and RS either by using a structured token or an API-like mechanism like token introspection. This general-purpose data model does not assume either approach, and in fact both can be used together to convey different pieces of information. Where possible, mappings to concrete data fields in common standards understood by the RS are provided for each item in the model.

Value All access tokens have a unique value. This is the string that is passed on the wire between parties. The AS chooses the value, which can be structured as in or unstructured. When the token is structured, the token value also has a format known to the AS and RS, and the other items in 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 like token introspection described in . The access token value is conveyed the value field of an access_token response from . 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 token value, the client software is never expected nor intended to be able to understand the token value itself.

Issuer The access token is issued by the AS in a standard GNAP transaction. The AS will often need to identify itself in order to recognize tokens that it has issued, particularly in cases where tokens from multiple different AS's could be presented. 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 a formatted token or a token introspection response, this corresponds to the iss claim.

Audience The access token is intended for use at one or more RS's. The AS can identify those RS's to allow each RS to ensure that the token 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 a formatted token or token introspection response, this corresponds to the aud claim. In cases where more complex access is required, the location field of objects in the access array can also convey audience information. In such cases, the client instance might need to know the audience information in order to differentiate between possible RS's to present the token to.

Key Binding Access tokens in GNAP are bound to the client instance's registered or presented key, except in cases where the access token is a bearer token. For all tokens bound to a key, the AS and RS need to be able to identify which key the token is bound to, otherwise an attacker could substitute their own key during presentation of the token. In the case of an asymmetric algorithm, the model for the AS and RS need only contain the public key, while the client instance will also need to know the private key in order to present the token appropriately. In the case of a symmetric algorithm, all parties will need to either know or be able to derive the shared key. The source of this key information can vary depending on circumstance and deployment. For example, an AS could 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 issued and finds the key information there. The AS could alternatively bind each token to a specific key that is managed separately from client instance information. In such a case, the AS determines the key information directly. This approach allows the client instance to use a different key for each request, or allows the AS to issue a key for the client instance to use with the particular token. In all cases, the key binding also includes a proofing mechanism, along with any parameters needed for that mechanism such as a signing or digest algorithm. If such information is not stored, an attacker could present a token with a seemingly-valid key using an insecure and incorrect proofing mechanism. This value is conveyed to the client instance in the key field of the access_token response in . Since the common case is that the token is bound to the client instance's registered key, this field can be omitted in this case since the client will be aware of its own key. In a formatted token, this corresponds to the cnf (confirmation) claim. In a token introspection response, this corresponds to the key 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.

Flags GNAP access tokens can have multiple data flags associated with them that indicate special processing or considerations for the token. For example, whether the token is a bearer token, or should be expected to be durable across grant updates. The client can request a set of flags in the access_token request in . These flags are conveyed from the AS to the client in the flags field of the access_token response in . For token introspection, flags are returned in the flags field of the response.

Access Rights Access tokens are tied to a limited set of access rights. These rights specify in some detail what the token can be used for, how, and where. The internal structure of access rights are detailed in . The access rights associated with an access token are calculated from the rights available to the client instance making the request, the rights available to be approved by the RO, the rights actually approved by the RO, and the rights corresponding to the RS in question. The rights for a specific access token are a subset of the overall rights in a grant request. These rights are requested by the client instance in the access field of the access_token request in . The rights associated with an issued access token are conveyed to the client instance in the access field of the access_token response in . In token introspection responses, this corresponds to the access claim.

Time Validity Window The access token can be limited to a certain time window outside of which it is no longer valid for use at an RS. This window can be explicitly bounded by an expiration time and a not-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's issuance, 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 of an access token. However, this information can be made available to it using the expires_in field of an access token response in . The issuance time of the token is conveyed in the iat claim of a formatted token or a token introspection response. The expiration time of a token, after which it is to be rejected, is conveyed in the exp claim of a formatted token or a token introspection response. The starting time of a token's validity window, before which it is to be rejected, is conveyed in the nbf claim of a formatted token or a token introspection response.

Token Identifier Individual access tokens often need a unique internal identifier to allow the AS to differentiate between multiple separate tokens. This value of the token can often be used as the identifier, but in some cases a separate identifier is used. This separate identifier can be conveyed in the jti claim of a formatted token or a token introspection response. This identifier is not usually exposed to the client instance using the token, since the client instance only needs to use the token by value.

Authorizing Resource Owner Access tokens are approved on behalf of a resource owner (RO). The identity of this RO can be used by the 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 to determine which profile information to return. The nature of this information is subject to agreement by the AS and RS. This corresponds to the sub claim of a formatted token or a token introspection response. Detailed RO information is not returned to the client instance when an access token is requested alone, and in many cases returning this information to the client instance would be a privacy violation on the part of the AS. Since the access token represents a specific delegated access, the client instance needs only to use the token at its target RS. Following the profile example, the client instance does not need to know the 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 form of identifiers and assertions. These values are returned directly to the client separately from any access tokens that are requested, though it's common that they represent the same party.

End User The end user is the party operating the client software. The client instance can facilitate the end user interacting with the AS in order to determine the end user's identity, gather authorization, and provide the 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 user and RO separately. For example, an end user can request a financial payment, but the RO is the holder of the account that the payment would be withdrawn from. The RO would be consulted for approval by the AS outside of the flow of the GNAP request. A token in such circumstances would need to show both the RO and end user as separate entities.

Client Instance Access tokens are issued to a specific client instance by the AS. The identity of this instance can be 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 that client instance's most recent key rotation would need to be able to look up the client instance in order to find the key binding detail. This corresponds to the client_id claim of a formatted token or the instance_id field of a token introspection response. The client is not normally informed of this information separately, since a client instance can usually correctly assume that it is the client instance to which a token that it receives was issued.

Label When multiple access tokens are requested or a client instance uses token labels, the parties will need to keep track of which labels were applied to each individual token. Since labels can be re-used across different grant requests, the token label alone is not sufficient to uniquely identify a given access token in a system. However, within the context of a grant request, these labels are required to be unique. A client instance can request a specific label using the label field of an access_token request in . The AS can inform the client instance of a token's label using the label field of an access_token response in . This corresponds to the label field of a token introspection response.

Parent Grant Request All access tokens are issued in the context of a specific grant request from a client instance. The grant 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 RO's) 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 in

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 AS can store the client information in the grant itself and look it up by reference from the access token. The AS can also use this information when a grant request is updated. For example, if the client instance asks for a new access token from an existing grant, the AS can use this link to revoke older 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 that grant request can be continued using the API defined in where several pieces of statefulness need to be kept in hand. The client instance might need to keep an association with the grant request that issued the token in case the access token expires or does not have sufficient access rights, so that the client instance can get a new access token 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, GNAP does 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 the parent grant that issued it.

AS-Specific Access Tokens When an access token is used for the grant continuation API defined in (the continuation access token) the token management API defined in (the token management access token), or the RS-facing API defined in (the resource server management access token), the AS MUST separate these access tokens from others usable at RS's. The AS can do this through the use of a flag on the access token data structure, by using a special internal access 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 the continue field of the grant response in . The client instance is given token management access tokens only as part of the manage field of the grant response in . The means by which the RS is given resource server management access tokens is out of scope of this specification, but methods could include pre-configuration 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 instance MUST take steps to differentiate these special-purpose access tokens from access tokens used at RS's. To facilitate this, a client instance can store AS-specific access tokens separately from other access tokens in order to keep them from being confused with each other and used at the wrong endpoints. An RS should never see an AS-specific access token presented, so any attempts to process one MUST fail. When introspection is used, the AS MUST NOT return an active value of true for AS-specific access tokens to the RS. If an AS implements its protected endpoints in such a way as it uses token introspection internally, the AS MUST differentiate these AS-specific access tokens from those issued for use at an external RS.

Access Token Formats When the AS issues an access token for use at an RS, the RS needs to have some means of understanding what the access token is for in order to determine how to respond to the request. The core GNAP protocol makes neither assumptions nor demands on the format or contents of the access token, and in fact, the token format and contents are opaque to the client instance. However, such token formats can be the topic of agreements between the AS and RS. Self-contained structured token formats allow for the conveyance of information between the AS and RS without requiring the RS to call the AS at runtime as described in . Structured tokens can also be used in combination with introspection, allowing the token itself to carry one class of information and the introspection response to carry another. Some token formats, such as Macaroons and Biscuits , allow for the RS to derive sub-tokens without having to call the AS as described in . The supported token formats can be communicated dynamically at runtime between the AS and RS in several places.

• The AS can declare its supported token formats as part of RS-facing discovery
• The RS can require a specific token format be used to access a registered resource set
• The AS can return the token's format in an introspection response

In all places where the token format is listed explicitly, it MUST be one of the registered values in the GNAP Token Formats Registry .

Resource-Server-Facing API To facilitate runtime and dynamic connections, the AS can offer an RS-Facing API consisting of one or more of the following optional pieces.

• Discovery
• Introspection
• Token chaining
• Resource reference registration

RS-facing AS Discovery A GNAP AS offering RS-facing services can publish its features on a well-known discovery document using the URL .well-known/gnap-as-rs appended to the grant request endpoint URL. The discovery response is a JSON document consisting of a single JSON object with the following fields:

grant_request_endpoint (string):

The location of the AS's grant request endpoint defined by . This URL MUST 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 location MUST be a URL with a scheme component that MUST be https, a host component, and optionally, port, path and query components and no fragment components. REQUIRED. See .

introspection_endpoint (string):

The URL of the endpoint offering introspection. The location MUST be a URL with a scheme component that MUST 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. See .

token_formats_supported (array of strings):

A list of token formats supported by this AS. The values in this list MUST be registered in the GNAP Token Format Registry in . OPTIONAL.

resource_registration_endpoint (string):

The URL of the endpoint offering resource registration. The location MUST be a URL with a scheme component that MUST 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. See .

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 the proof field of the key section of the request. Values MUST be in the GNAP Key Proofing Methods registry. OPTIONAL.

Additional fields are defined in the GNAP RS-Facing Discovery Document Fields registry .

Protecting RS requests to the AS Unless otherwise specified, the RS MUST protect its calls to the AS using any of the signature methods defined by GNAP. This signing method MUST cover all of the appropriate portions of the HTTP request message, including any body elements, tokens, or headers required for functionality. The RS MAY present its keys by reference or by value in a similar fashion to a client instance calling the AS in the core protocol of GNAP, described in . In the protocols defined here, this takes the form of the resource server identifying itself using a key field or by passing an instance identifier directly. or by reference: The means by which an RS's keys are made known to the AS are out of scope of this specification. The AS MAY require an RS to pre-register its keys or could allow calls from arbitrary keys in a trust-on-first-use model. The AS MAY issue access tokens to the RS for protecting the RS-facing API endpoints, called a resource server management access token. If such tokens are issued, the RS MUST present them to the RS-facing API endpoints along with the RS authentication.

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

• has been issued by the AS
• has not expired
• has not been revoked
• is appropriate for the RS identified in the call

When the RS receives an access token, it can call the introspection endpoint at the AS to get token information. | RS | | AS | |Instance| | +--(2)->| | | | | | | | | | | |<-(3)--+ | | | | | +------+ | |<-(4)--+ | +--------+ +------+ ]]>

1. The client instance calls the RS with its access token.
2. 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).
3. The AS validates the access token value and the Resource Server's request and returns the introspection response for the token.
4. The RS fulfills the request from the client instance.

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

access_token (string):

REQUIRED. The access token value presented to the RS by the client instance.

proof (string):

RECOMMENDED. The proofing method used by the client instance to bind the token to the RS request. The value MUST be in the GNAP Key Proofing Methods registry.

resource_server (string or object):

REQUIRED. The identification used to authenticate the resource server making this call, either by value or by reference as described in .

access (array of strings/objects):

OPTIONAL. The minimum access rights required to fulfill the request. This MUST be in the format described in .

Additional fields are defined in the GNAP Token Introspection Request registry . The AS MUST 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 AS MUST 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 of the access field presented, the AS MUST NOT indicate the token as active. An active access token is defined as a token that

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

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

active (boolean):

REQUIRED. If true, 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 to false and other fields are omitted.

If the access token is active, additional fields from the single access token response structure defined in are included. In particular, these include the following:

access (array of strings/objects):

REQUIRED. The access rights associated with this access token. This MUST be in the format described in the . This array MAY be filtered or otherwise limited for consumption by the identified RS, including being an empty array, indicating that the token has no explicit access rights that can be disclosed to the RS.

key (object/string):

REQUIRED 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, this MUST NOT be included.

flags (array of strings):

OPTIONAL. The set of flags associated with the access token.

exp (integer):

OPTIONAL. The timestamp after which this token is no longer valid. Expressed as a integer seconds from UNIX Epoch.

iat (integer):

OPTIONAL. The timestamp at which this token was issued by the AS. Expressed as a integer seconds from UNIX Epoch.

nbf (integer):

OPTIONAL. The timestamp before which this token is not valid. Expressed as a integer seconds from UNIX Epoch.

aud (string or array of strings):

OPTIONAL. Identifiers for the resource servers this token can be accepted at.

sub (string):

OPTIONAL. Identifier of the resource owner who authorized this token.

iss (string):

REQUIRED. Grant endpoint URL of the AS that issued this token.

instance_id (string):

OPTIONAL. The instance identifier of the client instance that the token was issued to.

Additional fields are defined in the GNAP Token Introspection Response registry . The response MAY include any additional fields defined in an access token response and MUST NOT include the access token value itself. When processing the results of the introspection response, the RS MUST determine the appropriate course of action. For instance, if the RS determines that the access token's access rights are not sufficient for the request to which the token was attached, the RS can 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.

Registering a Resource Set If the RS needs to, it can post a set of resources as described in the Resource Access Rights section of to the AS's resource registration endpoint along with information about what the RS will need to validate the request.

access (array of objects/strings):

REQUIRED. The list of access rights associated with the request in the format described in the "Resource Access Rights" section of .

resource_server (string or object):

REQUIRED. The identification used to authenticate the resource server making this call, either by value or by reference as described in .

token_formats_supported (array of strings):

OPTIONAL. The token formats the RS is able to process for accessing the resource. The values in this array MUST be registered in the GNAP Token Formats Registry in . 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 AS MUST return an error to the RS.

token_introspection_required (boolean):

OPTIONAL. If present and set to true, the RS expects to make a token introspection request as described in . If absent or set to false, 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 AS MUST return an error to the RS.

Additional fields are defined in the GNAP Resource Set Registration Request registry . The RS MUST identify itself with its own key and sign the request. The AS responds with a reference appropriate to represent the resources list that the RS presented in its request as well as any additional information the RS might need in future requests.

resource_reference (string):

REQUIRED. A single string representing the list of resources registered in the request. The RS MAY make this handle available to a client instance as part of a discovery response as described in or as documentation to client software developers.

instance_id (string):

OPTIONAL. 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. See .

introspection_endpoint (string):

OPTIONAL. The introspection endpoint of this AS, used to allow the RS to perform token introspection. See .

Additional fields are defined in the GNAP Resource Set Registration Response Registry . If a resource was previously registered, the AS MAY return the same resource reference value as in previous responses. If the registration fails, the AS returns an HTTP 400 Bad Request error to the RS indicating that the registration was not successful. The client instance can then use the resource_reference value as a string-type access reference as defined in . This value MAY be combined with any other additional access rights requested by the client instance.

Error Responses In the case of an error from the RS-facing API, the AS responds to the RS with an HTTP 400 (Bad Request) status code and a JSON object consisting of a single error field, which is either an object or a string. When returned as a string, the error value is the error code: 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 the developer of the client. OPTIONAL.

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.

Deriving a downstream token Some architectures require an RS to act as a client instance and use a derived access token for a secondary RS. Since the RS is not the same entity that made the initial grant request, the RS is not capable of referencing or modifying the existing grant. As such, the RS needs to request or generate a new token access token for its use at the secondary RS. This internal secondary token is issued in the context of the incoming access token. While it is possible to use a token format that allows for the RS to generate its own secondary token, the AS can allow the RS to request this secondary access token using the same process used by the original client instance to request the primary access token. Since the RS is acting as its own client instance from the perspective of GNAP, this process uses the same grant endpoint, request structure, and response structure as a client instance's request. | RS1 | | AS | | RS2 | |Instance| | +--(2)->| | | | | | | |<-(3)--+ | | | | | | | +------+ | | | | | | | | | | | +-----------(4)------->| | | | | |<----------(5)--------+ | | |<-(6)--+ | | | +--------+ +-------+ +-------+ ]]>

1. The client instance calls RS1 with an access token.
2. RS1 presents that token to the AS to get a derived token for use at RS2. RS1 indicates that it has no ability to interact with the RO. Note that RS1 signs its request with its own key, not the token's key or the client instance's key.
3. The AS returns a derived token to RS1 for use at RS2.
4. RS1 calls RS2 with the token from (3).
5. RS2 fulfills the call from RS1.
6. RS1 fulfills the call from the original client instance.

If the RS needs to derive a token from one presented to it, it can request one from the AS by making a token request as described in and presenting the existing access token's value in the "existing_access_token" field. Since the RS is acting as a client instance, the RS MUST identify itself with its own key in the client field and sign the request just as any client instance would, as described in . The AS MUST determine that the token being presented is appropriate for use at the RS making the token chaining request. The AS responds with a token for the downstream RS2 as described in . The downstream RS2 could repeat this process as necessary for calling further RS's.

Acknowledgements The editors would like to thank the feedback of the following individuals for their reviews, implementations, and contributions: Aaron Parecki, Adrian Gropper, Andrii Deinega, Annabelle Backman, Dmitry Barinov, Fabien Imbault, Florian Helmschmidt, George Fletcher, Justin Richer, Kathleen Moriarty, Leif Johansson, Mike Varley, Nat Sakimura, Takahiko Kawasaki, Yaron Sheffer. Finally, the editors want to acknowledge the immense contributions of Aaron Parecki to the content of this document. We thank him for his insight, input, and hard work, without which GNAP would not have grown to what it is.

IANA Considerations IANA is requested to add values to existing registries and to create 5 registries in the Grant Negotiation and Authorization Protocol registry.

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

URI Suffix:

gnap-as-rs

Change Controller:

IETF

Specification Document:

of RFC xxxx

Status:

Permanent

GNAP Grant Request Parameters The following parameter is registered into the GNAP Grant Request Parameters registry:

Name:

existing_access_token

Type:

string

Specification document(s):

of RFC xxxx

GNAP Token Formats Registry This document defines a GNAP token format, for which IANA is asked to create and maintain a new registry titled "GNAP Token Formats". Initial values for this registry are given in . Future assignments and modifications to existing assignment are to be made through the Specification Required registration policy . The Designated Expert (DE) is expected to ensure that all registrations follow the template presented in . The DE is expected to ensure that the format's definition is sufficiently unique from other formats provided by existing parameters. The DE is expected to ensure that 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.

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

Human-readable description of the access token format.

Reference

The specification that defines the token format.

Initial Registry Contents

Name	Status	Description	Reference
jwt-signed	Active	JSON Web Token, signed with JWS
jwt-encrypted	Active	JSON Web Token, encrypted with JWE
macaroon	Active	Macaroon
biscuit	Active	Biscuit
zcap	Active	ZCAP

GNAP Token Introspection Request Registry This document defines GNAP token introspection, for which IANA is asked to create and maintain a new registry titled "GNAP Token Introspection Request". Initial values for this registry are given in . Future assignments and modifications to existing assignment are to be made through the Specification Required registration policy . The Designated Expert (DE) is expected to ensure that all registrations follow the template presented in . The DE is expected to ensure that the claim's definition is sufficiently orthogonal to other claims defined in the registry so as avoid overlapping functionality. The DE is expected to ensure that 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.

Registry Template

Name

The name of the claim.

Type

The JSON data type of the claim value.

Reference

The specification that defines the token.

Initial Registry Contents The table below contains the initial contents of the GNAP Token Introspection Registry.

Name	Type	Reference
access_token	string	of RFC xxxx
proof	string	of RFC xxxx
resource_server	object/string	of RFC xxxx
access	array of strings/objects	of RFC xxxx

GNAP Token Introspection Response Registry This document defines GNAP token introspection, for which IANA is asked to create and maintain a new registry titled "GNAP Token Introspection Response". Initial values for this registry are given in . Future assignments and modifications to existing assignment are to be made through the Specification Required registration policy . The Designated Expert (DE) is expected to ensure that all registrations follow the template presented in . The DE is expected to ensure that the claim's definition is sufficiently orthogonal to other claims defined in the registry so as avoid overlapping functionality. The DE is expected to ensure that 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.

Registry Template

Name

The name of the claim.

Type

The JSON data type of the claim value.

Reference

The specification that defines the token.

Initial Registry Contents The table below contains the initial contents of the GNAP Token Introspection Registry.

Name	Type	Reference
active	boolean	of RFC xxxx
access	array of strings/objects	of RFC xxxx
key	object/string	of RFC xxxx
flags	array of strings	of RFC xxxx
exp	integer	of RFC xxxx
iat	integer	of RFC xxxx
nbf	integer	of RFC xxxx
aud	string or array of strings	of RFC xxxx
sub	string	of RFC xxxx
iss	string	of RFC xxxx
instance_id	string	of RFC xxxx

GNAP Resource Set Registration Request Parameters This document defines a means to register a resource set for a GNAP AS, for which IANA is asked to create and maintain a new registry titled "GNAP Resource Set Registration Request Parameters". Initial values for this registry are given in . Future assignments and modifications to existing assignment are to be made through the Expert Review registration policy . The Designated Expert (DE) is expected to ensure that all registrations follow the template presented in . The DE is expected to ensure that the parameter's definition is sufficiently orthogonal to other claims defined in the registry so as avoid overlapping functionality. The DE is expected to ensure that 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.

Registry Template

Name

The name of the parameter.

Type

The JSON data type of the parameter value.

Reference

The specification that defines the token.

Initial Registry Contents The table below contains the initial contents of the GNAP Resource Set Registration Request Parameters Registry.

Name	Type	Reference
access	array of strings/objects	of RFC xxxx
resource_server	string or object	of RFC xxxx
token_formats_supported	string	of RFC xxxx
token_introspection_required	boolean	of RFC xxxx

GNAP Resource Set Registration Response Parameters This document defines a means to register a resource set for a GNAP AS, for which IANA is asked to create and maintain a new registry titled "GNAP Resource Set Registration Response Parameters". Initial values for this registry are given in . Future assignments and modifications to existing assignment are to be made through the Expert Review registration policy . The Designated Expert (DE) is expected to ensure that all registrations follow the template presented in . The DE is expected to ensure that the parameter's definition is sufficiently orthogonal to other claims defined in the registry so as avoid overlapping functionality. The DE is expected to ensure that 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.

Registry Template

Name

The name of the parameter.

Type

The JSON data type of the parameter value.

Reference

The specification that defines the token.

Initial Registry Contents The table below contains the initial contents of the GNAP Resource Set Registration Response Parameters Registry.

Name	Type	Reference
resource_reference	string	of RFC xxxx
instance_id	string	of RFC xxxx
introspection_endpoint	string	of RFC xxxx

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 is asked to create and maintain a new registry titled "GNAP RS-Facing Discovery Document Fields". Initial values for this registry are given in . Future assignments and modifications to existing assignment are to be made through the Expert Review registration policy . The Designated Expert (DE) is expected to ensure that all registrations follow the template presented in . The DE is expected to ensure that the claim's definition is sufficiently orthogonal to other claims defined in the registry so as avoid overlapping functionality. The DE is expected to ensure that the claim's definition specifies the syntax and semantics of the claim in sufficient detail to allow for RS to be able to communicate with the AS.

Registry Template

Name

The name of the parameter.

Type

The JSON data type of the parameter value.

Reference

The specification that defines the token.

Initial Registry Contents The table below contains the initial contents of the GNAP RS-Facing Discovery Registry.

Name	Type	Reference
introspection_endpoint	string	of RFC xxxx
token_formats_supported	array of strings	of RFC xxxx
resource_registration_endpoint	string	of RFC xxxx
grant_request_endpoint	string	of RFC xxxx
key_proofs_supported	array of strings	of RFC xxxx

GNAP RS-Facing Error Codes This document defines a set of errors that the AS can return to the RS, for which IANA is asked to create and maintain a new registry titled "GNAP RS-Facing Error Codes". Initial values for this registry are given in . Future assignments and modifications to existing assignment are to be made through the Specification Required registration policy . The DE is expected to ensure that all registrations follow the template presented in . The DE is expected to ensure that the error response is sufficiently unique from other errors to provide actionable information to the client instance. The DE is expected to ensure that 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.

Registration Template

Error:

A unique string code for the error.

Specification document(s):

Reference to the document(s) that specify 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.

Initial Contents

Error	Specification document(s)
invalid_request	of RFC xxxx
invalid_resource_server	of RFC xxxx
invalid_access	of RFC xxxx

Security Considerations In addition to the normative requirements in this document and in , implementors are strongly encouraged to consider these additional security considerations in implementations and deployments of GNAP.

TLS Protection in Transit All requests in GNAP made over untrusted network connections have to be made over TLS as outlined in 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.

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 in , this consists of actions such as validating the token's signature and ensuring the relevant fields and results are appropriate for the request being made. For reference-style tokens or tokens that are otherwise opaque to the RS, the token introspection RS-facing API can be used to provide updated information about the state of the token, as described in . 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 also ) Subject identification (the RS knows who authorized the token) Issuer restriction (the RS knows who created the token, including signing a structure or providing introspection to prove this)

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

Cacheing Token Validation Result Since token validation can be an expensive process, requiring either cryptographic operations or network calls to an introspection service as described in , an RS could cache the results of token validation for a particular token. The trade offs of using a cached validation for a token present an important decision space for implementors: relying on a cached validation result increases performance and lowers processing overhead, but it comes at the expense of the liveness and accuracy of the information in 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 simple methods is managing the lifetime of the cache in order to balance the performance and security properties. Too long of a cache, and an attacker has a larger window in which to use a revoked token. Too short of a window and 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 mechanism is outside the scope of this specification.

Key Proof Validation For key-bound access tokens, the proofing method needs to be validated alongside the value of the token itself as described in . The process of validation is defined by the key proofing method, as described in . 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.

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 access to all information necessary to create a new, valid request using the token in question.

Token Re-Use 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 re-using an access token presented to it by a client. While it is possible to build a system that makes use of this artifact as a feature, it is safer to exchange the incoming access token for another contextual token for use by the RS, as described in . This access token can be bound to the RS's own keys and limited to access needed by the RS, instead of the full set of rights associated with the token issued to the client instance.

Token Format Considerations With formatted tokens, the format of the token is likely to have its own considerations, and the RS needs to follow any such considerations during the token validation process. The application and scope of these considerations is specific to the format and outside the scope of this specification.

Over-sharing Token Contents The contents of the access token model divulge to the RS information about the access token's context and rights. 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 where a single access token is usable across multiple RS's. An attacker could use this to gain information about the larger system by compromising only one RS. By limiting the information available to only that which is relevant to a specific RS, such as using a limited introspection reply as defined in , a system can follow a principle of least disclosure to each RS.

Resource References Resource references, as returned by the protocol in , are intended to be opaque to both the RS and the client. However, since they are under the control of the AS, the AS can put whatever content it wants into the reference value. This value could unintentionally disclose system structure or other internal details if it processed by an unintended party. Furthermore, such patterns could lead to the client software and RS depending on certain structures being present in the reference value, which diminishes the separation of concerns of the different roles in a GNAP system. To mitigate this, the AS should only use fully random or encrypted values for resource references.

Token Re-Issuance From an Untrusted AS It is possible for an attacker's client instance to issue its own tokens to another client instance, acting as an AS that the second client instance has chosen to trust. If the token is a bearer token or the re-issuance is bound using an AS-provided key, the target client instance will not be able to tell that the token was originally issued by the valid AS. This process allows an attacker to insert their own session and rights into an unsuspecting client instance, in the guise of a token valid for the attacker that appears to have been issued to the target client 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 tokens from 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 directly for access tokens for the RS. Furthermore, limiting the use of bearer tokens and AS-provided keys to only highly trusted AS's and limited circumstances prevents the attacker from being able to willingly exfiltrate their token to an unsuspecting client instance.

Introspection of Token Keys The introspection response defined in provides a means for the AS to tell the RS the key material needed to validate the key proof of the request. Capture of the introspection response can expose these security keys to an attacker. In the case of asymmetric cryptography, only the public key is exposed, and the token cannot be re-used by the attacker based on this result alone. This could potentially divulge information 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 validate the key proof of the request, as described in . However, divulging the key material 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 and re-use as a bearer token, as described in . Consequently, symmetric keys should only be used in systems where the RS can be fully trusted to not create a new request with tokens presented to it.

RS Registration and Management Most functions of the RS-facing API in are protected by requiring the RS to present proof of a signing key along with the request, in order to identify the RS making the call, potentially coupled with an AS-specific access token. This practice allows the AS to differentially respond to API calls to different RS's, such as answering introspection calls with only the access rights relevant to a given RS instead of all 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 this specification, it is anticipated that common practice will be to statically register an RS, 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 could attempt to register a set of resources that mimics a different RS in order to solicit an access token usable at the target RS. If the access token is a bearer token or is bound to a symmetric key that is known to the RS, then the attacker's RS gains the ability and knowledge needed to 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 the location field of an access rights request, thereby allowing the AS to limit the view the RS has into the larger system.

Privacy Considerations

Token Contents The contents of the access token could potentially contain personal information about the end-user, RO, or other parties. This is true whether the contents are parsed from the token itself or sent in an introspection response. While an RS will sometimes need this information for processing, it's often the case that an RS is exposed to these details only in passing, and not intentionally. For example, disclosure of a medical record number in the contents of an access token usable for both medial and non-medical APIs. To mitigate this, the a limited token introspection response can be used, as defined in .

Token Use Disclosure through Introspection When introspection is used by an RS, the AS is made aware of a particular token being used at a particular RS. When the RS is a separate system, the AS would not otherwise have insight into this action. This can potentially lead to the AS learning about patterns and actions of particular end users by watching which RS's are accessed and when.

Mapping a User to an AS When the client instance receives information about the protecting AS from an RS, this can be used to derive information about the resources being protected without releasing the resources themselves. For example, if a medical record is protected by a personal AS, an untrusted client could call an RS to discover the location of the AS protecting the record. Since the AS is tied strongly to a single RO, the untrusted and unauthorized client software can gain information about the resource being protected without accessing the record itself.

References Normative References In many standards track documents several words are used to signify the requirements in the specification. These words are often capitalized. This document defines these words as they should be interpreted in IETF documents. This document specifies an Internet Best Current Practices for the Internet Community, and requests discussion and suggestions for improvements. A Uniform Resource Identifier (URI) is a compact sequence of characters that identifies an abstract or physical resource. This specification defines the generic URI syntax and a process for resolving URI references that might be in relative form, along with guidelines and security considerations for the use of URIs on the Internet. The URI syntax defines a grammar that is a superset of all valid URIs, allowing an implementation to parse the common components of a URI reference without knowing the scheme-specific requirements of every possible identifier. This specification does not define a generative grammar for URIs; that task is performed by the individual specifications of each URI scheme. [STANDARDS-TRACK] JSON Web Token (JWT) is a compact, URL-safe means of representing claims to be transferred between two parties. The claims in a JWT are encoded as a JSON object that is used as the payload of a JSON Web Signature (JWS) structure or as the plaintext of a JSON Web Encryption (JWE) structure, enabling the claims to be digitally signed or integrity protected with a Message Authentication Code (MAC) and/or encrypted. RFC 2119 specifies common key words that may be used in protocol specifications. This document aims to reduce the ambiguity by clarifying that only UPPERCASE usage of the key words have the defined special meanings. JavaScript Object Notation (JSON) is a lightweight, text-based, language-independent data interchange format. It was derived from the ECMAScript Programming Language Standard. JSON defines a small set of formatting rules for the portable representation of structured data. This document removes inconsistencies with other specifications of JSON, repairs specification errors, and offers experience-based interoperability guidance. Bespoke Engineering acert.io GNAP defines a mechanism for delegating authorization to a piece of software, and conveying the results and artifacts of that delegation to the software. This delegation can include access to a set of APIs as well as subject information passed directly to the software. This document defines two strategies for handling long lines in width-bounded text content. One strategy, called the "single backslash" strategy, is based on the historical use of a single backslash ('\') character to indicate where line-folding has occurred, with the continuation occurring with the first character that is not a space character (' ') on the next line. The second strategy, called the "double backslash" strategy, extends the first strategy by adding a second backslash character to identify where the continuation begins and is thereby able to handle cases not supported by the first strategy. Both strategies use a self-describing header enabling automated reconstitution of the original content. Informative References n.d. Many protocols make use of points of extensibility that use constants to identify various protocol parameters. To ensure that the values in these fields do not have conflicting uses and to promote interoperability, their allocations are often coordinated by a central record keeper. For IETF protocols, that role is filled by the Internet Assigned Numbers Authority (IANA). To make assignments in a given registry prudently, guidance describing the conditions under which new values should be assigned, as well as when and how modifications to existing values can be made, is needed. This document defines a framework for the documentation of these guidelines by specification authors, in order to assure that the provided guidance for the IANA Considerations is clear and addresses the various issues that are likely in the operation of a registry. This is the third edition of this document; it obsoletes RFC 5226.

Document History

• -05
  • Added discussion of access tokens used to call the RS-facing AS APIs.
  • Updated IANA sections to align with core (and each other).
  • Added IANA section on introspection requests.
  • Added error responses.
  • Added extended discussion on resource server registration practices.
• -04
  • Editorial cleanup.
  • Updated IANA requirements, including "specification required" registration.
  • Added privacy and security considerations.
  • Clarified and expanded token introspection request and response.
  • Clarified and expanded resource set registration request and response, include example of use of resource reference.
  • Updated discovery.
  • Allow optional tokens on RS-facing API requests.
  • Tighter controls over derived tokens.
• -03
  • Added token model.
  • Added IANA sections.
• -02
  • Editorial and formatting fixes.
• -01
  • Better described RS authentication.
  • Added access token format registry.
  • Filled out introspection protocol.
  • Filled out resource registration protocol.
  • Expanded RS-facing discovery mechanisms.
  • Moved client-facing RS response back to GNAP core document.
• -00
  • Extracted resource server section.