Request

The client begins the delegation process by creating a grant request. This is a JSON document POSTed to the authorization server's grant endpoint. This same request starts the transaction regardless of the type of client, the type of resource being accessed, or the type of authorizations needed to access said resources.

The request contains several parts:

• access_token describes the rights and properties of any access tokens that the client instance is requesting
• subject contains a request for information about the current end user that the client instance is requesting from the AS
• client identifies the instance of client software using a key the client is able to provide proof of possession for during this transaction and any related actions
• user contains assertions about the current user that the client knows
• interact contains information about how the client is able to get the user to interact with the AS, if necessary

Some of these values can be sent by reference instead of by value, as described below. The AS can also limit which values can be used together, such as only allowing certain callback URIs or display information for a particular key handle.

Note that the JSON in many sections is potentially polymorphic. For example, when sent as a fully-formed request, client is a JSON object but when sent as an instance identifier it is sent as a JSON string.

This interactive example shows how the different sections can be composed with each other in a request.

{
    "access_token": {
        "access": [
            {
                "type": "example.com/resource-set",
                "actions": [
                    "read",
                    "write",
                    "dolphin"
                ],
                "locations": [
                    "https://server.example.net/",
                    "https://resource.local/other"
                ],
                "datatypes": [
                    "metadata",
                    "images"
                ]
            }
        ]
    },
    "client": {
        "key": {
            "proof": "httpsig",
            "jwk": {
                "kty": "RSA",
                "e": "AQAB",
                "kid": "xyz-1",
                "alg": "RS256",
                "n": "kOB5rR4Jv0GMeLaY6_It_r3ORwdf8ci_JtffXyaSx8xYJCCNaOKNJn_Oz0YhdHbXTeWO5AoyspDWJbN5w_7bdWDxgpD-y6jnD1u9YhBOCWObNPFvpkTM8LC7SdXGRKx2k8Me2r_GssYlyRpqvpBlY5-ejCywKRBfctRcnhTTGNztbbDBUyDSWmFMVCHe5mXT4cL0BwrZC6S-uu-LAx06aKwQOPwYOGOslK8WPm1yGdkaA1uF_FpS6LS63WYPHi_Ap2B7_8Wbw4ttzbMS_doJvuDagW8A1Ip3fXFAHtRAcKw7rdI4_Xln66hJxFekpdfWdiPQddQ6Y1cK2U3obvUg7w"
            }
        },
        "display": {
            "name": "My Client Display Name",
            "uri": "https://example.net/client"
        }
    },
    "interact": {
        "finish": {
            "method": "redirect",
            "uri": "https://client.example.net/return/123455",
            "nonce": "LKLTI25DK82FX4T4QFZC"
        }
    }
}

Each of the sections is detailed below.

The client instance has to protect all requests to the AS by signing the request with its key.

The AS will send a response back to the client.

Access Token

The access_token parameter allows the client instance to request one or more access tokens from the AS, for use at downstream resource servers. The client can signal a number of different behaviors, including whether the resulting token is bound to a signing key (by default, it is), what kinds of access are requested for the token, and even whether multiple access tokens are requested. The client instance can also signal advanced functionality, such as whether or not a given access token could be split into multiple resulting access tokens by the AS.

When requesting a single access token, the access_token object contains the following fields:

• access describes the resources the access token should be bound to
• label provides a unique, client-chosen label for the resulting access token
• flags allows the client to signal advanced functionality

{
    "access_token": {
        "label": "token1",
        "access": [
            {
                "type": "example.com/resource-set",
                "actions": [
                    "read",
                    "write",
                    "dolphin"
                ],
                "locations": [
                    "https://server.example.net/",
                    "https://resource.local/other"
                ],
                "datatypes": [
                    "metadata",
                    "images"
                ]
            }
        ],
        "flags": [
            "bearer",
            "split"
        ]
    }
}

Access

The access parameter contains a list of all resources and APIs the client wishes to access. Each object in this array lists the types of actions the client can take, the URIs where those actions can be taken, and the kinds of data that the client expects access to.

{
    "access": [
        {
            "type": "example.com/resource-set",
            "actions": [
                "read",
                "write",
                "dolphin"
            ],
            "locations": [
                "https://server.example.net/",
                "https://resource.local/other"
            ],
            "datatypes": [
                "metadata",
                "images"
            ]
        }
    ]
}

An AS can publish pre-set resources as resource references that can be passed by the client to the AS during a transaction request, similar to OAuth 2's scope concept. The AS can determine a default set of resources for a client not asking for anything specifically.

{
    "access": [
        "foo",
        "bar",
        "dolphin-metadata"
    ]
}

The client can send several of these objects or references in a single request, which the AS interprets as the client requesting access to all of the resources with a single access token.

Multiple Access Tokens

Usually, a client instance will request a single access token, in which case the client instance sends a single object as the value of the access_token object. However, GNAP allows advanced clients to request several tokens at once on a single request. To request multiple access tokens, the client sends an array instead of an object for the value of the access_token parameter. The values of this array are the same objects used in a single access token request, with one additional requirement: Each individual access tokens request object must include a unique label for that token. Each item in the access_token array will correspond to a different named access token in the response.

{
    "access_token": [
        {
            "label": "token1",
            "access": [
                {
                    "type": "example.com/resource-set",
                    "actions": [
                        "read",
                        "write",
                        "dolphin"
                    ],
                    "locations": [
                        "https://server.example.net/",
                        "https://resource.local/other"
                    ],
                    "datatypes": [
                        "metadata",
                        "images"
                    ]
                }
            ]
        },
        {
            "label": "token2",
            "access": [
                {
                    "type": "example.com/resource-set",
                    "actions": [
                        "foo",
                        "bar",
                        "dolphin"
                    ],
                    "locations": [
                        "https://resource.other/"
                    ],
                    "datatypes": [
                        "data",
                        "pictures"
                    ]
                }
            ]
        }
    ]
}

In this specific example, the client is requesting token1 to access the first resource and token2 to access the second resource. See more about what this means in the section on tokens.

Flags

The flags parameter allows the client instance to specify specific advanced behavior to be associated with the requested access token.

The bearer flag indicates that the client does not want the resulting access token to be bound to a key for presentation at the RS. Without this flag, the access token must be presented with proof of the client's key using the same mechanism the client used to make the original request.

The split flag indicates that the client is prepared for the AS to split the requested token into multiple access tokens in the response. Without this flag, a request for a single access token will never result in multiple access tokens. The label values for the resulting split tokens are at the discretion of the AS that processes the split.

Interact

The interact parameter lets the client tell the AS how to get a user to interact with the AS during a transaction. A client could be capable of multiple forms of interaction with the user, from redirecting to an arbitrary URL, to displaying a user code, to relaying messages to another piece of software.

More detail is found in the Interaction section.

Client

The client parameter allows the client instance to identify itself to the AS during its request. In GNAP, client software could have multiple distinct instances, depending on the nature of the software and its deployment. A mobile application, for example, would have many individual, distinct instances, while a web application would likely only have one. Furthermore, a client instance could be long-lived or ephemeral. A mobile application will need ongoing access long after the initial authorization, while an SPA instance will cease to exist at the end of the browser session. It's up to the AS to determine what kinds of clients it will accept connections from, including whether it will require client developers to pre-register client instance keys or derive keys from some known source, like a certificate authority.

The client instance can identify its aspects by value, sending an object as the client parameter in the initial request. This allows the client to identify itself to the AS and provide all the information necessary for the AS to start the transaction. Alternatively, the client can present an instance identifier by sending this identifier as a string in the client parameter. The AS dereferences this string to determine whatever client information is needed to start the transaction. The instance identifier can be generated during a static registration process or dynamically from the response of the AS.

Key

In GNAP, each distinct client instance is identified by its key. If two copies of the same software have the same key, they are functionally the same client instance. If one copy of a piece of client software has multiple keys, each key represents a separate instance from the perspective of GNAP.

The client instance can pass its key information to the AS by value or reference using the key parameter, thereby identifying the client instance making the call. When passed by value, the key object contains the key data in one of several formats, including X.509 certificates or JWKs. The proof parameter indicates how the client instance can provide proof of those keys, and may be one of several values including httpsig or mtls. When passed by reference, the key value is a simple opaque string identifier that the AS dereferences to find the key material.

Any keys referenced here, whether by value or by reference, have to be proved by the client during every request in the transaction, whether the initial request or a continuation request. More detail is found in the Keys section.

Display

The display section describes the client software that is making the request. This information can be used during any interaction with the user that the AS might need to do, and for auditing and review of authorization decisions.

Subject

The subject parameter lets the client request information about the user. The presence of this field indicates to the AS that the client wants to know who is logged in at the AS during the interaction process, and to have that information returned to the client.

This is distinct from the user parameter below, which contains information that the client already knows about the current user.

User

The user parameter lets the client pass information to the AS about the current user in the form of an assertion or other set of claims gathered from a trusted source. Any assertions presented usually need to be validated by the AS, and it should be additionally validated that the client is an authorized holder of this information. The client can also present a set of possible subject identifiers that the AS may know the user by, though these are hints and can't be taken as proof that the user is present.

While this does not necessarily prove that the user in question is actually present with the client, it can allow the AS to make authorization decisions without user interaction when the AS can trust the client to present this information. For example, if the AS has previously seen the user interact with this client and the client software is trusted, the authorization server could decide to process any requests as if that user's presence were already accounted for. Therefore if something is requested that does not require additional authorization, the AS does not need to interact with the user.

The AS can dynamically generate a user handle and return it to the client in the response. This handle can be used by the same piece of software to identify the same user in future transactions. In this way, it is similar to the persistent claims token from UMA 2.

This is distinct from the subject parameter above, which is about the client asking for information about the current user.