OpenID Connect Core 1.0

This resource implements the OpenID Connect Core 1.0 specification. The OpenID Connect protocol, in abstract, follows the following steps.

  1. The RP (Client) sends a request to the OpenID Provider (OP)
  2. The OP authenticates the End-User
  3. The OP responds with an ID Token and an Access Token
  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

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

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

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


Cookie JSESSIONOPENID
string HEADER

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


HTTP 200
text/plain

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 clientid and redirecturi are specified as query parameters, while the user OpenId session (if present) is retrieved from a browser cookie.

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


Cookie JSESSIONOPENID
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.


Parameters are submitted as application/x-www-form-urlencoded


HTTP 200
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 endsessionendpoint 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 idtokenhint 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 postlogoutredirect_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 postlogoutredirect_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.

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


HTTP 200
application/json

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

Before participating in an OpenId transaction the Relying Party (Client) must register with the Key Bridge OpenId service. New Client 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. These session keys are used by the client and the resource server as input to a MAC. 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. Together with the access token the authorization server returns a session key (in the mac_key parameter) and several other parameters. The resource server obtains the session key via the access token.

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

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

Interaction between the Client and the Authorization Server

API resources

OpenId Client registration resource. Enables automated registration of new Clients and provides automated generation and issuance of new OAuth credentials to existing Clients.

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


ClientRegistrationRequest
application/json application/xml

A complete description of the Client relying party. This includes the client's specified context_root plus several client-specific parameters such as operating system and hardware address.


HTTP 200
application/json

An OpenId client registration response, which include important OpenId service provider configurations such as the login, logout, error and accessdenied_ URIs plus OAuth credentials. The response is an extended MacAccessTokenResponse (which extends the OAuth AccessTokenResponse).

OpenId token endpoint

To obtain an Access Token, an ID Token, and optionally a Refresh Token, the RP (Client) sends a Token Request to the Token Endpoint to obtain a Token Response, as described in Section 3.2 of OAuth 2.0 [RFC6749], when using the Authorization Code Flow.

Non standard implementation.

This resource does not generate new tokens. Instead it echos back the existing End User AuthN token to the requesting client. This is to enable Authorization flow clients to use the Key Bridge J2EE service if desired.

Key Bridge uses OpenId Implicit flow, which does not use this Token resource. Tokens are used in the Authorization Code flow.

Request and response

A Client makes a Token Request by presenting its Authorization Grant (in the form of an Authorization Code) to the Token Endpoint using the granttype value authorizationcode, as described in Section 4.1.3 of OAuth 2.0 RFC6749. The following is a non-normative example of a Token Request (with line wraps within values for display purposes only):

  POST /token HTTP/1.1
  Host: server.example.com
  Content-Type: application/x-www-form-urlencoded
  Authorization: Basic czZCaGRSa3F0MzpnWDFmQmF0M2JW

  grant_type=authorization_code
  &code=SplxlOBeZQQYbYS6WxSbIA
  &redirect_uri=https%3A%2F%2Fclient.example.org%2Fcb

After receiving and validating a valid and authorized Token Request from the Client, the Authorization Server returns a successful response that includes an ID Token and an Access Token. The parameters in the successful response are defined in Section 4.1.4 of OAuth 2.0 RFC6749. The response uses the application/json media type.

