OIDC 1.0
Basics
OpenID Connect (OIDC) is an authentication protocol, based on OAuth 2.0 protocol specifications. It uses JSON Web Tokens (JWT), which can be obtained using workflows conforming to OAuth 2.0 protocol specifications.
OAuth 2.0 is mainly used for resource access and sharing purposes, whereas OIDC is used for handling user authentication process. Its main purpose is to provide an end user with one login flow for multiple web sites or applications. Each time an end user needs to login to web using OIDC, he will be redirected to an OIDC endpoint where the user must authenticate against and then taken to the intended web.
For example, when a web application prompts a user to authenticate using a Google or Facebook credentials then the web application is presumably using OIDC protocol. The protocol allows a wide range of applications, including Mobile, Web and JavaScript apps, to request and receive information about authenticated users and sessions.
mID Provider(IAM) provides a customized connector capability that makes it easier to configure an OIDC enabled application to use mID Provider(IAM) platform as an Identity Provider (IdP) in an OIDC work flow.
Why use OIDC for my application?
OIDC protocol is more straightforward to integrate than SAML protocol and can work with a variety of applications. Particularly, it provides the following:
Consumable identity tokens
Client applications receive an end-user’s identity encapsulated in a JSON Web Token (JWT) called an Identity Token or just an ID token. JWTs are simple and convenient that supports a variety of signature and encryption algorithms.
OAuth 2.0 protocol
Client applications use OAuth 2.0 workflows to get ID tokens, which work with web applications including native mobile applications. By using OAuth 2.0 workflows, you deal with one protocol for authentication and authorization (get access token) purposes.
Robust capabilities
OIDC is very easy to integrate with simple applications, while also providing with features and other security benefits that can meet appealing business requirements.
How it works?
For a high level overview on how OIDC flow works, let us use the same example as we mentioned before, i.e., signing into a web application using a Facebook or Google account:
- When a user choose the option to sign in to web application using Facebook or Google account, then the web application sends an Authorization Request to Facebook or Google.
- Facebook or Google then authenticates the user credentials or requests the user to login if he is not already logged in, and then requests for his authorization (displays all the permissions that web application requires, for example user's e-mail address, and also requests the user if it is ok with to continue further).
- Once the user authenticates and authorizes the sign in, Facebook or Google sends an Access Token and also an ID Token (if requested) back to the web application.
- Web application then retrieves all the user information from an ID Token or make use of the Access Token to invoke an API (Facebook or Google).
Access Tokens
These are credentials that can be used by client applications to invoke an API. The tokens can be a non-JWT token or a JWT Token. The main purpose of this token is to provide information to the API that the bearer of this particular token has been granted or acknowledged with authorization access to the API and request explicit actions (as defined by the scopes).
Identity or ID Tokens
These are JWT Tokens that consists of identity information. The information is consumed by client application and contains information like user's first name, last name, given name, email etc., generally used to display on the UI. An ID Token conforms to industry specific standardization (RFC 7519) and contains three distinct parts: header, body and signature.
Flows
OIDC presents the below authentication flows. These flows guides how an authentication is handled by an OIDC Provider and what can be sent to an application.
The table below summarizes the characteristics of all the flows mentioned above:
| Property | Authorization Code Flow | Implicit Flow | Hybrid Flow |
|---|---|---|---|
| All tokens(ID token and Access token) returned from Authorization Endpoint | No | Yes | No |
| All tokens(ID token and Access token) returned from Token Endpoint | Yes | No | No |
| Tokens not revealed to User Agent | Yes | No | No |
| Client can be authenticated | Yes | No | Yes |
| Refresh Token possible | Yes | No | Yes |
| Communication in one round trip | No | Yes | No |
| Most communication server-to-server | Yes | No | Varies |
Response types
The flow used is determined by the response_type value contained in the Authorization Request. These response_type values select the flows:
| "response_type" value | Flow |
|---|---|
| code | Authorization Code Flow |
| id_token | Implicit Flow |
| id_token token | Implicit Flow |
| code id_token | Hybrid Flow |
| code token | Hybrid Flow |
| code id_token token | Hybrid Flow |
Implicit flow
This is a browser-based protocol that is similar to Authorization Code Flow except there are fewer requests and no refresh tokens involved. We do not recommend this flow as there remains the possibility of access tokens being leaked in the browser history as tokens are transmitted via redirect URIs (see below). Also, since this flow doesn’t provide the client with a refresh token, access tokens would either have to be long-lived or users would have to re-authenticate when they expired. This flow is supported because it is in the OIDC and OAuth 2.0 specification. Here’s a brief summary of the protocol:
- A session is started by the client by passing in the client ID (unique per client) and is redirected to an IdP.
- The IdP initiates authentication and authorization of the user for a specific instance.
- The user data is encoded by the IdP into an ID Token that consists of user information (scopes) (or) an ID token and Access token as per the response_type selected. This token is transmitted to a pre-configured redirection page (Redirect URI) on a web server.
- The client validates the ID token and retrieves the end user's subject identifier.If everything is verified, a secure session is established.
Endpoints involved in the Implicit Code Flow
- Authorization Endpoint - 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 above. When using the Implicit Flow, all tokens are returned from the Authorization Endpoint; the Token Endpoint is not used.
mIdentity uses the following request parameters with the Implicit Code Flow:
| Request Parameter | Required? | Description |
|---|---|---|
| scope | Required | OpenID Connect requests MUST contain the openid scope value. If the openid scope value is not present, the behavior is entirely unspecified. Other scope values MAY be present. Scope values used that are not understood by an implementation SHOULD be ignored. |
| response_type | Required | OAuth 2.0 Response Type value that determines the authorization processing flow to be used, including what parameters are returned from the endpoints used. When using the Implicit Flow, this value is id_token token or id_token. NOTE: While OAuth 2.0 also defines the token Response Type value for the Implicit Flow, OpenID Connect does not use this Response Type, since no ID Token would be returned. |
| client_id | Required | The Client Identifier(website or mobile app identifier) valid at the Authorization Server. |
| redirect_uri | Required | Redirection URI to which the response will be sent. This URI MUST exactly match one of the Redirection URI values for the Client pre-registered at the OpenID Provider.When using this flow, the Redirection URI MUST NOT use the http scheme unless the Client is a native application, in which case it MAY use the http: scheme with localhost as the hostname. |
| nonce | Required | String value used to associate a Client session with an ID Token, and to mitigate replay attacks. The value is passed through unmodified from the Authentication Request to the ID Token. Sufficient entropy MUST be present in the nonce values used to prevent attackers from guessing values. |
| state | Recommended | Opaque value used to maintain state between the request and the callback. Typically, Cross-Site Request Forgery (CSRF, XSRF) mitigation is done by cryptographically binding the value of this parameter with a browser cookie. |
| response_mode | Optional | Informs the Authorization Server of the mechanism to be used for returning parameters from the Authorization Endpoint. This use of this parameter is NOT RECOMMENDED when the Response Mode that would be requested is the default mode specified for the Response Type. |
| consent | Required | The Authorization Server SHOULD prompt the End-User for consent before returning information to the Client. If it cannot obtain consent, it MUST return an error, typically consent_required. |
Following are the parameters returned from the Authorization Endpoint:
| Response Parameter | Required? | Description |
|---|---|---|
| access_token | Required | OAuth 2.0 Access Token. This is returned unless the response_type value used is id_token. |
| token_type | Required | The value MUST be Bearer or another token_type value that the Client has negotiated with the Authorization Server. This profile only describes the use of bearer tokens. This is returned in the same cases as access_token is. |
| id_token | Required | ID Token. |
| state | REQUIRED if the state parameter is present in the Authorization Request. | Clients MUST verify that the state value is equal to the value of state parameter in the Authorization Request. |
| expires_in | Optional | Expiration time of the Access Token in seconds since the response was generated. |
Authorization flow
This flow can be used for client applications that has backend or back channel communication with the IdP. It operates like a conventional OAuth flow which results in an Access Token returned in secret to a client application via sequence of calls executed on the back channel. During the flow, instead of transmitting user data, the IdP transmits a special authorization_code that can be exchanged for an Access Token via back channel services. In addition to authorization_code, the exchange also includes a client ID and secret (similar to OAuth 2.0 flow). This flow is even more secure than Implicit flow, because the tokens are not visible through any development tools on the browser.
- A session is started by the client by passing in the client ID (unique per client) and is redirected to an IdP.
- The IdP initiates authentication and authorization of the user for a specific instance.
- Authorization Server obtains End-User Consent/Authorization.
- An authorization_code is transmitted back to the web server using a pre-configured redirection page (Redirect URI).
- Next, the web server transmits the authorization_code, client ID, and secret to the IdP token endpoint which is validated by the IdP and returns an Access Token.
- The web server utilizes the access token to obtain further information about the user (if required) and a secure session is established.
Endpoints involved in the Authorization Code Flow
-
Authorization Endpoint - 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 above. This endpoint returns the authorization code which could be exchanged for an access token, embedded in the redirect_uri.
-
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, when using the Authorization Code Flow. Returns the Access token in exchange to the authorization code.
-
Token introspection Endpoint - To validate the Access token and ID token obtained via the Token Endpoint.
mIdentity uses the following request parameters with the Authorization Code Flow:
| Request Parameter | Required? | Description |
|---|---|---|
| scope | Required | OpenID Connect requests MUST contain the openid scope value. If the openid scope value is not present, the behavior is entirely unspecified. Other scope values MAY be present. Scope values used that are not understood by an implementation SHOULD be ignored. |
| response_type | Required | OAuth 2.0 Response Type value that determines the authorization processing flow to be used, including what parameters are returned from the endpoints used. When using the Authorization Code Flow, this value is code. |
| client_id | Required | The Client Identifier(website or mobile app identifier) valid at the Authorization Server. |
| redirect_uri | Required | Redirection URI to which the response will be sent. This URI MUST exactly match one of the Redirection URI values for the Client pre-registered at the OpenID Provider, with the matching performed.When using this flow, the Redirection URI SHOULD use the https scheme; however, it MAY use the http scheme, provided that the Client Type is confidential, and provided the OP allows the use of http Redirection URIs in this case. The Redirection URI MAY use an alternate scheme, such as one that is intended to identify a callback into a native application. |
| state | Recommended | Opaque value used to maintain state between the request and the callback. Typically, Cross-Site Request Forgery (CSRF, XSRF) mitigation is done by cryptographically binding the value of this parameter with a browser cookie. |
| response_mode | Optional | Informs the Authorization Server of the mechanism to be used for returning parameters from the Authorization Endpoint. This use of this parameter is NOT RECOMMENDED when the Response Mode that would be requested is the default mode specified for the Response Type. |
| nonce | Optional | String value used to associate a Client session with an ID Token, and to mitigate replay attacks. The value is passed through unmodified from the Authentication Request to the ID Token. Sufficient entropy MUST be present in the nonce values used to prevent attackers from guessing values. |
| consent | Required | The Authorization Server SHOULD prompt the End-User for consent before returning information to the Client. If it cannot obtain consent, it MUST return an error, typically consent_required. |
Hybrid flow
This flow is a combination of both Implicit and Authorization flows. This flow can be used to obtain an authorization_code and respective tokens from authorization endpoint, and can also request tokens from token endpoint.
Endpoints involved in the Hybrid Code Flow
-
Authorization Endpoint - 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 above. This endpoint returns the authorization code which could be exchanged for an access token, embedded in the redirect_uri.
-
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, when using the Hybrid Code Flow. Returns the Access token in exchange to the authorization code.
-
Token introspection Endpoint - To validate the Access token and ID token obtained via the Token Endpoint.
mIdentity uses the following request parameters with the Hybrid Code Flow:
| Request Parameter | Required? | Description |
|---|---|---|
| scope | Required | OpenID Connect requests MUST contain the openid scope value. If the openid scope value is not present, the behavior is entirely unspecified. Other scope values MAY be present. Scope values used that are not understood by an implementation SHOULD be ignored. |
| response_type | Required | OAuth 2.0 Response Type value that determines the authorization processing flow to be used, including what parameters are returned from the endpoints used. When using the Hybrid Flow, this value is code id_token, code token, or code id_token token. |
| client_id | Required | The Client Identifier(website or mobile app identifier) valid at the Authorization Server. |
| redirect_uri | Required | Redirection URI to which the response will be sent. This URI MUST exactly match one of the Redirection URI values for the Client pre-registered at the OpenID Provider, with the matching performed.When using this flow, the Redirection URI SHOULD use the https scheme; however, it MAY use the http scheme, provided that the Client Type is confidential, and provided the OP allows the use of http Redirection URIs in this case. The Redirection URI MAY use an alternate scheme, such as one that is intended to identify a callback into a native application. |
| state | Recommended | Opaque value used to maintain state between the request and the callback. Typically, Cross-Site Request Forgery (CSRF, XSRF) mitigation is done by cryptographically binding the value of this parameter with a browser cookie. |
| response_mode | Optional | Informs the Authorization Server of the mechanism to be used for returning parameters from the Authorization Endpoint. This use of this parameter is NOT RECOMMENDED when the Response Mode that would be requested is the default mode specified for the Response Type. |
| nonce | Optional | String value used to associate a Client session with an ID Token, and to mitigate replay attacks. The value is passed through unmodified from the Authentication Request to the ID Token. Sufficient entropy MUST be present in the nonce values used to prevent attackers from guessing values. |
| consent | Required | The Authorization Server SHOULD prompt the End-User for consent before returning information to the Client. If it cannot obtain consent, it MUST return an error, typically consent_required. |
Refresh Token flow
This type of grant is used by client applications to exchange a Refresh Token for an Access Token when the Access Token has expired.
This enables client applications to continue with valid Access Tokens without the need for interaction with users.
Endpoints involved in the Refresh token Flow
- 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 Respons. Returns the Access token in exchange to the Refresh token, when using the Refresh Token flow.
mIdentity uses the following request parameters with the Refresh Token Flow
| Request Parameter | Required? | Description |
|---|---|---|
| grant_type | Required | This must be refresh_token. |
| refresh_token | Required | The refresh token to be exchanged for an Access token. |
| scope | Optional | This is mandatory if the scope is other than openid |
| client_id | Required | The Client Identifier(website or mobile app identifier) valid at the Authorization Server. |
| client_secret | Required | The secure secret secret assigned to the Client to Authenticate the client at the Authorization Server. |
Password Grant
This type of grant is used for the purpose of exchanging user's credentials for an Access Token. It is not recommended to use this type of grant, because a client application will gather user's password to transmit the same to an IdP server.
Additionally, this flow is very limited in practical use because it does not enable any mechanisms for Multi-Factor Authentication (MFA) or Account Delegations.
Endpoints involved in the Password Flow
- 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 Respons. Returns the Access token in exchange to the Resource Owner's credentials, when using the Password flow.
mIdentity uses the following request parameters with the Password Flow
| Request Parameter | Required? | Description |
|---|---|---|
| grant_type | Required | This must be password. |
| client_id | Required | The Client Identifier(website or mobile app identifier) valid at the Authorization Server. |
| client_secret | Required | The secure secret secret assigned to the Client to Authenticate the client at the Authorization Server. |
| client_secret | Required | The application password. |
| scope | Optional | This is mandatory if the scope is other than openid |
Client Credentials Grant
This type of grant is used by client applications to obtain Access Tokens outside user's context.
This flow is typically used by client applications to gain access to resources about their own context (application context) and do not take part to gain access to user's resources.
Endpoints involved in the Client Credentials Flow
- 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 Respons. Returns the Access token in exchange to the Client ID and Client Secret, when using the Client credentials flow.
mIdentity uses the following request parameters with the Client Credentials Flow
| Request Parameter | Required? | Description |
|---|---|---|
| grant_type | Required | This must be client_credentials. |
| client_id | Required | The Client Identifier(website or mobile app identifier) valid at the Authorization Server. |
| client_secret | Required | The secure secret secret assigned to the Client to Authenticate the client at the Authorization Server. |
| scope | Optional | This is mandatory if the scope is other than openid |
Scopes
A Scope is a mechanism used in OAuth 2.0 in which claims are grouped together as a separated list of identifiers to define access privileges to a user. Scopes combined together with Access Tokens will determine the resources available to access OAuth 2.0 endpoints.
In OIDC, the information of a defined scope is presented as claim value in the Access Token, that is returned after a successful authentication, also via User Info endpoint. In simple terms, claims are nothing but name/value pairs that consists of information about a user including some metadata about OIDC service.
Types of Scopes
Scopes are categorized into following types:
Identity scopes
Requesting claims (or identity information) about a user, example, first name, last name, given name or e-mail address is designed as a scope in OIDC. For example, there exists a scope called "profile" that contains user information like name, family_name, preferred_username, gender, birthdate, picture etc.
Resource scopes
These scopes identifies Resource Servers (or Web APIs) - example, a scope named weather that represents a weather API.
Standard Scopes
Following are a list of standard OIDC scopes that returns a set of standard claims.
| Scopes | Type | Description |
|---|---|---|
| openid * required | string | This scope is mandatory which is used to inform Authorization server about the OIDC request and returns a sub-claim which is a unique ID for the user. |
| profile | string | This scope used for requesting access to user’s default claims which are: name, family_name, given_name, middle_name, nickname, preferred_username, profile, picture, website, gender, birthdate, zoneinfo, locale, and updated_at.Note: The claims are returned if mIDentity has the information. |
| offline_access | string | Version 2.0 only. When this scope is provided with password grant, a Refresh_Token which allows for offline access is returned. |
KOBIL Specific Scopes
Apart from the above standard scopes, mIDentiy One platform provides KOBIL Specific Scopes.
| Scopes | Types | Description |
|---|---|---|
| kobil_password | string | This scope requires mID Server(SSMS) PAM password to be used for authentication purpose. |
| kobil_oneshot | string | This scope requires verification token to be transmitted via URL query parameter: login_otp for authentication purpose. |
Claims
These are set of user attributes (example, name/value pairs that consists of user information). The attributes are returned based on requested scope during authentication flow. In simple terms, a scope is a set of claims.
OIDC specifies a set of standard claims. The set of standard claims are listed in the table below. However, if you need to capture information about a user, then there is no standard claim at the moment that best describes this piece of information. For that you need to generate a custom claim and attach it to a token.
| Claim | Type | Description |
|---|---|---|
| sub | string | Subject - Identifier for the End-User at the Issuer. |
| name | string | End-User's full name in displayable form including all name parts, possibly including titles and suffixes, ordered according to the End-User's locale and preferences. |
| given_name | string | Given name(s) or first name(s) of the End-User. Note that in some cultures, people can have multiple given names; all can be present, with the names being separated by space characters. |
| family_name | string | Surname(s) or last name(s) of the End-User. Note that in some cultures, people can have multiple family names or no family name; all can be present, with the names being separated by space characters. |
| middle_name | string | Middle name(s) of the End-User. Note that in some cultures, people can have multiple middle names; all can be present, with the names being separated by space characters. Also note that in some cultures, middle names are not used. |
| nickname | string | Casual name of the End-User that may or may not be the same as the given_name. For instance, a nickname value of Mike might be returned alongside a given_name value of Michael. |
| preferred_username | string | Shorthand name by which the End-User wishes to be referred to at the RP, such as Jane doe or j.doe. This value MAY be any valid JSON string including special characters such as @, /, or whitespace. |
| profile | string | URL of the End-User's profile page. |
| picture | string | URL of the End-User's profile picture. This URL MUST refer to an image file (for example, a PNG, JPEG, or GIF image file), rather than to a Web page containing an image. Note that this URL SHOULD specifically reference a profile photo of the End-User suitable for displaying when describing the End-User, rather than an arbitrary photo taken by the End-User. |
| website | string | URL of the End-User's Web page or blog. This Web page SHOULD contain information published by the End-User or an organization that the End-User is affiliated with. |
| string | End-User's preferred e-mail address. | |
| email_verified | boolean | True if the End-User's e-mail address has been verified; otherwise false. When this Claim Value is true, this means that the OP took affirmative steps to ensure that this e-mail address was controlled by the End-User at the time the verification was performed. The means by which an e-mail address is verified is context-specific, and dependent upon the trust framework or contractual agreements within which the parties are operating. |
| gender | string | End-User's gender. Values defined by this specification are female and male. Other values MAY be used when neither of the defined values are applicable. |
| birthdate | string | End-User's birthday, represented in YYYY-MM-DD format. |
| zoneinfo | string | String from zoneinfo time zone database representing the End-User's time zone. |
| locale | string | End-User's locale, represented as a language tag. For example, en-US or fr-CA. |
| phone_number | string | End-User's preferred telephone number. |
| phone_number_verified | boolean | True if the End-User's phone number has been verified; otherwise false. |
| address | JSON object | End-User's preferred postal address |
| updated_at | number | Time the End-User's information was last updated. Its value is a JSON number representing the number of seconds from 1970-01-01T0:0:0Z as measured in UTC until the date/time. |
Reference: https://openid.net/specs/openid-connect-core-1_0.html#StandardClaims
Glossary
OIDC Provider
This is an identity server that implements OpenID Connect 1.0 Protocol and OAuth 2.0. Primarily an identity server authenticates users via an external identity provider, manages and authenticates clients, provides session management, provides single sign-on, issues and validates identity(ID tokens) and Access tokens.
Resource
Resource is the user data or information that needs to be protected. It could be identity information of the user such as profile data, email address etc.
Scopes
Scopes are unique IDs for resources that a client application wants to access. This identifier is sent to an OIDC provider during an authentication/token request.
Claims
Claims are set of user attributes (example, name/value pairs that consists of user information). The attributes are returned based on requested scope during authentication flow. In simple terms, a scope is a set of claims.
Authentication/Token Request
Client applications request tokens from an OIDC provider. Depending on the requested scopes, OIDC provider will return an ID token or an Access Token or both.
Authentication Response
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.
Roles/Stakeholders
Client (Relying Party)
A client is a software application that requests tokens from an IdP Provider (clients are also termed as Relying Party - RP). The tokens are used for authentication or gaining access to resources. A client application must be registered with an OIDC provider. Some examples for client applications are native mobile apps or desktop applications, web applications, Single Page Applications (SPA) etc.
User (Resource Owner)
A user is a person who is using a client application registered with an OIDC provider so as to access his or her resources (data).
Resource server
A server that hosts the protected user resources.
Authorization Server
A server that is responsible to authorize user to access resources. This is the entity that provides access tokens for authorization.
Tokens
Access Token
This token grants access to a resource. Client applications request access tokens and forward them to an API. The token consists of information about the client application and user (if exists). An API will use the information to grant access to the data.
Refresh Token
This token is of type string that is used to obtain new access token when an existing access token expires. Not all the API uses refresh tokens.
Identity Token
This token represents the result of an authentication flow. It consists of an identifier of the user (indicated as sub or subject claim). It also contains additional information about the user.