OpenID Connect 1.0

OpenID Connect 1.0 is a simple identity layer on top of the OAuth 2.0 protocol.

It allows client applications to verify the identity of the end-user based on the authentication performed by an OAuth 2.0 authorization server, as well as to obtain basic profile information about the end-user in an interoperable and REST manner.

OpenID Connect allows client applications of all types (including Web-based, mobile and JavaScript), to request and receive information about authenticated sessions and end-users.

OpenID Connect specification

The OpenID Connect 1.0 specification consists of the following documents:

• Core: defines the core OpenID Connect functionality: authentication built on top of OAuth 2.0 and the use of claims to communicate information about the end-user.
• Discovery – Optional: defines how client applications dynamically discover information about OpenID providers.
• Dynamic Registration – Optional: defines how clients dynamically register with OpenID providers
• OAuth 2.0 Multiple Response Types: defines several specific new OAuth 2.0 response types.
• OAuth 2.0 Form Post Response Mode – Optional: defines how to return OAuth 2.0 authorization response parameters (including OpenID Connect Authentication Response parameters) using HTML form values that are auto-submitted by the user agent using HTTP POST method.
• Session Management – Optional: defines how to manage OpenID Connect sessions, including postMessage-based logout functionality.
• HTTP-Based Logout – Optional: defines an HTTP-based logout mechanism that does not use an OP iframe on RP pages.
• Back-Channel Logout – Optional: defines a logout mechanism that uses back-channel communication between the OP and RPs being logged out.

See [OIDC] for more information.

OpenID Connect flow

OpenID Connect reuses the OAuth 2.0 protocol and parameters, and extends on OAuth 2.0 to introduce an Identity layer through the following additions:

• Along with access token, an ID token is returned, which is a JSON Web Token [JWT] with identity claims.
• A UserInfo endpoint is introduced, which returns basic profile attributes against the access token.

The above diagram illustrates an abstract flow based on the authorisation Code grant type.

Here is a description of the flows:
1. The end-user is using the service from the Service Provider (SP) and the use case needs to authenticate the end-user (for instance, Form Filling to sign-up).
2. The SP prepares the Authorisation request and sends it to the Authorisation end-point at the Identity Provider (IDP), passing the required LoA in the Request Object.
3. The IDP selects the appropriate authenticator for the Level of Assurance (LoA) and authenticates the end-user.
4. The IDP returns the response – depending on the grant-type used, e.g. for Authorisation Code grant-type, the Authorisation code is returned. The SP can then retrieve the access token, the refresh token along with the ID Token (with the anonymized user identifier) depending on the requested scopes.
5. If needed, the SP can call the UserInfo end-point at the IDP to get the basic attributes, passing the access token.

ID Token

The primary extension that OpenID Connect makes to OAuth 2.0 to enable end-users to be authenticated is the ID Token data structure. 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 can be used to implement ID federation and Single Sign-On features.

NOTE: The ID Token is represented as a JSON Web Token (JWT). See [JWT] for further details.

The following claims are used within the id_token for all OAuth 2.0 flows used by OpenID Connect:

Claim	Required	Description	Samples
iss	Yes	The issuer identifier.	https://openid.orange.fr/oidc” target=”_blank”
sub	Yes	The subject identifier. A locally unique and never reassigned identifier within the issuer for the end-user, which is intended to be consumed by the client application. It MUST NOT exceed 255 ASCII characters in length. The sub value is a case sensitive string.	AWYEBR-200-iWDbrWzOkP5IJm… 7e/QKnauteaONcU=
aud	Yes	The intended audience for the ID Token. It is an array of case-sensitive strings. It MUST contain the client_id of your client application.	KSAAgXm3Jf…e56zNqaD1Pl5
exp	Yes	The expiration time after which the ID Token MUST NOT be accepted for processing. It’s represented as the number of seconds from 1970-01-01T0:0:0Z as measured in UTC until the date/time specified.	1445349320
iat	Yes	The time of issue of the ID Token. It’s represented as the number of seconds from 1970-01-01T0:0:0Z as measured in UTC until the date/time specified.	1445345720
auth_time		Time when the end-user authentication occurred. 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.	1445345455
acr	No	Authentication Context Class Reference. The value “0” indicates the end-user authentication did not meet the requirements of ISO/IEC 29115). Authentications with level 0 SHOULD NOT be used to authorize access to any resource of any monetary value.	For instance, acr=0 is appropriate for authentication using a long-lived browser cookie.
amr	No	Authentication Methods References. JSON array of strings that are identifiers for authentication methods used in the authentication.	Possible values are: OK, SIM_PIN, OTP (to be confirmed).

ID Token generation (JWT format)

The id_token is obtained when requesting OAuth 2.0 token in exchange of authorization code, on condition that the openid scope was requested and is allowed. See 3-legged OAuth Technical Guide for further details.

As an example:

curl -X POST \
-H "Authorization: Basic NktSSHljksd...ndb6UdnlrT2lOaA==" \
-d "grant_type=authorization_code \
&code=OFR-251HymujFP8f7H...kjj88pjFP8716a727f \
&redirect_uri=http%3F%2F%2Fwww.myserver.com" \
https://api.orange.com/oauth/v2/token 

Response (200 OK):