The following is a non-normative example of a successful Token Response.

  HTTP/1.1 200 OK
  Content-Type: application/json
  Cache-Control: no-store
  Pragma: no-cache

  {
  "access_token": "SlAV32hkKG",
  "token_type": "Bearer",
  "refresh_token": "8xLOxBtZp8",
  "expires_in": 3600,
  "id_token": "eyJhbGciOiJSUzI1NiIsImtpZCI6IjFlOWdkazcifQ.ewogImlzc
     yI6ICJodHRwOi8vc2VydmVyLmV4YW1wbGUuY29tIiwKICJzdWIiOiAiMjQ4Mjg5
     NzYxMDAxIiwKICJhdWQiOiAiczZCaGRSa3F0MyIsCiAibm9uY2UiOiAibi0wUzZ
     fV3pBMk1qIiwKICJleHAiOiAxMzExMjgxOTcwLAogImlhdCI6IDEzMTEyODA5Nz
     AKfQ.ggW8hZ1EuVLuxNuuIJKX_V8a_OMXzR0EHR9R6jgdqrOOF4daGU96Sr_P6q
     Jp6IcmD3HP99Obi1PRs-cwh3LO-p146waJ8IhehcwL7F09JdijmBqkvPeB2T9CJ
     NqeGpe-gccMg4vfKjkM8FcGvnzZUN4_KSP0aAp1tOJ1zZwgjxqGByKHiOtX7Tpd
     QyHE5lcMiKPXfEIQILVq0pc_E2DzL7emopWoaoZTF_m0_N0YzFC6g6EJbOEoRoS
     K5hoDalrcvRYLSrQAZZKflyuVCyixEoV9GfNQC3_osjzw2PAithfubEEBLuVVk4
     XUVrWOLrLl0nx7RkKU8NXNHq-rvKMzqg"
  }

Token error response

If the Token Request is invalid or unauthorized, the Authorization Server constructs the error response. The parameters of the Token Error Response are defined as in Section 5.2 of OAuth 2.0 [RFC6749]. The HTTP response body uses the application/json media type with HTTP response code of 400. The following is a non-normative example Token Error Response:

  HTTP/1.1 400 Bad Request
  Content-Type: application/json
  Cache-Control: no-store
  Pragma: no-cache

  {
    "error": "invalid_request"
  }

API resources

Makes a Token Request by presenting the End User Authorization Grant (in the form of an Authorization Code) and the Client OAuth consumer key (as the Authorization header).

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


Parameters are submitted as application/x-www-form-urlencoded


HTTP 200
application/json

On success: a new OAuth Token Response. On error: an error message and description.

UserInfo

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

The UserInfo 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 UserInfo Endpoint accepts Access Tokens as OAuth 2.0 Bearer Token Usage RFC 6749.

The UserInfo Endpoint support the use of Cross Origin Resource Sharing (CORS) CORS to enable Java Script Clients to access the endpoint.

UMA is a profile of OAuth 2.0 that 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. Resource owners configure authorization servers with access policies that serve as asynchronous authorization grants.

The UMA Profile of OAuth has three broad phases:

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

These are illustrated below.

                                            +--------------+
                                            |   resource   |
           +---------manage (A)------------ |     owner    |
           |                                +--------------+
           |         Phase 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) |
    +------------+                          +--------------+
           ^                                       |
           |         Phases 2 and 3:         authorize (D)
           |         get authorization,            |
           |         access a resource             v
           |                                +--------------+
           +---------access (E)-------------|    client    |
                                            +--------------+
                                            requesting party

The Three Phases 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:

  • profile OPTIONAL. This scope value requests access to the End-User's default profile Claims, which are: name, familyname, givenname, middlename, nickname, preferredusername, profile, picture, website, gender, birthdate, zoneinfo, locale, and updated_at.
  • email 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 phonenumber and phonenumber_verified Claims.

Key Bridge defines the following additional scope values:

  • scope 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

The following is a non-normative example of a UserInfo (and UserScope) request:

  GET|POST /userinfo HTTP/1.1
  Host: server.example.com
  Authorization: Bearer <span class="text-danger">SlAV32hkKG</span>

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"
  }

Error response example

When an error condition occurs, the UserInfo 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 UserInfo Error Response:

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

API resources

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

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


HTTP 200
application/json

the UserAddress information

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

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


HTTP 200
application/json

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

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.

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


HTTP 200
application/json

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

Retrieve an End User's settings for a particular Client. In addition to a user profile, which is available via the UserInfo end point, 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.

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


HTTP 200
application/json

On success: a 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.

POST implementation of the GET method. Prefer NOT to use this method. Use GET instead.

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


Parameters are submitted as application/x-www-form-urlencoded


HTTP 200
application/json

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

Rest method to 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.

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


Parameters are submitted as application/x-www-form-urlencoded


HTTP 200
application/json

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