National foreword

This British Standard is the UK implementation of ISO/IEC 26131:2024.

The UK participation in its preparation was entrusted to Technical Committee ICT/1, Information systems co-ordination.

A list of organizations represented on this committee can be obtained on request to its committee manager.

Contractual and legal considerations

This publication has been prepared in good faith, however no representation, warranty, assurance or undertaking (express or implied) is or will be made, and no responsibility or liability is or will be accepted by BSI in relation to the adequacy, accuracy, completeness or reasonableness of this publication. All and any such responsibility and liability is expressly disclaimed to the full extent permitted by the law.

This publication is provided as is, and is to be used at the recipient’s own risk.

The recipient is advised to consider seeking professional guidance with respect to its use of this publication.

This publication is not intended to constitute a contract. Users are responsible for its correct application.

Compliance with a British Standard cannot confer immunity from legal obligations.

This British Standard was published under the authority of the Standards Policy and Strategy Committee on 30 November 2024.

Foreword

ISO (the International Organization for Standardization) and IEC (the International Electrotechnical Commission) form the specialized system for worldwide standardization. National bodies that are members of ISO or IEC participate in the development of International Standards through technical committees established by the respective organization to deal with particular fields of technical activity. ISO and IEC technical committees collaborate in fields of mutual interest. Other international organizations, governmental and non-governmental, in liaison with ISO and IEC, also take part in the work.

The procedures used to develop this document and those intended for its further maintenance are described in the ISO/IEC Directives, Part 1. In particular, the different approval criteria needed for the different types of document should be noted (see www.iso.org/directives or www.iec.ch/members_experts/refdocs).

ISO and IEC draw attention to the possibility that the implementation of this document may involve the use of (a) patent(s). ISO and IEC take no position concerning the evidence, validity or applicability of any claimed patent rights in respect thereof. As of the date of publication of this document, ISO and IEC had not received notice of (a) patent(s) which may be required to implement this document. However, implementers are cautioned that this may not represent the latest information, which may be obtained from the patent database available at www.iso.org/patents and https://patents.iec.ch. ISO and IEC shall not be held responsible for identifying any or all such patent rights.

Any trade name used in this document is information given for the convenience of users and does not constitute an endorsement.

For an explanation of the voluntary nature of standards, the meaning of ISO specific terms and expressions related to conformity assessment, as well as information about ISO's adherence to the World Trade Organization (WTO) principles in the Technical Barriers to Trade (TBT), see www.iso.org/iso/foreword.html. In the IEC, see www.iec.ch/understanding-standards.

This document was prepared by the OpenID Foundation (OIDF) (as OpenID Connect Core 1.0 incorporating errata set 2) and drafted in accordance with its editorial rules. It was adopted, under the JTC 1 PAS procedure, by Joint Technical Committee ISO/IEC JTC 1, Information technology.

Any feedback or questions on this document should be directed to the user’s national standards body. A complete listing of these bodies can be found at www.iso.org/members.html and www.iec.ch/national-committees.

Abstract

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

OpenID Connect 1.0 is a simple identity layer on top of the OAuth 2.0 [RFC6749] 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 [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.

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) [JWT] called an ID Token (see Section 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).

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 [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 [OpenID.Registration], or may be obtained via other mechanisms.

The previous versions of this specification are:

OpenID Connect Core 1.0 incorporating errata set 1 [OpenID.Core.Errata1]
OpenID Connect Core 1.0 (final) [OpenID.Core.Final]

1.1 Requirements Notation and Conventions

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 [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) [JWS] and JSON Web Encryption (JWE) [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.

1.2 Terminology

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 [RFC6749], the terms "Claim Name", "Claim Value", "JSON Web Token (JWT)", "JWT Claims Set", and "Nested JWT" defined by JSON Web Token (JWT) [JWT], the terms "Base64url Encoding", "Header Parameter", and "JOSE Header" defined by JSON Web Signature (JWS) [JWS], the term "User Agent" defined by RFC 7230 [RFC7230], and the term "Response Mode" defined by OAuth 2.0 Multiple Response Type Encoding Practices [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 [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].
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) [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 [RFC4949], ISO/IEC 29115 Entity Authentication Assurance [ISO29115], and ITU‑T X.1252 [X.1252].

1.3 Overview

The OpenID Connect protocol, in abstract, follows the following steps.

The RP (Client) sends a request to the OpenID Provider (OP).
The OP authenticates the End-User and obtains authorization.
The OP responds with an ID Token and usually an Access Token.
The RP can send a request with the Access Token to the UserInfo Endpoint.
The UserInfo Endpoint returns Claims about the End-User.

These steps are illustrated in the following diagram:

2 ID Token

3 Authentication

3.1 Authentication using the Authorization Code Flow

3.2 Authentication using the Implicit Flow

3.3 Authentication using the Hybrid Flow

4 Initiating Login from a Third Party

5 Claims

5.1 Standard Claims

5.2 Claims Languages and Scripts

5.3 UserInfo Endpoint

5.4 Requesting Claims using Scope Values

5.5 Requesting Claims using the "claims" Request Parameter

5.6 Claim Types

5.7 Claim Stability and Uniqueness

6 Passing Request Parameters as JWTs

6.1 Passing a Request Object by Value

6.2 Passing a Request Object by Reference

6.3 Validating JWT-Based Requests

7 Self-Issued OpenID Provider

7.1 Self-Issued OpenID Provider Discovery

7.2 Self-Issued OpenID Provider Registration

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.2 Encryption

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.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.2 OAuth Parameters Registration

18.3 OAuth Extensions Error Registration

18.4 URI Scheme Registration

19 References

19.1 Normative References

19.2 Informative References

BS ISO/IEC 26131:2024

Information technology. OpenID connect. OpenID connect core 1.0 incorporating errata set 2

Current

Published:

30 Nov 2024