Konubinix' opinionated web of thoughts

OpenID Connect

Fleeting

It’s an extension on top of OAuth 2.0 that provides a way for the client to get the identity of the resource owner.

It does not say anything about the resource server and let OAuth 2.0 deal with this1.

They precise only two roles: OpenID Connect Provider and Relying Party 2. They don’t even redefine the resource server, while they rename the provider and the relying party3. Actually, in the standard, there are only two references to the resource server and only anecdotally.

Also, they define the end-user as being the human participant4, therefore a more vague definition of the resource owner.

The overview of the flow indeed only shows those actors and only refers to the access token as a side note5.

Here are the scopes are used to get access to some claims about the user.

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. An Authorization Request using these extensions is called an Authentication Request.

https://openid.net/specs/openid-connect-basic-1_0.html

3.1.3.7. ID Token Validation

Clients MUST validate the ID Token in the Token Response in the following manner:

If the ID Token is encrypted, decrypt it using the keys and algorithms that the Client specified during Registration that the

https://openid.net/specs/openid-connect-core-1_0.html

3.2.2.9. Access Token Validation

To validate an Access Token issued from the Authorization Endpoint with an ID Token, the Client SHOULD do the following:

Hash the octets of the ASCII representation of the access_token with the hash algorithm specified in JWA (Jones, M., “JSON Web Algorithms (JWA),” July 2014.) [JWA] for the alg Header Parameter of the ID Token’s JOSE Header. For instance, if the alg is RS256, the hash algorithm used is SHA-256.

Take the left-most half of the hash and base64url encode it.

The value of at_hash in the ID Token MUST match the value produced in the previous step.

https://openid.net/specs/openid-connect-core-1_0.html

Standard Claims

This specification defines a set of standard Claims. They can be requested to be returned either in the UserInfo Response, per Section 5.3.2 (Successful UserInfo Response), or in the ID Token, per Section 2 (ID Token).

https://openid.net/specs/openid-connect-core-1_0.html

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

https://openid.net/specs/openid-connect-core-1_0.html

Claims requested by the profile, email, address, and phone scope values are returned from the UserInfo Endpoint, as described in Section 5.3.2 (Successful UserInfo Response), when a response_type value is used that results in an Access Token being issued. However, when no Access Token is issued (which is the case for the response_type value id_token), the resulting Claims are returned in the ID Token.

https://openid.net/specs/openid-connect-core-1_0.html

Claim Stability and Uniqueness

The sub (subject) and iss (issuer) Claims, used together, are the only Claims that an RP can rely upon as a stable identifier for the End-User, since the sub Claim MUST be locally unique and never reassigned within the Issuer for a particular End-User, as described in Section 2 (ID Token). Therefore, the only guaranteed unique identifier for a given End-User is the combination of the iss Claim and the sub Claim

https://openid.net/specs/openid-connect-core-1_0.html

For instance, an Issuer MAY re-use an email Claim Value across different End-Users at different points in time, and the claimed email address for a given End-User MAY change over time. Therefore, other Claims such as email, phone_number, and preferred_username and MUST NOT be used as unique identifiers for the End-User

https://openid.net/specs/openid-connect-core-1_0.html

The OpenID Connect Core 1.0 specification 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

https://openid.net/specs/openid-connect-core-1_0.html#Introduction

Its formula for success: simple JSON-based identity tokens (JWT), delivered via OAuth 2.0 flows designed for web, browser-based and native / mobile applications.

https://connect2id.com/learn/openid-connect

The ID token resembles the concept of an identity card, in a standard JWT format, signed by the OpenID Provider (OP)

https://connect2id.com/learn/openid-connect

ID tokens are requested via the OAuth 2.0 protocol, which has been a tremendous success on its own

https://connect2id.com/learn/openid-connect

OpenID Connect 1.0 is a simple identity layer on top of the OAuth 2.0 protocol. It allows 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.

https://openid.net/connect/

OpenID Connect utilises the OAuth 2.0 semantics and flows to allow clients (relying parties) to access the user’s identity, encoded in a JSON Web Token (JWT) called ID token

