| 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 OpenID Connect Implicit Client Implementer's Guide 1.0 contains a subset of the OpenID Connect Core 1.0 specification that is designed to be easy to read and implement for basic Web-based Relying Parties using the OAuth 2.0 Implicit Flow. This specification intentionally duplicates content from the Core specification to provide a self-contained implementer's guide for basic Web-based Relying Parties using the OAuth Implicit Flow.
OpenID Providers and non-Web-based applications should instead consult the Core specification.
1.
Introduction
1.1.
Requirements Notation and Conventions
1.2.
Terminology
1.3.
Overview
2.
Protocol Elements
2.1.
Implicit Flow
2.1.1.
Client Prepares Authentication Request
2.1.1.1.
Request Parameters
2.1.2.
Client Sends Request to Authorization Server
2.1.3.
Authorization Server Authenticates End-User
2.1.4.
Authorization Server Obtains End-User Consent/Authorization
2.1.5.
Authorization Server Sends End-User Back to Client
2.1.5.1.
End-User Grants Authorization
2.1.5.2.
End-User Denies Authorization or Invalid Request
2.1.5.3.
Redirect URI Fragment Handling
2.2.
ID Token
2.2.1.
ID Token Validation
2.2.2.
Access Token Validation
2.3.
UserInfo Endpoint
2.3.1.
UserInfo Request
2.3.2.
Successful UserInfo Response
2.3.3.
UserInfo Error Response
2.4.
Scope Values
2.5.
Standard Claims
2.5.1.
Address Claim
2.5.2.
Claims Languages and Scripts
2.5.3.
Claim Stability and Uniqueness
3.
Self-Issued OpenID Provider
3.1.
Self-Issued OpenID Provider Discovery
3.2.
Self-Issued OpenID Provider Registration
3.2.1.
Providing Information with the "registration" Request Parameter
3.3.
Self-Issued OpenID Provider Request
3.4.
Self-Issued OpenID Provider Response
3.5.
Self-Issued ID Token Validation
4.
Serializations
4.1.
Query String Serialization
4.2.
Form Serialization
5.
String Operations
6.
Implementation Considerations
6.1.
Discovery and Registration
7.
Security Considerations
7.1.
TLS Requirements
8.
Privacy Considerations
8.1.
Personally Identifiable Information
8.2.
Data Access Monitoring
8.3.
Correlation
9.
IANA Considerations
10.
References
10.1.
Normative References
10.2.
Informative References
Appendix A.
Acknowledgements
Appendix B.
Notices
Appendix C.
Document History
§
Authors' Addresses
| TOC |
This OpenID Connect Implicit Client Implementer's Guide 1.0 contains a subset of the OpenID Connect Core 1.0 (Sakimura, N., Bradley, J., Jones, M., de Medeiros, B., and C. Mortimore, “OpenID Connect Core 1.0,” December 2023.) [OpenID.Core] specification that is designed to be easy to read and implement for basic Web-based Relying Parties using the OAuth [RFC6749] (Hardt, D., Ed., “The OAuth 2.0 Authorization Framework,” October 2012.) Implicit Flow. This specification intentionally duplicates content from the Core specification to provide a self-contained implementer's guide for basic Web-based Relying Parties using the OAuth Implicit Flow. Should there be any conflicts between the contents of this implementer's guide and the OpenID Connect Core specification, the latter takes precedence.
See the OpenID Connect Basic Client Implementer's Guide 1.0 (Sakimura, N., Bradley, J., Jones, M., de Medeiros, B., and C. Mortimore, “OpenID Connect Basic Client Implementer's Guide 1.0,” December 2023.) [OpenID.Basic] for a related guide for basic Web-based Relying Parties using the OAuth authorization_code grant type. OpenID Providers and non-Web-based applications should instead consult the Core specification. This guide omits implementation and security considerations for OpenID Providers and non-Web-based applications.
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. An Authorization Request using these extensions is called an Authentication 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.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 location. 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.
| 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 [RFC2119] (Bradner, S., “Key words for use in RFCs to Indicate Requirement Levels,” March 1997.).
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] data structures in this specification utilize the JWS Compact Serialization; the JWS JSON Serialization is not used.
When the RFC 2119 language applies to the behavior of OpenID Providers, it is in this specification for explanatory value to help Client implementers understand the expected behavior of OpenID Providers.
| TOC |
This specification uses the terms "Access Token", "Authorization Code", "Authorization Endpoint", "Authorization Grant", "Authorization Server", "Client", "Client Identifier", "Client Secret", "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)", and "JWT Claims Set" defined by JSON Web Token (JWT) (Jones, M., Bradley, J., and N. Sakimura, “JSON Web Token (JWT),” May 2015.) [JWT], the terms "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], and 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].
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.
- Claim
- Piece of information asserted about an Entity.
- Claims Provider
- Server that can return Claims about an Entity.
- 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.
- 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.
- 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.
- 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.
- 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.
- 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.
- 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.
| 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 |
Authentication Requests can follow one of three paths: the Authorization Code Flow, the Implicit Flow, or the Hybrid Flow. The Authorization Code Flow is intended for Clients that can securely maintain a Client Secret between themselves and the Authorization Server, whereas the Implicit Flow is intended for Clients that cannot. However, the Authorization Code flow is sometimes also used by Native applications and other Clients in order to be able to obtain a Refresh Token, even when they cannot ensure the secrecy of the Client Secret value. The Hybrid Flow combines aspects of the Authorization Code Flow and the Implicit Flow. It enables Clients to obtain an ID Token optionally an Access Token with only one round trip to the Authorization Server, possibly minimizing latency, while still enabling Clients to later get tokens from the Token Endpoint -- especially a Refresh Token.
This specification only provides information that is sufficient for basic Clients using the Implicit Flow.
| TOC |
The Implicit Flow consists of the following steps:
| TOC |
When the RP wishes to Authenticate the End-User or determine whether the End-User is already Authenticated, the Client prepares an Authentication Request to be sent to the Authorization Endpoint.
Communication with the Authorization Endpoint MUST utilize TLS. See Section 7.1 (TLS Requirements) for more information on using TLS.
Clients MAY construct the request using the HTTP GET or the HTTP POST method as defined in RFC 7231 (Fielding, R., Ed. and J. Reschke, Ed., “Hypertext Transfer Protocol (HTTP/1.1): Semantics and Content,” June 2014.) [RFC7231].
If using the HTTP GET method, the parameters are serialized using the Query String Serialization, per Section 4.1 (Query String Serialization). If using the HTTP POST method, the request parameters are added to the HTTP request entity-body using the application/x-www-form-urlencoded format as defined by [W3C.SPSD‑html401‑20180327] (, “HTML 4.01 Specification,” March 2018.).
The following is a non-normative example of an Authentication Request URL (with line wraps within values for display purposes only):
https://server.example.com/authorize?
response_type=id_token%20token
&client_id=s6BhdRkqt3
&redirect_uri=https%3A%2F%2Fclient.example.org%2Fcb
&scope=openid%20profile
&state=af0ifjsldkj
&nonce=n-0S6_WzA2Mj
| TOC |
This subset of OpenID Connect uses the following OAuth 2.0 request parameters:
- response_type
- REQUIRED. This value consists of id_token and token, as a space-delimited list. This requests that both an Access Token and an ID Token be returned from the Authorization Endpoint, as specified 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].
- client_id
- REQUIRED. OAuth 2.0 Client Identifier valid at the Authorization Server.
- scope
- REQUIRED. OpenID Connect requests MUST contain the openid scope value. OPTIONAL scope values of profile, email, address, phone, and offline_access are also defined. See Section 2.4 (Scope Values) for more about the scope values defined by this specification.
- 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 as described in Section 6.2.1 of [RFC3986] (Berners-Lee, T., Fielding, R., and L. Masinter, “Uniform Resource Identifier (URI): Generic Syntax,” January 2005.) (Simple String Comparison). 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 or the IP loopback literals 127.0.0.1 or [::1] as the hostname.
- 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.
This specification also defines the following request parameters:
- 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. One method to achieve this is to store a cryptographically random value in HTML5 local storage and use a cryptographic hash of the value as the nonce parameter. In that case, the nonce in the returned ID Token is compared to the hash of the value in local storage to detect ID Token replay by third parties.
- display
- OPTIONAL. ASCII [RFC20] (Cerf, V., “ASCII format for Network Interchange,” October 1969.) string value that specifies how the Authorization Server displays the authentication and consent user interface pages to the End-User. The defined values are:
The Authorization Server MAY also attempt to detect the capabilities of the User Agent and present an appropriate display.
- page
- The Authorization Server SHOULD display the authentication and consent UI consistent with a full User Agent page view. If the display parameter is not specified, this is the default display mode.
- popup
- The Authorization Server SHOULD display the authentication and consent UI consistent with a popup User Agent window. The popup User Agent window should be of an appropriate size for a login-focused dialog and should not obscure the entire window that it is popping up over.
- touch
- The Authorization Server SHOULD display the authentication and consent UI consistent with a device that leverages a touch interface.
- wap
- The Authorization Server SHOULD display the authentication and consent UI consistent with a "feature phone" type display.
- If an OP receives a display value outside the set defined above that it does not understand, it MAY return an error or it MAY ignore it; in practice, not returning errors for not-understood values will help facilitate phasing in extensions using new display values.
- prompt
- OPTIONAL. Space-delimited, case-sensitive list of ASCII string values that specifies whether the Authorization Server prompts the End-User for reauthentication and consent. The defined values are: