Transaction Request

The client begins the transaction by creating a transaction request. This is a JSON document POSTed to the authorization server's transaction endpoint. This 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 transaction request contains five parts:

  • client includes information about how the client software making the request
  • resources contains a list of resources that the client is requesting access to
  • interact contains information about how the client is able to get the user to interact with the AS, if necessary
  • key contains information about the 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

Each ot these sections is optional and can be also sent as a handle instead. When sent as a handle, the AS looks up the handle value to determine the values associated with that handle. The AS can also limit which values can be used together, such as only allowing certain callback URIs or keys when used with a client handle.

Note that the JSON in all sections is potentially multimodal. That is to say, when sent as a fully-formed request, it is a JSON object. When sent as a handle, it is sent as a JSON string.

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

{
    "client": {
        "name": "My Client Display Name",
        "uri": "https://example.net/client"
    },
    "interact": {
        "type": "redirect",
        "callback": "https://client.example.net/return/123455",
        "nonce": "LKLTI25DK82FX4T4QFZC"
    },
    "resources": [
        "dolphin-metadata"
    ],
    "key": {
        "jwks": {
            "keys": [
                {
                    "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"
                }
            ]
        }
    }
}

Each of the sections is detailed below. The AS will send a transaction response in response.

Client

The client 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.

The AS can statically issue a client handle to a piece of software (or its developer) to be used in place of this section. In this way, it takes the place of the client_id and client_secret of OAuth 2. In these cases, the AS will likely also keep references to which resources the client can ask for, which interact methods it is allowed to use, which keys it is allowed to present, and even what kinds of user information it can assert.

A client that is accessing things of its own accord and not on behalf of a user has to be pre-registered with a handle in this way and attached to a key.

An AS can also dynamically generate a client handle and return it to the client during the initial transaction response. This handle can be used by the same piece of software to identify itself in future transactions.

Resources

The resources 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.

{
    "actions": [
        "read",
        "write",
        "dolphin"
    ],
    "locations": [
        "https://server.example.net/",
        "https://resource.local/other"
    ],
    "data": [
        "metadata"
    ]
}

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

An AS can also dynamically generate a resources handle and return it to the client during the initial transaction response. This handle can be used by the same piece of software to identify this same kind of request in future transactions.

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

Interact

The interact parameter lets the client tell the AS how to get a user to interact with the AS during a transaction.

More detail is found in the Interaction section.

Do we care about an interact handle? Redirect based clients need to send a new nonce parameter every time anyway, and could potentially send a new callback URL while they're at it. Any matching on callback URI's can be tied to keys and would need to have the same rules as a dynamic registration system would have anyway.

Key

The key parameter lets the client tell the AS which keys it is able to prove ownership of during the course of the transaction.

The AS can statically issue a key handle to a piece of software (or its developer). An AS can also dynamically generate a key handle and return it to the client during the initial transaction. This handle can be used by the same piece of software to identify its keys in future transactions.

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

We need a mechanism for the AS to issue keys to the client during this process, and to acknowledge that it's accepted the presentation and proof of any keys sent by the client.

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. These claims need to be able to be validated by the AS, and it should be additionally validated that the client is an authorized holder of this information.

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 in appropriately trusted scenarios.

The AS can dynamically generate a user handle and return it to the client in the transaction 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.