https://connect2id.com/learn/openid-connect

ID Token
JSON Web Token (JWT) that contains Claims about the Authentication event. It MAY contain other Claims.

https://openid.net/specs/openid-connect-basic-1_0.html

OpenID Provider (OP)
OAuth 2.0 Authorization Server that is capable of Authenticating the End-User and providing Claims to a Relying Party about the Authentication event and the End-User

https://openid.net/specs/openid-connect-basic-1_0.html

Relying Party (RP)
OAuth 2.0 Client application requiring End-User Authentication and Claims from an OpenID Provider.

https://openid.net/specs/openid-connect-basic-1_0.html

The Code Flow consists of the following steps:

  • Client prepares an Authentication Request containing the desired request parameters.
  • Client sends the request to the Authorization Server.
  • Authorization Server authenticates the End-User.
  • Authorization Server obtains End-User Consent/Authorization.
  • Authorization Server sends the End-User back to the Client with code.
  • Client sends the code to the Token Endpoint to receive an Access Token and ID Token in the response.
  • Client validates the tokens and retrieves the End-User’s Subject Identifier.

https://openid.net/specs/openid-connect-basic-1_0.html

The Client receives a response with the following parameters as described in Section 4.1.4 of OAuth 2.0 [RFC6749]. The response SHOULD be encoded using UTF-8 [RFC3629].

access_token
REQUIRED. Access Token for the UserInfo Endpoint.
token_type
REQUIRED. OAuth 2.0 Token Type value. The value MUST be Bearer, as specified in OAuth 2.0 Bearer Token Usage [RFC6750], for Clients using this subset. Note that the token_type value is case insensitive.
id_token
REQUIRED. ID Token.
expires_in
OPTIONAL. Expiration time of the Access Token in seconds since the response was generated.
refresh_token
OPTIONAL. Refresh Token.

The Client can then use the Access Token to access protected resources at Resource Servers.

https://openid.net/specs/openid-connect-basic-1_0.html

The Client MUST validate the ID Token in the Token Response

https://openid.net/specs/openid-connect-basic-1_0.html

Use of this extension is requested by Clients by including the openid scope value in the Authorization Request

https://openid.net/specs/openid-connect-core-1_0.html#Introduction

Information about the authentication performed is returned in a JSON Web Token (JWT) [JWT] called an ID Token

https://openid.net/specs/openid-connect-core-1_0.html#Introduction

OAuth 2.0 Authentication Servers implementing OpenID Connect are also referred to as OpenID Providers (OPs).

https://openid.net/specs/openid-connect-core-1_0.html#Introduction

OAuth 2.0 Clients using OpenID Connect are also referred to as Relying Parties (RPs)

https://openid.net/specs/openid-connect-core-1_0.html#Introduction

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

https://openid.net/specs/openid-connect-core-1_0.html#Introduction

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.

https://openid.net/specs/openid-connect-core-1_0.html#Introduction

Client MUST validate the Token Response as follows:

https://openid.net/specs/openid-connect-core-1_0.html#Introduction

Information about the authentication performed is returned in a JSON Web Token (JWT) [JWT] called an ID Token

https://openid.net/specs/openid-connect-basic-1_0.html

Authentication

Process used to achieve sufficient confidence in the binding between the Entity and the presented Identity.

https://openid.net/specs/openid-connect-basic-1_0.html

Identifier

Value that uniquely characterizes an Entity in a specific context.

https://openid.net/specs/openid-connect-basic-1_0.html

OpenID Connect 1.0 is a simple identity layer on top of the OAuth 2.0 [RFC6749] protocol

https://openid.net/specs/openid-connect-core-1_0.html#Introduction

An Authentication Request is an OAuth 2.0 Authorization Request that requests that the End-User be authenticated by the Authorization Server.

https://openid.net/specs/openid-connect-core-1_0.html#Introduction

standard claims

This subset of OpenID Connect defines a set of standard Claims. They are returned in the UserInfo Response.

