OAuth 2.0 direct interation for native clients using federation

4.3.1. Federating Response

If the authorization server decides to federate to another authorization server, it responds with error code federate and MUST return the federation_uri, federation_body, response_uri and auth_session response attributes.¶

When federating to another authorization server:¶

• Federating authorization server MUST use PAR [RFC9126] and include request_uri in federation_body.¶

• If native_callback_uri was included in the native authorization request, it MUST be included when calling federated authorization server's Native Authorization Endpoint.¶

Example federating response:¶

HTTP/1.1 400 Bad Request
Content-Type: application/json

{
    "error": "federate",
    "auth_session": "ce6772f5e07bc8361572f",
    "response_uri": "https://prev-as.com/native-authorization",
    "federation_uri": "https://next-as.com/native-authorization",
    "federation_body": "client_id=s6BhdRkqt3&request_uri=
      urn:ietf:params:oauth:request_uri:R3p_hzwsR7outNQSKfoX"
}

Client MUST call the federation_uri using HTTP POST, and provide it federation_body as application/x-www-form-urlencoded request body. Example:¶

POST /native-authorization HTTP/1.1
Host: next-as.com
Content-Type: application/x-www-form-urlencoded

client_id=s6BhdRkqt3&request_uri=
urn:ietf:params:oauth:request_uri:R3p_hzwsR7outNQSKfoX

The client MUST provide any response obtained from the federated authorization server, as application/x-www-form-urlencoded request body for the response_uri of the respective federating authorization server which SHALL be invoked using HTTP POST.¶

However, when federated authorization server returns the following error codes: federate, insufficient_authorization, insufficient_information, redirect_to_app, redirect_to_web, client MUST handle these errors according to FiPA [I-D.ietf-oauth-first-party-apps] and this specification.¶

Example client calling receiving an authorization code response from the federated authorization server:¶

HTTP/1.1 200 OK
Server: next-as.com
Content-Type: application/json
Cache-Control: no-store

{
  "authorization_code": "uY29tL2F1dGhlbnRpY"
}

And providing it to the federating authorization server's response_uri, adding previously obtained auth_session:¶

POST /native-authorization HTTP/1.1
Host: prev-as.com
Content-Type: application/x-www-form-urlencoded

authorization_code=uY29tL2F1dGhlbnRpY
&auth_session=ce6772f5e07bc8361572f

4.3.2. Redirect to app response

If the authorization server decides to nominate another native app to interact with end user, it responds with error code redirect_to_app and MUST return the deep_link response attribute.¶

Example redirect_to_app response:¶

HTTP/1.1 400 Bad Request
Content-Type: application/json

{
    "error": "redirect_to_app",
    "deep_link": "https://next-as.com/native-authorization?
      client_id=s6BhdRkqt3&request_uri=
      urn:ietf:params:oauth:request_uri:R3p_hzwsR7outNQSKfoX"
}

Client MUST use OS mechanisms to invoke the obtained deep_link. If no app claiming deep_link is found on the device, client MUST terminate the flow and MAY attempt a normal non-native OAuth flow.¶

The invoked app handles the native authorization request:¶

• Validates the request and ensures it contains a native_callback_uri, Otherwise terminates the flow.¶

• Establishes trust in native_callback_uri and validates that an app claiming it is on the device. Otherwise terminates the flow.¶

• Authenticates end-user and authorizes the request.¶

• Uses OS mechanisms to natively invoke native_callback_uri and return to the client, providing it a response according to this specification's response from a Native Authorization Endpoint, as url-encoded query parameters.¶

Note - trust establishment mechanisms in native_callback_uri are out of scope of this specification. However we assume closed ecosystems could employ an allowList, and open ecosystems could leverage [OpenID.Federation]:¶

• Extract native_callback_uri's DNS domain.¶

• Add the path /.well-known/openid-federation and perform trust chain resolution.¶

• Inspect client's metadata for redirect_uri's and validate native_callback_uri is included among them.¶

When the client is invoked on its native_callback_uri, it shall regard the invocation as a response from the authorization server which instructed redirect_to_app. Therefore, obtained response's audience is the authorization server which federated the client to the authorization server which redirected the client to the app. See Section 4.3.1 for details.¶

Example URI used to invoke of client app on its claimed native_callback_uri:¶

https://client.example.com/cb?authorization_code=uY29tL2F1dGhlbnRpY

Example client invoking the response_uri of the authorization server which federated it to the authorization server, which redirected it to the app:¶