HTTP/1.1 200 OK
Content-Type: application/json
{
  "token_type": "Bearer",
  "access_token": "OFR-84228a532da9ab133f97f8ac1...c5eecb0dce51cc1dab95d12c",
  "expires_in": 3600,
  "refresh_token": "OFR-47bdf45f66b6b055971a04e3...5dea4b22a800c0844855f2c5defac6",
  "id_token": "eyJ0eXAiOiJKVbGciOiJIUzI1NiJ9.eyJpc3MiOiJodHRzNDU0NTUsImFjciI6MH0.zJFKrzdNaFUNz3njw8HfY"
}

ID Token validation

The client application must validate the obtained id_token as defined in the OpenID Connect specification.

To do this, the client can split the id_token at the period (“.”) characters, take the second segment, and base64url decode it to obtain a JSON object containing the requested claims.

As an example:

base64_decode(eyJpc3MiOiJodHRwczovL29w...UzNDU0NTUsImFjciI6MH0)

{
  "iss":"https://openid.orange.fr/oidc",
  "sub":"AWYEBR-200-iWDbrWzOkP5IJm...7e/QKnauteaONcU=",
  "aud":"KSAAgXm3Jf...e56zNqaD1Pl5",
  "exp":1445349320,
  "iat":1445345720,
  "auth_time":1445345455,
  "acr":0
}

NOTE: The sub claim contains the User ID of the authenticated Orange end-user. This User ID is persistent for your service.

Claims

A client application can obtain claims about end-user and the authentication event.

OpenID Connect defines a standard set of basic profile claims. Pre-defined sets of claims can be requested using specific scope values or individual claims can be requested using the claims request parameter.

Standard claims

The OpenID Connect 1.0 specification defines a set of standard claims. They can be requested to be returned either in the UserInfo response or in the ID Token.

Claim	Type	Description
sub	string	Subject – Issuer identifier for the end-user.
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 janedoe or j.doe.
profile	string	URL of the end-user’s profile page. The contents of this Web page SHOULD be about the End-User.
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.
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.
email	string	End-user’s preferred e-mail address. Its value MUST conform to the RFC 5322 addr-spec syntax.
email_verified	boolean	True if the end-user’s e-mail address has been verified; otherwise false.
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 as an ISO 8601:2004 YYYY-MM-DD format. The year MAY be 0000, indicating that it is omitted. To represent only the year, YYYY format is allowed.
zoneinfo	string	String from zoneinfo time zone database representing the end-user’s time zone. For example, Europe/Paris.
locale	string	End-user’s locale, represented as a BCP47 [RFC5646] language tag. This is typically an ISO 639-1 Alpha-2 language code in lowercase and an ISO 3166-1 Alpha-2 country code in uppercase, separated by a dash. For instance: fr_FR or en_GB.
phone_number	string	End-user’s preferred telephone number (E.164).
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. See Address structure below.
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.

The Address JSON object represents a physical mailing address. It is bound of the following attributes:

Attribute	Type	Description
formatted	string	Full mailing address, formatted for display. MAY contain multiple lines, separated by newline characters.
street_address	string	MAY contain house number, street name, PO Box number. If using multiple lines, the lines are separated by newline characters.
locality	string	City, Town.
region	string	State, Province, County.
postal_code	string	Post Code, ZIP code.
country	string	Country name.

Requesting claims using Scope values

Client applications use scope values 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.

Scopes can be used to request that specific sets of information be made available as claim values. OpenID Connect defines the following scope values that are used to request Claims:

• profile (optional): this scope value is used to 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.

Multiple scope values may be used by creating a space delimited, case sensitive list of ASCII scope values.

The claims requested by the profile, email, address and phone scope values are returned from the UserInfo endpoint (see Standard claims for further details). Please note that the end-user will be given the option to have our Orange Authorization Server decline to provide some or all information requested by your client applications.

As as example (scope=openid profile):

curl -X GET \
-H "Authorization: Bearer OFR-84228a532da9ab133f97f8ac1...c5eecb0dce51cc1dab95d12c" \
https://api.orange.com/openidconnect/v1/userinfo 

Response (200 OK):

HTTP/1.1 200 OK
Content-Type: application/json
{
  "sub": "AWYEBR-200-b9uYD1k6...7l7k1ep/9wKKRhSw="
  "name": "Antoine MAINARD",
}

The sub claim contains a unique and persistent user identifier, specific to your client application. The name field contains the declarative complete name (first + last name) of the end-user.

NOTE: Additional claims such as address, phone, email can be made available, while subjected to Orange authorization.

References

• [OIDC] “Welcome to OpenID Connect”
• [OIDC_CORE] N. Sakimura, J. Bradley, M. Jones, B. de Medeiros and C. Mortimore, “OpenID Connect Core 1.0”, November 2014
• [MOBILE CONNECT], GSMA Association, “CPAS 5 OpenID Connect – Mobile Connect Profile Version 1.1, 2014
• [OAUTH] D. Hardt, “The OAuth 2.0 Authorization Framework” RFC 6749, October 2012.
• [JWT] M. Jones, J. Bradley and N. Sakimura, “JSON Web Token (JWT)” RFC 7519, May 2015
• [JSON] “Introducing JSON”