Member 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 janedoe or j.doe. This value MAY be any valid JSON string including special characters such as @, /, or whitespace. The RP MUST NOT rely upon this value being unique, as discussed in Section 2.5.3.
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. 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.
email string End-User’s preferred e-mail address. Its value MUST conform to the RFC 5322 [RFC5322] addr-spec syntax. The RP MUST NOT rely upon this value being unique, as discussed in Section 2.5.3.
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 document 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 [ISO8601‑2004] YYYY-MM-DD format. The year MAY be 0000, indicating that it is omitted. To represent only the year, YYYY format is allowed. Note that depending on the underlying platform’s date related function, providing just year can result in varying month and day, so the implementers need to take this factor into account to correctly process the dates.
zoneinfo string String from zoneinfo [zoneinfo] time zone database representing the End-User’s time zone. For example, Europe/Paris or America/Los_Angeles.
locale string End-User’s locale, represented as a BCP47 [RFC5646] language tag. This is typically an ISO 639-1 Alpha-2 [ISO639‑1] language code in lowercase and an ISO 3166-1 Alpha-2 [ISO3166‑1] country code in uppercase, separated by a dash. For example, en-US or fr-CA. As a compatibility note, some implementations have used an underscore as the separator rather than a dash, for example, en_US; Relying Parties MAY choose to accept this locale syntax as well.
phone_number string End-User’s preferred telephone number. E.164 [E.164] is RECOMMENDED as the format of this Claim, for example, +1 (425) 555-1212 or +56 (2) 687 2400. If the phone number contains an extension, it is RECOMMENDED that the extension be represented using the RFC 3966 [RFC3966] extension syntax, for example, +1 (604) 555-1234;ext=5678.
phone_number_verified boolean True if the End-User’s phone number has been verified; otherwise false. When this Claim Value is true, this means that the OP took affirmative steps to ensure that this phone number was controlled by the End-User at the time the verification was performed. The means by which a phone number is verified is context specific, and dependent upon the trust framework or contractual agreements within which the parties are operating. When true, the phone_number Claim MUST be in E.164 format and any extensions MUST be represented in RFC 3966 format.
address JSON object End-User’s preferred postal address. The value of the address member is a JSON [RFC4627] structure containing some or all of the members defined in Section 2.5.1.
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-01T00:00:00Z as measured in UTC until the date/time.

https://openid.net/specs/openid-connect-basic-1_0.html#StandardClaims

userinfo endpoint

misconcetions

people always say that it is a protocol to provide authn on top of OAuth 2.0. If that was the case, it would defined stuff like two factors authentication

It is rather a way to deal with identification: getting some information about the identity of the client. As if the authorization server were the resource server of user identity and the id token was the resource (see authentication vs identification vs authorization).

All the domains are so different that it looks impossible to define more precise term that oauth 2.0 scope and resources. But for identity, this is not the case, there can be a consensus and a definition of the schema of the data that makes identity.

OpenID Connect is all about defining this schema and the protocol to get that data.

For instance, in this podcast, the confusion is made.

Identity Token

The JWT that contains data about the authentication event6. Therefore often related to the user itself.

claims

The following Claims are used within the ID Token:

