End User authorization

The Authorization Endpoint performs Authentication of the End-User. This is done by sending the User Agent to the Authorization Server's Authorization Endpoint for Authentication and Authorization, using request parameters defined by OAuth 2.0 and additional parameters and parameter values defined by OpenID Connect.

An Authentication Request is an OAuth 2.0 Authorization Request that requests that the End-User be authenticated by the Authorization Server.

Authorization Servers MUST support the use of the HTTP GET and POST methods defined in RFC 2616 [RFC2616] at the Authorization Endpoint. Clients MAY use the HTTP GET or POST methods to send the Authorization Request to the Authorization Server. If using the HTTP GET method, the request parameters are serialized using URI Query String Serialization, per Section 13.1. If using the HTTP POST method, the request parameters are serialized using Form Serialization, per Section 13.2.

Request and response

The authorization code grant type is used to obtain both access tokens and refresh tokens and is optimized for confidential clients. Since this is a redirection-based flow, the client must be capable of interacting with the resource owner's user-agent (typically a web browser) and capable of receiving incoming requests (via redirection) from the authorization server.

+----------+
| Resource |
|   Owner  |
|          |
+----------+
     ^
    (B)
+----|-----+          Client Identifier      +---------------+
|  User   -+----(A)-- + Redirection URI ----=| Authorization |
|  Agent  -+----(B)-- User authenticates ---=|     Server    |
|         -+----(C)-- Authorization Code ---=|               |
+-|----|---+                                 +---------------+
  |    |                                         ^      v
 (A)  (C)                                        |      |
  ^    v                                         |      |
+---------+                                      |      |
|         |=---(D)-- Authorization Code ---------'      |
|  Client |          + Redirection URI                  |
|         |=---(E)----- Access Token -------------------'
+---------+       (w/ Optional Refresh Token)

Note: The lines illustrating steps (A), (B), and (C) are broken into two parts as they pass through the user-agent.

The following is a non-normative example HTTP 302 redirect response by the Client, which triggers the User Agent to make an Authentication Request to the Authorization Endpoint (with line wraps within values for display purposes only):

HTTP/1.1 302 Found
Location: https://server.example.com/authorize?
  response_type=code
  &scope=openid%20profile%20email
  &client_id=s6BhdRkqt3
  &state=af0ifjsldkj
  &redirect_uri=https%3A%2F%2Fclient.example.org%2Fcb

An Authentication Response is an OAuth 2.0 Authorization Response message returned from the OP's Authorization Endpoint in response to the Authorization Request message sent by the RP.

The following is a non-normative example successful response using this flow (with line wraps within values for display purposes only):

HTTP/1.1 302 Found
Location: https://client.example.org/cb?
  code=SplxlOBeZQQYbYS6WxSbIA
  &state=af0ifjsldkj

End user logout

Supports Client-initiated logout functionality.

An OpenId client (Relying Party, or "RP") can notify the OP that the End-User has logged out of the site and might want to log out of the OP as well. In this case, the RP, after having logged the End-User out of the RP, redirects the End-User's User Agent to the OP's logout endpoint URL. This URL is normally obtained via the end_session_endpoint element of the OP's Discovery response or may be learned via other mechanisms.

This specification also defines the following parameters that are passed as query parameters in the logout request:

At the logout endpoint, the OP SHOULD ask the End-User whether he wants to log out of the OP as well. If the End-User says "yes", then the OP MUST log out the End-User.

Non standard implementation.

If the end session request is cryptographically verified by the OP then the End User is automatically and immediately logged out of the Client session.

Client registration

Supports automated OAuth key distribution

Key Bridge employs the OpenID Connect Dynamic Client Registration protocol for client registration. An OpenID Connect Relying Party can dynamically register with the Key Bridge OpenID service. Before participating in an OpenId transaction the Relying Party (RP, Client) must register with the Key Bridge OpenId service.

New registrations are placed in a disabled state until reviewed and approved by an administrator.

Client registration is indempotent and can be repeated as many times as needed. A client may re-register at any time to refresh their OAuth credentials and to receive a new shared secret.

Architecture