POST /native-authorization HTTP/1.1
Host: prev-as.com
Content-Type: application/x-www-form-urlencoded

authorization_code=uY29tL2F1dGhlbnRpY
&auth_session=ce6772f5e07bc8361572f

4.3.3. Additional Information Required Response

If additional user input is required, for example to determine where to federate to, the response body shall contain the following additional properties:¶

logo:

OPTIONAL. URL or base64-encoded logo of Authorization Server, for branding purposes.¶

userPrompt:

REQUIRED. A JSON object containing the prompt definition. The following parameters MAY be used:¶

• options: OPTIONAL. A JSON object that defines a dropdown/select input with various options to choose from. Each key is the parameter name to be sent in the response and each value defines the option:¶

  • title: OPTIONAL. A string holding the input's title.¶

  • description: OPTIONAL. A string holding the input's description.¶

  • values: REQUIRED. A JSON object where each key is the selection value and each value holds display data for that value:¶

    • name: REQUIRED. A string holding the display name of the selection value.¶

    • logo: OPTIONAL. A string holding a URL or base64-encoded image for that selection value.¶

• inputs: OPTIONAL. A JSON object that defines an input field. Each key is the parameter name to be sent in the response and each value defines the input field:¶

  • title: OPTIONAL. A string holding the input's title.¶

  • hint: OPTIONAL. A string holding the input's hint that is displayed if the input is empty.¶

  • description: OPTIONAL. A string holding the input's description.¶

Example of requesting end-user for 2 multiple-choice inputs:¶

HTTP/1.1 400 Bad Request
Content-Type: application/json

{
    "error": "insufficient_information",
    "auth_session": "ce6772f5e07bc8361572f",
    "logo": "uri or base64-encoded logo of Authorization Server",
    "userPrompt": {
        "options": {
            "bank": {
                "title": "Bank",
                "description": "Choose your Bank",
                "values": {
                    "bankOfSomething": {
                        "name": "Bank of Something",
                        "logo": "uri or base64-encoded logo"
                    },
                    "firstBankOfCountry": {
                        "name": "First Bank of Country",
                        "logo": "uri or base64-encoded logo"
                    }
                }
            },
            "segment": {
                "title": "Customer Segment",
                "description": "Choose your Customer Segment",
                "values": {
                    "retail": "Retail",
                    "smb": "Small & Medium Businesses",
                    "corporate": "Corporate",
                    "ic": "Institutional Clients"
                }
            }
        }
    }
}

Example of requesting end-user for text input entry (email):¶

HTTP/1.1 400 Bad Request
Content-Type: application/json

{
    "error": "insufficient_information",
    "auth_session": "ce6772f5e07bc8361572f",
    "action": "prompt",
    "id": "request-identifier-2",
    "logo": "uri or base64-encoded logo of Authorization Server",
    "userPrompt": {
        "inputs": {
            "email": {
                "hint": "Enter your email address",
                "title": "E-Mail",
                "description": "Lorem Ipsum"
            }
        }
    }
}

The client gathers the required additional information and makes a POST request to the Native Authorization Endpoint. Example of response following end-user multiple-choice:¶

POST /native-authorization HTTP/1.1
Host: example.as.com
Content-Type: application/x-www-form-urlencoded

auth_session=ce6772f5e07bc8361572f
&bank=bankOfSomething
&segment=retail

Example of Client App response following end-user input entry:¶

POST /native-authorization HTTP/1.1
Host: example.as.com
Content-Type: application/x-www-form-urlencoded

auth_session=ce6772f5e07bc8361572f
&email=end_user@example.as.com

A.1.1. Diagram

                                                +--------------------+
                                                |   Authorization    |
                          (B)Native             |      Server 1      |
             +----------+ Authorization Request |+------------------+|