iss
REQUIRED. Issuer Identifier for the Issuer of the response. The iss value is a case-sensitive URL using the https scheme that contains scheme, host, and optionally, port number and path components and no query or fragment components.
sub
REQUIRED. Subject Identifier. Locally unique and never reassigned identifier within the Issuer for the End-User, whichi is intended to be consumed by the Client, e.g., 24400320 or AItOawmwtWwcT0k51BayewNvutrJUqsvl6qs7A4. It MUST NOT exceed 255 ASCII characters in length. The sub value is a case-sensitive string.
aud
REQUIRED. Audience(s) that this ID Token is intended for. It MUST contain the OAuth 2.0 client_id of the Relying Party as an audience value. It MAY also contain identifiers for other audiences. 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. The processing of this parameter requires that the current date/time MUST be before the expiration date/time listed in the value. Implementers MAY provide for some small leeway, usually no more than a few minutes, to account for clock skew. Its value is a JSON [RFC7159] number representing the number of seconds from 1970-01-01T00:00:00Z as measured in UTC until the date/time. See RFC 3339 [RFC3339] for details regarding date/times in general and UTC in particular.
iat
REQUIRED. Time at which the JWT was issued. Its value is a JSON number representing the number of seconds from 1970-01-01T00:00:00Z as measured in UTC until the date/time.
auth_time
Time when the End-User authentication occurred. Its value is a JSON number representing the number of seconds from 1970-01-01T00:00:00Z as measured in UTC until the date/time. When a max_age request is made then this Claim is REQUIRED; otherwise, its inclusion is OPTIONAL.
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. The Client MUST verify that the nonce Claim Value is equal to the value of the nonce parameter sent in the Authentication Request. 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. The nonce value is a case-sensitive string.
at_hash
OPTIONAL. Access Token hash value. This is OPTIONAL when the ID Token is issued from the Token Endpoint, which is the case for this subset of OpenID Connect; nonetheless, an at_hash Claim MAY be present. Its value is the base64url encoding of the left-most half of the hash of the octets of the ASCII representation of the access_token value, where the hash algorithm used is the hash algorithm used in the alg Header Parameter of the ID Token’s JOSE Header. For instance, if the alg is RS256, hash the access_token value with SHA-256, then take the left-most 128 bits and base64url-encode them. The at_hash value is a case-sensitive string.
acr
OPTIONAL. Authentication Context Class Reference. String specifying an Authentication Context Class Reference value that identifies the Authentication Context Class that the authentication performed satisfied. The value “0” indicates the End-User authentication did not meet the requirements of ISO/IEC 29115 [ISO29115] level 1. For historic reasons, the value “0” is used to indicate that there is no confidence that the same person is actually there. Authentications with level 0 SHOULD NOT be used to authorize access to any resource of any monetary value. An absolute URI or an RFC 6711 [RFC6711] registered name SHOULD be used as the acr value; registered names MUST NOT be used with a different meaning than that which is registered. Parties using this claim will need to agree upon the meanings of the values used, which may be context specific. The acr value is a case-sensitive string.
amr
OPTIONAL. Authentication Methods References. JSON array of strings that are identifiers for authentication methods used in the authentication. For instance, values might indicate that both password and OTP authentication methods were used. The definition of particular values to be used in the amr Claim is beyond the scope of this document. Parties using this claim will need to agree upon the meanings of the values used, which may be context specific. The amr value is an array of case-sensitive strings.
azp
OPTIONAL. Authorized party - the party to which the ID Token was issued. If present, it MUST contain the OAuth 2.0 Client ID of this party. This Claim is only needed when the ID Token has a single audience value and that audience is different than the authorized party. It MAY be included even when the authorized party is the same as the sole audience. The azp value is a case-sensitive string containing a StringOrURI value.

ID Tokens MAY contain other Claims. Any Claims used that are not understood MUST be ignored.

https://openid.net/specs/openid-connect-basic-1_0.html

scopes

  • External reference: https://openid.net/specs/openid-connect-basic-1_0.html#StandardClaims OpenID Connect defines the following scope values:

    • openid: REQUIRED. Informs the Authorization Server that the Client is making an OpenID Connect request. If the openid scope value is not present, the behavior is entirely unspecified.
    • 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.
    • offline_access: OPTIONAL. This scope value requests that an OAuth 2.0 Refresh Token be issued that can be used to obtain an Access Token that grants access to the End-User’s UserInfo Endpoint even when the End-User is not present (not logged in).

    https://openid.net/specs/openid-connect-basic-1_0.html

OpenID Connect Provider

A tool that can provide signed ID Token. Basically the authorization server from the point of view of OpenID Connect.

OAuth 2.0 Authentication Servers implementing OpenID Connect are also referred to as OpenID Providers (OPs).

https://openid.net/specs/openid-connect-basic-1_0.html

This specification also defines the following terms:

OpenID Provider (OP)
OAuth 2.0 Authorization Server that is capable of Authenticating the End-User and providing Claims to a Relying Party about the Authentication event and the End-User. […]

