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.
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
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.
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.
Implemented final (core) specifications in this application
Implemented draft specifications - now deprecated
Roadmap draft specifications - subject to change
Under review for future inclusion
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.
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
GET implementation of the POST Authorization Request method.
Cookie | string | HEADER | A cookie set by the Key Bridge OpenID service. References an existing authenticated session. Name = JSESSIONOPENID |
On success an HTTP redirect with an authorization code. On error an HTTP redirect to the OpenId sign in page.
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.
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 |
On success an HTTP redirect with an authorization code. On error an HTTP redirect to the OpenId sign in page.
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-hint | RECOMMENDED | Previously 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-uri | OPTIONAL | URL 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. |
state | OPTIONAL | Opaque 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
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.
Cookie | string | HEADER | The user session id, presented in a Cookie named |
On success an HTTP redirect to the RP indicated redirect_uri. On error a JSON-encoded error description.
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
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.
clientId | string | TEMPLATE | The server assigned client id value |
On success an HTTP 204 No Content message
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.
clientId | string | TEMPLATE | The server assigned client id value |
The current OpenId Client Registration information
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.
ResponseA fully populated OpenIdClientRegistrationResponse instance configuration, which include extended OpenId provider details such as the login, logout, error and access_denied URIs.
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.
clientId | string | TEMPLATE | The server assigned client id value |
The updated OpenId Client Registration 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:
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.
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:
profile | OPTIONAL | This 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. |
OPTIONAL | This scope value requests access to the email and email_verified Claims. | |
address | OPTIONAL | This scope value requests access to the address Claim. |
phone | OPTIONAL | This scope value requests access to the phone_number and phone_number_verified Claims. |
scope | OPTIONAL | A 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. |
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.
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
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.
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 |
The UserAddress information
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].
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 |
Information about an authorized End User as indicated in the user info request scope.
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.
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 |
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.
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.
Authorization | string | HEADER | The OpenId issued authorization code. This is also the End User AuthN Session ID for the requesting Client. |
The UserAddress information
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].
Authorization | string | HEADER | The OpenId issued authorization code. This is also the End User AuthN Session ID for the requesting Client. |
Information about an authorized End User as indicated in the user info request 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.
Authorization | string | HEADER | The OpenId issued authorization code. This is also the End User AuthN Session ID for the requesting Client. |
A simple UserScope message that conveys End User scope assignments with the OpenId provider.
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.
Authorization | string | HEADER | Basic authorization header encoding the client_id and client_secret values. |
On success: a simple HTTP code 200 OK.
On error: a UserInfo response with an error message and corresponding description.