OpenID Connect Core 1.0

Key Bridge implements the OpenID Connect Core 1.0 specification for user authentication and authorization. OpenID Connect 1.0 is a simple identity layer on top of the OAuth 2.0 protocol. It enables Clients to verify the identity of the End-User based on the authentication performed by an Authorization Server, as well as to obtain basic profile information about the End-User in an interoperable and REST-like manner. The OpenID Connect protocol, in abstract, utilizes the following steps.

  1. The Relying Party (RP, Client) sends an authentication (AuthN) request to the OpenID Provider (OP, Server)
  2. The OP authenticates (AuthN) and authorizes (AuthZ) the End-User
  3. The OP responds with an AuthN Token and an AuthZ Access Token (which may be the same)
  4. The RP can send a request with the Access Token to the UserInfo Endpoint
  5. The UserInfo Endpoint returns Claims about the End-User

In the Key Bridge system the UserInfo EndPoint is integrated with the OpenID Provider. This sequence is illustrated below.

    +--------+                                   +--------+
    |       -+---------(1) AuthN Request--------=|        |
    |        |  +--------+                       |        |
    |        |  |  End-  |=--(2) AuthN & AuthZ--=|        |
    |        |  |  User  |                       |        |
    |   RP   |  |(Human) |                       |   OP   |
    |(Client)|  +--------+                       |(Server)|
    |        |=--------(3) AuthN Response--------|        |
    |       -+---------(4) UserInfo Request-----=|        |
    |        |=--------(5) UserInfo Response-----|        |
    +--------+                                   +--------+

Definitions

  • AuthN is a common abbreviation for authentication, for verifying a party's identity
  • AuthZ is a common abbreviation for authorization, for granting or denying access to a resource
  • RP is the Relying Party - the (client) party who relies upon OpenId services for AuthN and AuthZ capabilities
  • OP is the Offering Party - the (server) party who offers OpenId services
  • Client is an OpenID Relying Party.
  • End-User id a Human participant

Authentication using the Implicit Flow

OpenID Connect performs authentication to log in the End-User or to determine that the End-User is already logged in. OpenID Connect returns the result of the Authentication performed by the Server to the Client in a secure manner so that the Client can rely on it. The Authentication result is returned in an ID Token.

  • All tokens are returned from the Authorization Endpoint
  • The Access Token is returned directly to the Client
    • The Authorization Server does not perform Client Authentication

Implicit Flow Steps (J2EE)

The Implicit Flow follows the following steps, which are slightly modified to work with a J2EE application server. Specifically: The Authorization server authorizes an End User and a second UserScope REST query is added to enable the Client to authorize the End User.

  • Client prepares an Authentication Request containing the desired request parameters.
    • Client sends the request to the Authorization Server.
  • Authorization Server Authorization the End-User.
  • Authorization Server sends the End-User back to the Client with an ID Token.
  • Client validates the ID token .
  • Client retrieves the End-User's scope assignments.
    • Client authorizes End User based on End-User's scope assignments.

References

Implemented final (core) specifications in this application

Implemented draft specifications - now deprecated

Roadmap draft specifications - subject to change

Under review for future inclusion

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

API resources

https://keybridgewireless.com/openid/api/authorize

GET implementation of the POST Authorization Request method.

Parameters
Cookie string HEADER

A cookie set by the Key Bridge OpenID service. References an existing authenticated session.

Name = JSESSIONOPENID
Response
Response text/plain

On success an HTTP redirect with an authorization code. On error an HTTP redirect to the OpenId sign in page.

https://keybridgewireless.com/openid/api/authorize

OpenID end user authentication rest end point. This establishes (or renews) an OAuth session on the Key Bridge OpenId service linking the End User and the Client, and provides authentication for the End User to access the Client using the End User AuthN token and the Client's (previously issued) OAuth credentials. The client_id and redirect_uri are specified as query parameters, while the user OpenId session (if present) is retrieved from a browser cookie.

Parameters
Cookie string HEADER

A cookie set by the Key Bridge OpenID service when an End User presents a valid user name and password. The cookie references an authenticated session binding an End User and a Client on the OpenId service.

Name = JSESSIONOPENID
Response
Response text/plain

