Introduction
OpenID Connect 1.0 is a simple identity layer on top of the OAuth 2.0 [RFC6749] 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.
Protocols specifications:
OpenID Connect Core: https://openid.net/specs/openid-connect-core-1_0.html
- OpenID Connect Session Management: http://openid.net/specs/openid-connect-session-1_0.html
- OAuth 2.0 for Native Apps: https://tools.ietf.org/html/rfc8252
- Proof Key for Code Exchange by OAuth Public Clients: https://tools.ietf.org/html/rfc7636
- OAuth 2.0 Token Revocation: https://tools.ietf.org/html/rfc7009
Definitions
OpenID Connect implements authentication as an extension to the OAuth 2.0 authorization process.
Use of this extension is requested by Clients by including the openid scope value in the Authorization Request.
Information about the authentication performed is returned in a JSON Web Token (JWT) called an ID Token.
OAuth 2.0 Authentication Servers implementing OpenID Connect are also referred to as OpenID Providers (OPs).
OAuth 2.0 Clients using OpenID Connect are also referred to as Relying Parties (RPs).
Overview
- The RP (Client) sends a request to the OpenID Provider (OP).
- The OP authenticates the End-User and obtains authorization.
- The OP responds with an ID Token and usually an Access Token.
- The RP can send a request with the Access Token to the UserInfo Endpoint.
-
The UserInfo Endpoint returns Claims about the End-User.
Get Started
API Hosts
The CoffeeBean’s OIDC APIs can have different hosts according to customer and environment:
| Type | Host |
| Static | https://<environment>.socialidnow.com/v2/accounts/<account_name> |
| Subdomain | https://<account_name>[.|-]<environment>.socialidnow.com |
Contact our customer support to know which hosts were configured to your company.
Authentication
Authentication can follow one of three paths:
- Authorization Code Flow (response_type=code)
- Implicit Flow (response_type=id_token token or response_type=id_token)
Hybrid Flow (using other Response Type values defined in OAuth 2.0 Multiple Response Type Encoding Practices).
Authorization Code Flow
The authorization code flow is used to obtain both access tokens, id tokens and refresh tokens and is optimized for confidential clients (backend).
Authorization Request
Endpoint
GET |
<host>/oauth/authorize |
Parameters
response_type |
required | Value MUST be set to "code". |
client_id |
required | The client identifier. |
redirect_uri |
required | Redirection URI to which the response will be sent. |
scope |
required | OpenID Connect requests MUST contain the openid scope value. In addition, more scopes can be added (see Scopes session). |
state |
recommended | Opaque value used to maintain state between the request and the callback. |
nonce |
optional | String value used to associate a Client session with an ID Token, and to mitigate replay attacks. |
Request example
|
|
Response example
|
|
Error Response
See specification at https://tools.ietf.org/html/rfc6749#section-4.1.2.1 and https://openid.net/specs/openid-connect-core-1_0.html#AuthError.
Token Request
Endpoint
POST |
|
Authorization
Confidential clients or other clients issued client credentials MUST authenticate with the authorization server.
Clients may use the HTTP Basic authentication scheme or, alternatively, include the client credentials in the request-body using the parameters client_id and client_secret, as described in the parameters.
When using HTTP Basic authentication, the client identifier is encoded using the "application/x-www-form-urlencoded" encoding algorithm, and the encoded value is used as the username; the client password is encoded using the same algorithm and used as the password.
Parameters
grant_type |
required | Value MUST be set to "authorization_code". |
code |
required | The authorization code received from the authorization server. |
redirect_uri |
required | Value MUST be identical to the "redirect_uri" parameter included in the authorization request |
client_id |
required |
REQUIRED, if the client is not authenticating with the authorization server. |
client_secret |
required |
REQUIRED, if the client is not authenticating with the authorization server. |
Request example (with HTTP Basic Authentication)
|
|
Request example (with request-body client parameters)
|
|
Response example
|
|
Error Response
See specification at https://tools.ietf.org/html/rfc6749#section-5.2.
Implicit Flow
The implicit grant type is used to obtain id tokens and access tokens (it does not support the issuance of refresh tokens) and is optimized for public clients known to operate a particular redirection URI. These clients are typically implemented in a browser using a scripting language such as JavaScript.
Authorization Request
Endpoint
GET |
<host>/oauth/authorize |
Parameters
response_type |
required | Value MUST be set to “id_token token” or “id_token” |
client_id |
required | The client identifier. |
redirect_uri |
required | Redirection URI to which the response will be sent. |
scope |
required | OpenID Connect requests MUST contain the openid scope value. In addition, more scopes can be added (see Scopes session). |
state |
recommended | Opaque value used to maintain state between the request and the callback. |
nonce |
required | String value used to associate a Client session with an ID Token, and to mitigate replay attacks. |
Request example
|
|
Response example
|
|
Error Response
See specification at https://tools.ietf.org/html/rfc6749#section-4.1.2.1 and https://openid.net/specs/openid-connect-core-1_0.html#AuthError.
ID Token
The ID Token is a security token that contains Claims about the Authentication of an End-User by an Authorization Server when using a Client, and potentially other requested Claims. The ID Token is represented as a JSON Web Token (JWT).
The following Claims are used within the ID Token for all OAuth 2.0 flows used by OpenID Connect:
| iss | required | Issuer Identifier for the Issuer of the response. |
| sub | required | Subject Identifier (user_id). |
| aud | required | Audience(s) that this ID Token is intended for. In the general case, the aud value is an array of case sensitive strings. In the common special case when there is one audience, the aud value MAY be a single case sensitive string. |
| exp | required | Expiration time on or after which the ID Token MUST NOT be accepted for processing. |
| iat | required | Time at which the JWT was issued. |
| nonce | it depends | String value used to associate a Client session with an ID Token, and to mitigate replay attacks. If present in the Authentication Request, Authorization Servers MUST include a nonce Claim in the ID Token with the Claim Value being the nonce value sent in the Authentication Request. |
| at_hash | it depends | Access Token hash value. If the ID Token is issued from the Authorization Endpoint with an access_token value, which is the case for the response_type value id_token token, this is REQUIRED |
Additional Claims
Additional claims required in the scopes will be added to the ID token using a namespace to avoid collision names as recommended by OpenID specification.
Example:
| Scope: | openid datastore.user_data |
| ID Token Claim: | https://api.socialidnow.com/datastore.user_data |
Security
The ID Token will be signed using the MAC based HS256 algorithm. The octets of the UTF-8 representation of the client_secret corresponding to the client_id contained in the aud (audience) Claim are used as the key to validate the signature. The client_secret value MUST contain at least 32 octets.
Scopes
For OpenID Connect, scopes can be used to request that specific sets of information be made available as Claim Values.
The available scopes are:
openid |
required | OpenID Connect requests MUST contain the openid scope value. |
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. |
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 phone_number and phone_number_verified Claims. |
user_data |
optional | This scope value requests access to all fields from the Datastore schema named “user_data” to be added as an additional Claim. |
datastore.[schema] |
optional | This scope value requests access to all fields from the Datastore schema named [schema] to be added as an additional Claim. |
Userinfo Endpoint
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 normally represented by a JSON object that contains a collection of name and value pairs for the Claims.
Communication with the UserInfo Endpoint MUST utilize TLS.
The UserInfo Endpoint MUST support the use of the HTTP GET and HTTP POST methods defined in RFC 2616.
The UserInfo Endpoint MUST accept Access Tokens as OAuth 2.0 Bearer Token Usage [RFC6750].
The UserInfo Endpoint SHOULD support the use of Cross Origin Resource Sharing (CORS) and or other methods as appropriate to enable JavaScript Clients to access the endpoint.
Endpoint
GET|POST |
|
Logout Endpoint
The logout endpoint follows the specification from RP-Initiated Logout. An Relying Party (RP) can notify the OpenID Provider (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.
Endpoint
GET|POST |
<host>/oauth/logout |
Parameters
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. |
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. 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. |
Revoke Endpoint
Endpoint
POST |
|
Parameters
token |
required | The token that the client wants to get revoked. |
token_type_hint |
optional | A hint about the type of the token submitted for revocation. Allowed values: access_token, refresh_token |
Request example
With HTTP Basic Authentication
|
|
Response
The authorization server responds with HTTP status code 200 if the token has been revoked successfully or if the client submitted an invalid token.
Example
|
|