https://openid.net/specs/openid-connect-core-1_0.html#Introduction

OpenID Connect 1.0 is a simple identity layer on top of the OAuth 2.0 protocol. It allows 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.

https://openid.net/connect/

OpenID Connect allows clients of all types, including Web-based, mobile, and JavaScript clients, to request and receive information about authenticated sessions and end-users

https://openid.net/connect/

OpenID Connect or OIDC is an identity protocol that utilizes the authorization and authentication mechanisms of OAuth 2.0.

https://auth0.com/intro-to-iam/what-is-openid-connect-oidc/

While OAuth 2.0 is an authorization protocol, OIDC is an identity authentication protocol a

https://auth0.com/intro-to-iam/what-is-openid-connect-oidc/

used to verify the identity of a user to a client service, also called Relying Party

https://auth0.com/intro-to-iam/what-is-openid-connect-oidc/

Notes linking here


  1. As background, the OAuth 2.0 Authorization Framework [RFC6749] and OAuth 2.0 Bearer Token Usage [RFC6750] specifications provide a general framework for third-party applications to obtain and use limited access to HTTP resources. They define mechanisms to obtain and use Access Tokens to access resources but do not define standard methods to provide identity information. Notably, without profiling OAuth 2.0, it is incapable of providing information about the authentication of an End-User. Readers are expected to be familiar with these specifications.

    https://openid.net/specs/openid-connect-core-1_0.html#Introduction

     ↩︎
  2. 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).

    https://openid.net/specs/openid-connect-core-1_0.html#Introduction

     ↩︎
  3. This specification uses the terms […] “Authorization Server”, “Client”, […] “Resource Owner”, “Resource Server”, […] defined by OAuth 2.0 [RFC6749]

    […]

    This specification also defines the following terms:

    End-User
    Human participant. […]
    OpenID Provider (OP)
    OAuth 2.0 Authorization Server that is capable of Authenticating the End-User and providing Claims to a Relying Party about the Authentication event and the End-User. […]
    Relying Party (RP)
    OAuth 2.0 Client application requiring End-User Authentication and Claims from an OpenID Provider.

    https://openid.net/specs/openid-connect-core-1_0.html#Introduction

     ↩︎
  4. End-User
    Human participant

    https://openid.net/specs/openid-connect-core-1_0.html

     ↩︎
  5. The OpenID Connect protocol, in abstract, follows the following steps.
    
    1) The [[id:4ba66897-9805-453c-b0d8-94d567c8f79d][RP]] (Client) sends a request to the OpenID Provider ([[id:8f180b6d-f9a8-4244-a3e8-827fd4098835][OP]]).
    2) The OP authenticates the End-User and obtains authorization.
    3) The OP responds with an [[id:957552a3-2db5-4515-bdbc-b6c373f48afe][ID Token]] and usually an [[id:e8b165d4-cb30-4a18-9d23-990629f09f2d][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.
    
    These steps are illustrated in the following diagram:
    
    +--------+                                   +--------+
    |        |                                   |        |
    |        |---------(1) AuthN Request-------->|        |
    |        |                                   |        |
    |        |  +--------+                       |        |
    |        |  |        |                       |        |
    |        |  |  End-  |<--(2) AuthN & AuthZ-->|        |
    |        |  |  User  |                       |        |
    |   RP   |  |        |                       |   OP   |
    |        |  +--------+                       |        |
    |        |                                   |        |
    |        |<--------(3) AuthN Response--------|        |
    |        |                                   |        |
    |        |---------(4) UserInfo Request----->|        |
    |        |                                   |        |
    |        |<--------(5) UserInfo Response-----|        |
    |        |                                   |        |
    +--------+                                   +--------+
    
    --- https://openid.net/specs/openid-connect-core-1_0.html#Introduction
    
     ↩︎
  6. ID Token JSON Web Token (JWT) [JWT] that contains Claims about the Authentication event. It MAY contain other Claims.

    […]

    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) [JWT].

    https://openid.net/specs/openid-connect-basic-1_0.html

     ↩︎