(A)User  +---|          |---------------------->||     Native       ||
   Starts|   |          |                       ||  Authorization   ||
   Flow  +-->|  Client  |<----------------------||    Endpoint      ||
             |          | (C)Federate Error     |+------------------+|
             |          |        Response       +--------------------+
             |          |         :
             |          |         :             +--------------------+
             |          |         :             |   Authorization    |
             |          | (D)Native             |      Server 2      |
             |          | Authorization Request |+------------------+|
             |          |---------------------->||     Native       ||
             |          |                       ||  Authorization   ||
             |          |<----------------------||    Endpoint      ||
             |          | (E) Redirect to       |+------------------+|
             |          |     App Response      +--------------------+
             |          |         :
             |          |         :             +--------------------+
             |          | (F) Invoke App        |                    |
             |          |---------------------->|   Native App of    |
             |          |                       |   Auth Server 2    |
             |          |<----------------------|                    |
             |          | (G)Authorization code +--------------------+
             |          |   For Auth Server 1
             |          |         :             +--------------------+
             |          |         :             |   Authorization    |
             |          | (H)Authorization Code |      Server 1      |
             |          |    For Auth Server 1  |+------------------+|
             |          |---------------------->||    Response      ||
             |          |                       ||       Uri        ||
             |          |<----------------------||    Endpoint      ||
             |          | (I) Authorization     |+------------------+|
             |          |     Code Response     |                    |
             |          |         :             |                    |
             |          |         :             |                    |
             |          | (J) Token Request     |+------------------+|
             |          |---------------------->||      Token       ||
             |          |                       ||     Endpoint     ||
             |          |<----------------------||                  ||
             |          | (K) Access Token      |+------------------+|
             |          |                       +--------------------+
             |          |
             +----------+

Figure: Native client federated, then redirected to app¶

A.1.2. Client makes initial request and receives "federate" error

Client calls the native authorization endpoint and includes the native_callback_uri parameter:¶

POST /native-authorization HTTP/1.1
Host: as-1.com
Content-Type: application/x-www-form-urlencoded

client_id=t7CieSlru4&native_callback_uri=
https://client.example.com/cb

The first authorization server, as-1.com, decides to federate to as-2.com after validating it supports the native authorization endpoint. If it does not, as-1.com returns:¶

HTTP/1.1 400 Bad Request
Content-Type: application/json

{
    "error": "native_authorization_federate_unsupported"
}

If native authorization endpoint is supported by the federated authorization server, as-1.com performs a PAR [RFC9126] request to as-2.com's pushed authorization endpoint, including the original native_callback_uri:¶

POST /par HTTP/1.1
Host: as-2.com
Content-Type: application/x-www-form-urlencoded

client_id=s6BhdRkqt3&native_callback_uri=
https://client.example.com/cb

as-1.com receives a request_uri from as-2.com's PAR endpoint, which it includes in its response to client, in the federation_body attribute:¶

HTTP/1.1 400 Bad Request
Content-Type: application/json

{
    "error": "federate",
    "auth_session": "ce6772f5e07bc8361572f",
    "response_uri": "https://as-1.com/native-authorization",
    "federation_uri": "https://as-2.com/native-authorization",
    "federation_body": "client_id=s6BhdRkqt3&request_uri=
      urn:ietf:params:oauth:request_uri:R3p_hzwsR7outNQSKfoX"
}

See Section 4.3.1 for more details.¶

A.1.3. Client calls federated authorization server and is redirected to app

Client calls the federation_uri it got from as-1.com using HTTP POST with federation_body as application/x-www-form-urlencoded request body:¶

POST /native-authorization HTTP/1.1
Host: as-2.com
Content-Type: application/x-www-form-urlencoded

client_id=s6BhdRkqt3&request_uri=
urn:ietf:params:oauth:request_uri:R3p_hzwsR7outNQSKfoX

as-2.com decides to use its native app to interact with end-user and responds:¶

HTTP/1.1 400 Bad Request
Content-Type: application/json

{
    "error": "redirect_to_app",
    "deep_link": "https://as-2.com/native-authorization?
      client_id=s6BhdRkqt3&request_uri=
      urn:ietf:params:oauth:request_uri:R3p_hzwsR7outNQSKfoX"
}

Client locates an app claiming the obtained deep_link and invokes it. See Section 4.3.2 for more details. The invoked app handles the native authorization request and then natively invokes native_callback_uri:¶

https://client.example.com/cb?authorization_code=uY29tL2F1dGhlbnRpY

A.1.4. Client calls federating authorization server

Client invokes the response_uri of as-1.com as it is the authorization server which federated it to as-2.com and the app's response is regarded as the response of as-2.com:¶

POST /native-authorization HTTP/1.1
Host: as-1.com
Content-Type: application/x-www-form-urlencoded

authorization_code=uY29tL2F1dGhlbnRpY
&auth_session=ce6772f5e07bc8361572f

And receives in response an authorization code, which it is the audience of (no further federations) to resolve:¶

HTTP/1.1 200 OK
Content-Type: application/json

{
  "authorization_code": "vZ3:uM3G2eHimcoSqjZ"
}

Client proceeds to exchange code for tokens.¶