| TOC |
|
OpenID Connect 1.0 is a simple identity layer on top of the OAuth 2.0 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.
This 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. It also describes the security and privacy considerations for using OpenID Connect.
1.
Introduction
1.1.
Requirements Notation and Conventions
1.2.
Terminology
1.3.
Overview
2.
ID Token
3.
Authentication
3.1.
Authentication using the Authorization Code Flow
3.1.1.
Authorization Code Flow Steps
3.1.2.
Authorization Endpoint
3.1.2.1.
Authentication Request
3.1.2.2.
Authentication Request Validation
3.1.2.3.
Authorization Server Authenticates End-User
3.1.2.4.
Authorization Server Obtains End-User Consent/Authorization
3.1.2.5.
Successful Authentication Response
3.1.2.6.
Authentication Error Response
3.1.2.7.
Authentication Response Validation
3.1.3.
Token Endpoint
3.1.3.1.
Token Request
3.1.3.2.
Token Request Validation
3.1.3.3.
Successful Token Response
3.1.3.4.
Token Error Response
3.1.3.5.
Token Response Validation
3.1.3.6.
ID Token
3.1.3.7.
ID Token Validation
3.1.3.8.
Access Token Validation
3.2.
Authentication using the Implicit Flow
3.2.1.
Implicit Flow Steps
3.2.2.
Authorization Endpoint
3.2.2.1.
Authentication Request
3.2.2.2.
Authentication Request Validation
3.2.2.3.
Authorization Server Authenticates End-User
3.2.2.4.
Authorization Server Obtains End-User Consent/Authorization
3.2.2.5.
Successful Authentication Response
3.2.2.6.
Authentication Error Response
3.2.2.7.
Redirect URI Fragment Handling
3.2.2.8.
Authentication Response Validation
3.2.2.9.
Access Token Validation
3.2.2.10.
ID Token
3.2.2.11.
ID Token Validation
3.3.
Authentication using the Hybrid Flow
3.3.1.
Hybrid Flow Steps
3.3.2.
Authorization Endpoint
3.3.2.1.
Authentication Request
3.3.2.2.
Authentication Request Validation
3.3.2.3.
Authorization Server Authenticates End-User
3.3.2.4.
Authorization Server Obtains End-User Consent/Authorization
3.3.2.5.
Successful Authentication Response
3.3.2.6.
Authentication Error Response
3.3.2.7.
Redirect URI Fragment Handling
3.3.2.8.
Authentication Response Validation
3.3.2.9.
Access Token Validation
3.3.2.10.
Authorization Code Validation
3.3.2.11.
ID Token
3.3.2.12.
ID Token Validation
3.3.3.
Token Endpoint
3.3.3.1.
Token Request
3.3.3.2.
Token Request Validation
3.3.3.3.
Successful Token Response
3.3.3.4.
Token Error Response
3.3.3.5.
Token Response Validation
3.3.3.6.
ID Token
3.3.3.7.
ID Token Validation
3.3.3.8.
Access Token
3.3.3.9.
Access Token Validation
4.
Initiating Login from a Third Party
5.
Claims
5.1.
Standard Claims
5.1.1.
Address Claim
5.1.2.
Additional Claims
5.2.
Claims Languages and Scripts
5.3.
UserInfo Endpoint
5.3.1.
UserInfo Request
5.3.2.
Successful UserInfo Response
5.3.3.
UserInfo Error Response
5.3.4.
UserInfo Response Validation
5.4.
Requesting Claims using Scope Values
5.5.
Requesting Claims using the "claims" Request Parameter
5.5.1.
Individual Claims Requests
5.5.1.1.
Requesting the "acr" Claim
5.5.2.
Languages and Scripts for Individual Claims
5.6.
Claim Types
5.6.1.
Normal Claims
5.6.2.
Aggregated and Distributed Claims
5.6.2.1.
Example of Aggregated Claims
5.6.2.2.
Example of Distributed Claims
5.7.
Claim Stability and Uniqueness
6.
Passing Request Parameters as JWTs
6.1.
Passing a Request Object by Value
6.1.1.
Request using the "request" Request Parameter
6.2.
Passing a Request Object by Reference
6.2.1.
URI Referencing the Request Object
6.2.2.
Request using the "request_uri" Request Parameter
6.2.3.
Authorization Server Fetches Request Object
6.2.4.
"request_uri" Rationale
6.3.
Validating JWT-Based Requests
6.3.1.
Encrypted Request Object
6.3.2.
Signed Request Object
6.3.3.
Request Parameter Assembly and Validation
7.
Self-Issued OpenID Provider
7.1.
Self-Issued OpenID Provider Discovery
7.2.
Self-Issued OpenID Provider Registration
7.2.1.
Providing Information with the "registration" Request Parameter
7.3.
Self-Issued OpenID Provider Request
7.4.
Self-Issued OpenID Provider Response
7.5.
Self-Issued ID Token Validation
8.
Subject Identifier Types
8.1.
Pairwise Identifier Algorithm
9.
Client Authentication
10.
Signatures and Encryption
10.1.
Signing
10.1.1.
Rotation of Asymmetric Signing Keys
10.2.
Encryption
10.2.1.
Rotation of Asymmetric Encryption Keys
11.
Offline Access
12.
Using Refresh Tokens
12.1.
Refresh Request
12.2.
Successful Refresh Response
12.3.
Refresh Error Response
13.
Serializations
13.1.
Query String Serialization
13.2.
Form Serialization
13.3.
JSON Serialization
14.
String Operations
15.
Implementation Considerations
15.1.
Mandatory to Implement Features for All OpenID Providers
15.2.
Mandatory to Implement Features for Dynamic OpenID Providers
15.3.
Discovery and Registration
15.4.
Mandatory to Implement Features for Relying Parties
15.5.
Implementation Notes
15.5.1.
Authorization Code Implementation Notes
15.5.2.
Nonce Implementation Notes
15.5.3.
Redirect URI Fragment Handling Implementation Notes
15.6.
Compatibility Notes
15.7.
Related Specifications and Implementer's Guides
16.
Security Considerations
16.1.
Request Disclosure
16.2.
Server Masquerading
16.3.
Token Manufacture/Modification
16.4.
Access Token Disclosure
16.5.
Server Response Disclosure
16.6.
Server Response Repudiation
16.7.
Request Repudiation
16.8.
Access Token Redirect
16.9.
Token Reuse
16.10.
Eavesdropping or Leaking Authorization Codes (Secondary Authenticator Capture)
16.11.
Token Substitution
16.12.
Timing Attack
16.13.
Other Crypto Related Attacks
16.14.
Signing and Encryption Order
16.15.
Issuer Identifier
16.16.
Implicit Flow Threats
16.17.
TLS Requirements
16.18.
Lifetimes of Access Tokens and Refresh Tokens
16.19.
Symmetric Key Entropy
16.20.
Need for Signed Requests
16.21.
Need for Encrypted Requests
16.22.
HTTP 307 Redirects
16.23.
Custom URI Schemes on iOS
17.
Privacy Considerations
17.1.
Personally Identifiable Information
17.2.
Data Access Monitoring
17.3.
Correlation
17.4.
Offline Access
18.
IANA Considerations
18.1.
JSON Web Token Claims Registration
18.1.1.
Registry Contents
18.2.
OAuth Parameters Registration
18.2.1.
Registry Contents
18.3.
OAuth Extensions Error Registration
18.3.1.
Registry Contents
18.4.
URI Scheme Registration
18.4.1.
Registry Contents
19.
References
19.1.
Normative References
19.2.
Informative References
Appendix A.
Authorization Examples
A.1.
Example using response_type=code
A.2.
Example using response_type=id_token
A.3.
Example using response_type=id_token token
A.4.
Example using response_type=code id_token
A.5.
Example using response_type=code token
A.6.
Example using response_type=code id_token token
A.7.
RSA Key Used in Examples
Appendix B.
Acknowledgements
Appendix C.
Notices
§
Authors' Addresses
| TOC |
OpenID Connect 1.0 is a simple identity layer on top of the OAuth 2.0 [RFC6749] (Hardt, D., Ed., “The OAuth 2.0 Authorization Framework,” October 2012.) 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.
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. It also describes the security and privacy considerations for using OpenID Connect.
As background, the OAuth 2.0 Authorization Framework (Hardt, D., Ed., “The OAuth 2.0 Authorization Framework,” October 2012.) [RFC6749] and OAuth 2.0 Bearer Token Usage (Jones, M. and D. Hardt, “The OAuth 2.0 Authorization Framework: Bearer Token Usage,” October 2012.) [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.
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) (Jones, M., Bradley, J., and N. Sakimura, “JSON Web Token (JWT),” May 2015.) [JWT] called an ID Token (see Section 2 (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).
This specification assumes that the Relying Party has already obtained configuration information about the OpenID Provider, including its Authorization Endpoint and Token Endpoint locations. This information is normally obtained via Discovery, as described in OpenID Connect Discovery 1.0 (Sakimura, N., Bradley, J., Jones, M., and E. Jay, “OpenID Connect Discovery 1.0,” December 2023.) [OpenID.Discovery], or may be obtained via other mechanisms.
Likewise, this specification assumes that the Relying Party has already obtained sufficient credentials and provided information needed to use the OpenID Provider. This is normally done via Dynamic Registration, as described in OpenID Connect Dynamic Client Registration 1.0 (Sakimura, N., Bradley, J., and M. Jones, “OpenID Connect Dynamic Client Registration 1.0,” December 2023.) [OpenID.Registration], or may be obtained via other mechanisms.
The previous versions of this specification are:
| TOC |
The key words "MUST", "MUST NOT", "REQUIRED", "SHALL", "SHALL NOT", "SHOULD", "SHOULD NOT", "RECOMMENDED", "NOT RECOMMENDED", "MAY", and "OPTIONAL" in this document are to be interpreted as described in RFC 2119 (Bradner, S., “Key words for use in RFCs to Indicate Requirement Levels,” March 1997.) [RFC2119].
In the .txt version of this specification, values are quoted to indicate that they are to be taken literally. When using these values in protocol messages, the quotes MUST NOT be used as part of the value. In the HTML version of this specification, values to be taken literally are indicated by the use of this fixed-width font.
All uses of JSON Web Signature (JWS) (Jones, M., Bradley, J., and N. Sakimura, “JSON Web Signature (JWS),” May 2015.) [JWS] and JSON Web Encryption (JWE) (Jones, M. and J. Hildebrand, “JSON Web Encryption (JWE),” May 2015.) [JWE] data structures in this specification utilize the JWS Compact Serialization or the JWE Compact Serialization; the JWS JSON Serialization and the JWE JSON Serialization are not used.
| TOC |
This specification uses the terms "Access Token", "Authorization Code", "Authorization Endpoint", "Authorization Grant", "Authorization Server", "Client", "Client Authentication", "Client Identifier", "Client Secret", "Grant Type", "Protected Resource", "Redirection URI", "Refresh Token", "Resource Server", "Response Type", and "Token Endpoint" defined by OAuth 2.0 (Hardt, D., Ed., “The OAuth 2.0 Authorization Framework,” October 2012.) [RFC6749], the terms "Claim Name", "Claim Value", "JSON Web Token (JWT)", "JWT Claims Set", and "Nested JWT" defined by JSON Web Token (JWT) (Jones, M., Bradley, J., and N. Sakimura, “JSON Web Token (JWT),” May 2015.) [JWT], the terms "Base64url Encoding", "Header Parameter", and "JOSE Header" defined by JSON Web Signature (JWS) (Jones, M., Bradley, J., and N. Sakimura, “JSON Web Signature (JWS),” May 2015.) [JWS], the term "User Agent" defined by RFC 7230 (Fielding, R., Ed. and J. Reschke, Ed., “Hypertext Transfer Protocol (HTTP/1.1): Message Syntax and Routing,” June 2014.) [RFC7230], and the term "Response Mode" defined by OAuth 2.0 Multiple Response Type Encoding Practices (de Medeiros, B., Ed., Scurtescu, M., Tarjan, P., and M. Jones, “OAuth 2.0 Multiple Response Type Encoding Practices,” February 2014.) [OAuth.Responses].
This specification also defines the following terms:
- Authentication
- Process used to achieve sufficient confidence in the binding between the Entity and the presented Identity.
- Authentication Request
- OAuth 2.0 Authorization Request using extension parameters and scopes defined by OpenID Connect to request that the End-User be authenticated by the Authorization Server, which is an OpenID Connect Provider, to the Client, which is an OpenID Connect Relying Party.
- Authentication Context
- Information that the Relying Party can require before it makes an entitlement decision with respect to an authentication response. Such context can include, but is not limited to, the actual authentication method used or level of assurance such as ISO/IEC 29115 (International Organization for Standardization, “ISO/IEC 29115:2013. Information technology - Security techniques - Entity authentication assurance framework,” April 2013.) [ISO29115] entity authentication assurance level.
- Authentication Context Class
- Set of authentication methods or procedures that are considered to be equivalent to each other in a particular context.
- Authentication Context Class Reference
- Identifier for an Authentication Context Class.
- Authorization Code Flow
- OAuth 2.0 flow in which an Authorization Code is returned from the Authorization Endpoint and all tokens are returned from the Token Endpoint.
- Authorization Request
- OAuth 2.0 Authorization Request as defined by [RFC6749] (Hardt, D., Ed., “The OAuth 2.0 Authorization Framework,” October 2012.).
- Claim
- Piece of information asserted about an Entity.
- Claim Type
- Syntax used for representing a Claim Value. This specification defines Normal, Aggregated, and Distributed Claim Types.
- Claims Provider
- Server that can return Claims about an Entity.
- Credential
- Data presented as evidence of the right to use an identity or other resources.
- End-User
- Human participant.
- Entity
- Something that has a separate and distinct existence and that can be identified in a context. An End-User is one example of an Entity.
- Essential Claim
- Claim specified by the Client as being necessary to ensure a smooth authorization experience for the specific task requested by the End-User.
- Hybrid Flow
- OAuth 2.0 flow in which an Authorization Code is returned from the Authorization Endpoint, some tokens are returned from the Authorization Endpoint, and others are returned from the Token Endpoint.
- ID Token
- JSON Web Token (JWT) (Jones, M., Bradley, J., and N. Sakimura, “JSON Web Token (JWT),” May 2015.) [JWT] that contains Claims about the Authentication event. It MAY contain other Claims.
- Identifier
- Value that uniquely characterizes an Entity in a specific context.
- Identity
- Set of attributes related to an Entity.
- Implicit Flow
- OAuth 2.0 flow in which all tokens are returned from the Authorization Endpoint and neither the Token Endpoint nor an Authorization Code are used.
- Issuer
- Entity that issues a set of Claims.
- Issuer Identifier
- Verifiable Identifier for an Issuer. An Issuer Identifier 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.
- Message
- Request or a response between an OpenID Relying Party and an OpenID Provider.
- 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.
- Request Object
- JWT that contains a set of request parameters as its Claims.
- Request URI
- URL that references a resource containing a Request Object. The Request URI contents MUST be retrievable by the Authorization Server.
- Pairwise Pseudonymous Identifier (PPID)
- Identifier that identifies the Entity to a Relying Party that cannot be correlated with the Entity's PPID at another Relying Party.
- Personally Identifiable Information (PII)
- Information that (a) can be used to identify the natural person to whom such information relates, or (b) is or might be directly or indirectly linked to a natural person to whom such information relates.
- Relying Party (RP)
- OAuth 2.0 Client application requiring End-User Authentication and Claims from an OpenID Provider.
- Sector Identifier
- Host component of a URL used by the Relying Party's organization that is an input to the computation of pairwise Subject Identifiers for that Relying Party.
- Self-Issued OpenID Provider
- Personal, self-hosted OpenID Provider that issues self-signed ID Tokens.
- Subject Identifier
- Locally unique and never reassigned identifier within the Issuer for the End-User, which is intended to be consumed by the Client.
- UserInfo Endpoint
- Protected Resource that, when presented with an Access Token by the Client, returns authorized information about the End-User represented by the corresponding Authorization Grant. The UserInfo Endpoint URL MUST use the https scheme and MAY contain port, path, and query parameter components.
- Validation
- Process intended to establish the soundness or correctness of a construct.
- Verification
- Process intended to test or prove the truth or accuracy of a fact or value.
- Voluntary Claim
- Claim specified by the Client as being useful but not Essential for the specific task requested by the End-User.
IMPORTANT NOTE TO READERS: The terminology definitions in this section are a normative portion of this specification, imposing requirements upon implementations. All the capitalized words in the text of this specification, such as "Issuer Identifier", reference these defined terms. Whenever the reader encounters them, their definitions found in this section must be followed.
For more background on some of the terminology used, see Internet Security Glossary, Version 2 (Shirey, R., “Internet Security Glossary, Version 2,” August 2007.) [RFC4949], ISO/IEC 29115 Entity Authentication Assurance (International Organization for Standardization, “ISO/IEC 29115:2013. Information technology - Security techniques - Entity authentication assurance framework,” April 2013.) [ISO29115], and ITU-T X.1252 (International Telecommunication Union, “ITU-T Recommendation X.1252 - Cyberspace security - Identity management - Baseline identity management terms and definitions,” April 2010.) [X.1252].
| TOC |
The OpenID Connect protocol, in abstract, follows the following steps.
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-----| | | | | | +--------+ +--------+
| TOC |
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 is represented as a JSON Web Token (JWT) (Jones, M., Bradley, J., and N. Sakimura, “JSON Web Token (JWT),” May 2015.) [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. 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. A locally unique and never reassigned identifier within the Issuer for the End-User, which is intended to be consumed by the Client, e.g., 24400320 or AItOawmwtWwcT0k51BayewNvutrJUqsvl6qs7A4. It MUST NOT exceed 255 ASCII [RFC20] (Cerf, V., “ASCII format for Network Interchange,” October 1969.) 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 by the RP when performing authentication with the OP. 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 [RFC8259] (Bray, T., Ed., “The JavaScript Object Notation (JSON) Data Interchange Format,” December 2017.) number representing the number of seconds from 1970-01-01T00:00:00Z as measured in UTC until the date/time. See RFC 3339 (Klyne, G. and C. Newman, “Date and Time on the Internet: Timestamps,” July 2002.) [RFC3339] for details regarding date/times in general and UTC in particular. NOTE: The ID Token expiration time is unrelated the lifetime of the authenticated session between the RP and the OP.
- 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 or when auth_time is requested as an Essential Claim, then this Claim is REQUIRED; otherwise, its inclusion is OPTIONAL. (The auth_time Claim semantically corresponds to the OpenID 2.0 PAPE (Recordon, D., Jones, M., Bufu, J., Ed., Daugherty, J., Ed., and N. Sakimura, “OpenID Provider Authentication Policy Extension 1.0,” December 2008.) [OpenID.PAPE] auth_time response parameter.)
- nonce
- 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. If present in the ID Token, Clients 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. Authorization Servers SHOULD perform no other processing on nonce values used. The nonce 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 (International Organization for Standardization, “ISO/IEC 29115:2013. Information technology - Security techniques - Entity authentication assurance framework,” April 2013.) [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. (This corresponds to the OpenID 2.0 PAPE (Recordon, D., Jones, M., Bufu, J., Ed., Daugherty, J., Ed., and N. Sakimura, “OpenID Provider Authentication Policy Extension 1.0,” December 2008.) [OpenID.PAPE] nist_auth_level 0.) An absolute URI or an RFC 6711 (Johansson, L., “An IANA Registry for Level of Assurance (LoA) Profiles,” August 2012.) [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 amr value is an array of case-sensitive strings. Values used in the amr Claim SHOULD be from those registered in the IANA Authentication Method Reference Values registry [IANA.AMR] (IANA, “Authentication Method Reference Values,” .) established by [RFC8176] (Jones, M., Hunt, P., and A. Nadalin, “Authentication Method Reference Values,” June 2017.); parties using this claim will need to agree upon the meanings of any unregistered values used, which may be context specific.
- 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. The azp value is a case-sensitive string containing a StringOrURI value. Note that in practice, the azp Claim only occurs when extensions beyond the scope of this specification are used; therefore, implementations not using such extensions are encouraged to not use azp and to ignore it when it does occur.
ID Tokens MAY contain other Claims. Any Claims used that are not understood MUST be ignored. See Sections 3.1.3.6 (ID Token), 3.3.2.11 (ID Token), 5.1 (Standard Claims), and 7.4 (Self-Issued OpenID Provider Response) for additional Claims defined by this specification.
ID Tokens MUST be signed using JWS (Jones, M., Bradley, J., and N. Sakimura, “JSON Web Signature (JWS),” May 2015.) [JWS] and optionally both signed and then encrypted using JWS (Jones, M., Bradley, J., and N. Sakimura, “JSON Web Signature (JWS),” May 2015.) [JWS] and JWE (Jones, M. and J. Hildebrand, “JSON Web Encryption (JWE),” May 2015.) [JWE] respectively, thereby providing authentication, integrity, non-repudiation, and optionally, confidentiality, per Section 16.14 (Signing and Encryption Order). If the ID Token is encrypted, it MUST be signed then encrypted, with the result being a Nested JWT, as defined in [JWT] (Jones, M., Bradley, J., and N. Sakimura, “JSON Web Token (JWT),” May 2015.). ID Tokens MUST NOT use none as the alg value unless the Response Type used returns no ID Token from the Authorization Endpoint (such as when using the Authorization Code Flow) and the Client explicitly requested the use of none at Registration time.
ID Tokens SHOULD NOT use the JWS or JWE x5u, x5c, jku, or jwk Header Parameter fields. Instead, references to keys used are communicated in advance using Discovery and Registration parameters, per Section 10 (Signatures and Encryption).
The following is a non-normative example of the set of Claims (the JWT Claims Set) in an ID Token:
{
"iss": "https://server.example.com",
"sub": "24400320",
"aud": "s6BhdRkqt3",
"nonce": "n-0S6_WzA2Mj",
"exp": 1311281970,
"iat": 1311280970,
"auth_time": 1311280969,
"acr": "urn:mace:incommon:iap:silver"
}
| TOC |
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. For this reason, the Client is called Relying Party (RP) in this case.
The Authentication result is returned in an ID Token, as defined in Section 2 (ID Token). It has Claims expressing such information as the Issuer, the Subject Identifier, when the authentication was performed, etc.
Authentication can follow one of three paths: the Authorization Code Flow (response_type=code), the Implicit Flow (response_type=id_token token or response_type=id_token), or the Hybrid Flow (using other Response Type values defined in OAuth 2.0 Multiple Response Type Encoding Practices (de Medeiros, B., Ed., Scurtescu, M., Tarjan, P., and M. Jones, “OAuth 2.0 Multiple Response Type Encoding Practices,” February 2014.) [OAuth.Responses]). The flows determine how the ID Token and Access Token are returned to the Client.
The characteristics of the three flows are summarized in the following non-normative table. The table is intended to provide some guidance on which flow to choose in particular contexts.
| Property | Authorization Code Flow | Implicit Flow | Hybrid Flow |
|---|---|---|---|
| All tokens returned from Authorization Endpoint | no | yes | no |
| All tokens 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 |
| OpenID Connect Authentication Flows |
The flow used is determined by the response_type value contained in the Authorization Request. These response_type values select these 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 |
| OpenID Connect "response_type" Values |
All but the code Response Type value, which is defined by OAuth 2.0 (Hardt, D., Ed., “The OAuth 2.0 Authorization Framework,” October 2012.) [RFC6749], are defined in the OAuth 2.0 Multiple Response Type Encoding Practices (de Medeiros, B., Ed., Scurtescu, M., Tarjan, P., and M. Jones, “OAuth 2.0 Multiple Response Type Encoding Practices,” February 2014.) [OAuth.Responses] specification. 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.
| TOC |
This section describes how to perform authentication using the Authorization Code Flow. When using the Authorization Code Flow, all tokens are returned from the Token Endpoint.
The Authorization Code Flow returns an Authorization Code to the Client, which can then exchange it for an ID Token and an Access Token directly. This provides the benefit of not exposing any tokens to the User Agent and possibly other malicious applications with access to the User Agent. The Authorization Server can also authenticate the Client before exchanging the Authorization Code for an Access Token. The Authorization Code flow is suitable for Clients that can securely maintain a Client Secret between themselves and the Authorization Server.
| TOC |
The Authorization Code Flow goes through the following steps.
| TOC |
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.
Communication with the Authorization Endpoint MUST utilize TLS. See Section 16.17 (TLS Requirements) for more information on using TLS.
| TOC |
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 7231 (Fielding, R., Ed. and J. Reschke, Ed., “Hypertext Transfer Protocol (HTTP/1.1): Semantics and Content,” June 2014.) [RFC7231] 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 (Query String Serialization). If using the HTTP POST method, the request parameters are serialized using Form Serialization, per Section 13.2 (Form Serialization).
OpenID Connect uses the following OAuth 2.0 request parameters with the Authorization Code Flow:
- scope
- REQUIRED. OpenID Connect requests MUST contain the openid scope value. If the