The authorization server acts as a trusted third party that provides session keys to clients and to resource servers. In order to obtain the session key the client interacts with the authorization server as part of the a normal grant exchange. This is shown in an abstract way below.

                       +---------------+
                      =|               |
                    //=| Authorization | * * * *
                   /   | Server        |      Key Distribution
                 //    | (this)        |      (Register Client API)
                /      |               |       *
         (I)  //      /+---------------+       *
   Access    /      //                         *
   Token    /      /                           *
   Request//     //  (II) Access Token         *
         /      /                              *
       //     //                               *
      /      v                                 v
    +-----------+  Authenticate  (a)    +------------+
    |           |----------------------=|            |
    |           |   [Access Token]      | Relying    |
    | End User  |                       | Party      |
    | (Human)   |  Authenticated (b)    | (Client)   |
    |           |=----------------------|            |
    +-----------+                       +------------+

    ****: Out-of-Band Long-Term Key Establishment
    ----: Dynamic Session Key Distribution

Interaction between the Client and the Authorization Server

Together with the access token the authorization server returns a session key and several other parameters.

User information

Implements User-Managed Access (UMA) Profile of OAuth 2.0

User-Managed Access (UMA) is a profile of OAuth 2.0 RFC6749. UMA defines how resource owners can control protected-resource access by clients operated by arbitrary requesting parties, where the resources reside on any number of resource servers, and where a centralized authorization server governs access based on resource owner policies. The User endpoint is an OAuth 2.0 Protected Resource that returns Claims about the authenticated End-User. To obtain the requested Claims about the End-User, the Client makes a request to the UserInfo Endpoint using an Access Token obtained through OpenID Connect Authentication. These Claims are represented by a JSON (or XML) object that contains a collection of name and value pairs for the Claims.

The User endpoint accepts Access Tokens as OAuth 2.0 Bearer Token Usage RFC 6749 and supports Cross Origin Resource Sharing to enable Java Script Clients to access the endpoint.

The UMA profile of OAuth is implemented in to three steps:

1. Protect a resource
2. Get authorization
3. Access a resource

These are illustrated below.

                                            +--------------+
                                            |   resource   |
           +---------manage (A)------------ |     owner    |
           |                                +--------------+
           |         Step 1:                       |
           |         protect a                control (C)
           |         resource                      |
           v                                       v
    +------------+               +----------+--------------+
    |            |               |protection|              |
    |  resource  |               |   API    | authorization|
    |   server   |=-protect (B)--|  (needs  |    server    |
    |            |               |   PAT)   |              |
    +------------+               +----------+--------------+
    | protected  |                          | authorization|
    | resource   |                          |     API      |
    |(needs RPT) |                          |  (needs AAT) |
    +------------+                          +--------------+
           ^                                       |
           |         Steps 2 and 3:          authorize (D)
           |         get authorization,            |
           |         access a resource             v
           |                                +--------------+
           +---------access (E)-------------|    client    |
                                            +--------------+
                                            requesting party

The Three steps of the UMA profile of OAuth

The authorization server orchestrates and controls clients' access on their requesting parties' behalf to a resource owner's protected resources at a resource server, under conditions specified by that resource owner through policy.

Scope values

OpenID Connect Clients use scope values, as defined in Section 3.3 of OAuth 2.0 RFC 6749, to specify what access privileges are being requested for Access Tokens. The scopes associated with Access Tokens determine what resources will be available when they are used to access OAuth 2.0 protected endpoints. Protected Resource endpoints MAY perform different actions and return different information based on the scope values and other parameters used when requesting the presented Access Token.

OpenID Connect defines the following scope values that are used to request Claims:

Request and response examples

Key Bridge proprietary implementation

OpenID Connect Core 1.0, Section 5.3. specifies that the UserInfo Endpoint MUST support the use of the HTTP GET and HTTP POST methods. Key Bridge only supports the GET method to retrieve UserInfo.

The following is a non-normative example of a UserInfo request:

GET /user/info HTTP/1.1
Host: server.example.com
Authorization: Bearer SlAV32hkKG

The following is a non-normative example of a UserInfo Response:

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

{
  "sub": "248289761001",
  "name": "Jane Doe",
  "given_name": "Jane",
  "family_name": "Doe",
  "preferred_username": "j.doe",
  "email": "janedoe@example.com",
  "picture": "http://example.com/janedoe/me.jpg"
}

Other User services follow a similar pattern.

Error response example

When an error condition occurs the User endpoint returns an Error Response as defined in Section 3 of OAuth 2.0 Bearer Token Usage [RFC6750]. (HTTP errors unrelated to RFC 6750 are returned to the User Agent using the appropriate HTTP status code.)

The following is a non-normative example of a User Error Response:

HTTP/1.1 401 Unauthorized
WWW-Authenticate: error="invalid_token",  error_description="The Access Token expired"