On success an HTTP redirect with an authorization code. On error an HTTP redirect to the OpenId sign in page.

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:

id-token-hintRECOMMENDEDPreviously issued ID Token passed to the logout endpoint as a hint about the End-User's current authenticated session with the Client. This is used as an indication of the identity of the End-User that the RP is requesting be logged out by the OP. The OP need not be listed as an audience of the ID Token when it is used as an id_token_hint value.
post-logout-redirect-uriOPTIONALURL to which the RP is requesting that the End-User's User Agent be redirected after a logout has been performed. The value MUST have been previously registered with the OP, either using the post_logout_redirect_uris Registration parameter or via another mechanism. If supplied, the OP SHOULD honor this request following the logout.
stateOPTIONALOpaque value used by the RP to maintain state between the logout request and the callback to the endpoint specified by the post_logout_redirect_uri query parameter. If included in the logout request, the OP passes this value back to the RP using the state query parameter when redirecting the User Agent back to the RP.

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.

API resources

https://keybridgewireless.com/openid/api/endsession

An 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.

Parameters
Cookie string HEADER

The user session id, presented in a Cookie named JSESSIONOPENID

Name = JSESSIONOPENID
Response
Response */*

On success an HTTP redirect to the RP indicated redirect_uri. On error a JSON-encoded error description.

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.

API resources

https://keybridgewireless.com/openid/api/register/{clientId}

RFC 7592 OAuth 2.0 Dynamic Registration Management Client Delete Request

To deprovision itself on the authorization server, the client makes an HTTP DELETE request to the client configuration endpoint. This request is authenticated by the registration access token issued to the client.

Parameters
clientId string TEMPLATE

The server assigned client id value

Response
Response application/json

On success an HTTP 204 No Content message

https://keybridgewireless.com/openid/api/register/{clientId}

RFC 7592 OAuth 2.0 Dynamic Registration Management Client Read Request

To read the current configuration of the client on the authorization server, the client makes an HTTP GET request to the client configuration endpoint, authenticating with its registration access token.

Parameters
clientId string TEMPLATE

The server assigned client id value

Response
Response application/json

The current OpenId Client Registration information

https://keybridgewireless.com/openid/api/register

OpenID Connect Dynamic Client Registration

An OpenID Connect Relying Party can dynamically register with the End-User's OpenID Provider, providing information about itself to the OpenID Provider, and obtaining information needed to use it, including the OAuth 2.0 Client ID for this Relying Party. The posted object is a fully populated, valid OpenIdClientRegistrationRequest instance configuration.

Response
Response application/json

A fully populated OpenIdClientRegistrationResponse instance configuration, which include extended OpenId provider details such as the login, logout, error and access_denied URIs.

https://keybridgewireless.com/openid/api/register/{clientId}

RFC 7592 OAuth 2.0 Dynamic Registration Management Client Update Request

To update a previously registered client's registration with an authorization server, the client makes an HTTP PUT request to the client configuration endpoint. This request is authenticated by the registration access token issued to the client.

Parameters
clientId string TEMPLATE

The server assigned client id value

Response
Response application/json

The updated OpenId Client Registration information

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:

profileOPTIONALThis scope value requests access to the End-User's default profile Claims, which are: name, family_name, given_name, middle_name, nickname, preferred_username, profile, picture, website, gender, birthdate, zoneinfo, locale, and updated_at.
emailOPTIONALThis scope value requests access to the email and email_verified Claims.
addressOPTIONALThis scope value requests access to the address Claim.
phoneOPTIONALThis scope value requests access to the phone_number and phone_number_verified Claims.
scopeOPTIONALA Key Bridge proprietary extension. Provides a user name and group assignments. This is used by J2EE server authentication modules and supports integration of OpenID into J2EE application servers.

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"

API resources

https://keybridgewireless.com/openid/api/user/{sub}/address

This is a Key Bridge proprietary extension of UMA.

Get the User Address Claim. The Address Claim represents a physical mailing address. Implementations MAY return only a subset of the fields of an address, depending upon the information available and the End-User's privacy preferences. For example, the country and region might be returned without returning more fine-grained address information. Implementations MAY return just the full address as a single string in the formatted sub-field, or they MAY return just the individual component fields using the other sub-fields, or they MAY return both. If both variants are returned, they SHOULD be describing the same address, with the formatted address indicating how the component fields are combined.

Parameters
Authorization string HEADER

Basic authorization header encoding the client_id and client_secret values.

sub string TEMPLATE

The subject UID; this should reference an individual party record

Response
Response application/json

The UserAddress information

https://keybridgewireless.com/openid/api/user/{sub}/info

This is a Key Bridge proprietary extension of UMA.

Request information about an authorized End User. The Client may send a UserInfo request using either HTTP GET or HTTP POST. GET is strongly preferred. The End User Access Token, encoded in the OpenID session cookie and obtained from an OpenID Connect Authentication request MUST be sent as a Bearer Token, per Section 2 of OAuth 2.0 Bearer Token Usage [RFC6750].

Parameters
Authorization string HEADER

Basic authorization header encoding the client_id and client_secret values.

sub string TEMPLATE

The subject UID; this should reference an individual party record

Response
Response application/json

Information about an authorized End User as indicated in the user info request scope.

https://keybridgewireless.com/openid/api/user/{sub}/settings

This is a Key Bridge proprietary extension of UMA.

Retrieve an End User's settings specific to a particular Client. In addition to a user profile, which is available via the getUserInfo endpoint, an End User's settings and preferences may also be centrally stored, set and updated on the Key Bridge OpenId service. User settings and preferences are conveyed and stored as arbitrary key/value pairs and are specific to the Client.

Parameters
Authorization string HEADER

Basic authorization header encoding the client_id and client_secret values.

sub string TEMPLATE

The subject UID; this should reference an individual party record

Response
Response application/json

On success: a Key Bridge proprietary UserSetting data transfer object containing the End User settings for the requesting client.

On error: a UserInfo response with an error message and corresponding description.

https://keybridgewireless.com/openid/api/user/address

User-Managed Access (UMA) Profile

Get the User Address Claim. The Address Claim represents a physical mailing address. Implementations MAY return only a subset of the fields of an address, depending upon the information available and the End-User's privacy preferences. For example, the country and region might be returned without returning more fine-grained address information. Implementations MAY return just the full address as a single string in the formatted sub-field, or they MAY return just the individual component fields using the other sub-fields, or they MAY return both. If both variants are returned, they SHOULD be describing the same address, with the formatted address indicating how the component fields are combined.

Parameters
Authorization string HEADER

The OpenId issued authorization code. This is also the End User AuthN Session ID for the requesting Client.

Response
Response application/json

The UserAddress information

https://keybridgewireless.com/openid/api/user/info

User-Managed Access (UMA) Profile

Request information about an authorized End User. The Client may send a UserInfo request using either HTTP GET or HTTP POST. GET is strongly preferred. The End User Access Token, encoded in the OpenID session cookie and obtained from an OpenID Connect Authentication request MUST be sent as a Bearer Token, per Section 2 of OAuth 2.0 Bearer Token Usage [RFC6750].

Parameters
Authorization string HEADER

The OpenId issued authorization code. This is also the End User AuthN Session ID for the requesting Client.

Response
Response application/json

Information about an authorized End User as indicated in the user info request scope.

https://keybridgewireless.com/openid/api/user/scope

User-Managed Access (UMA) Profile

Provides the username and scope information to enable basic OpenId authorization. This enables J2EE Clients to authorize (as opposed to authenticate) End Users based upon the End User's assigned scope, which is synonymous with J2EE group association.

Parameters
Authorization string HEADER

The OpenId issued authorization code. This is also the End User AuthN Session ID for the requesting Client.

Response
Response application/json

A simple UserScope message that conveys End User scope assignments with the OpenId provider.

https://keybridgewireless.com/openid/api/user/settings

This is a Key Bridge proprietary extension of UMA.

Set or update an End User's settings on the OpenId provider. This method allows registered (and enabled / authorized) Client applications to store End User settings and preferences on the OpenId service provider system.

Parameters
Authorization string HEADER

Basic authorization header encoding the client_id and client_secret values.

Response
Response application/json

On success: a simple HTTP code 200 OK.
On error: a UserInfo response with an error message and corresponding description.

© 2021Key Bridge Wireless All rights reserved. Unauthorized access prohibited3.4.5-210324_0004