OpenID Connect Discovery 1.0 - draft 08

Abstract

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 RESTful manner.

This specification provides a mechanism for the OpenID Connect Client to discover the user's OpenID Provider as well as the necessary endpoints used by the OpenID Connect protocol suite.

Table of Contents

1.  Introduction
    1.1.  Requirements Notation and Conventions
    1.2.  Terminology
2.  Provider Discovery
    2.1.  Identifier Normalization
        2.1.1.  Identifier Type
        2.1.2.  E-Mail Address
        2.1.3.  URL
    2.2.  Non-Normative Examples
        2.2.1.  E-Mail Address
        2.2.2.  URL
        2.2.3.  Hostname & Port
    2.3.  Redirection
3.  Provider Configuration Information
    3.1.  Provider Configuration Request
    3.2.  Provider Configuration Response
    3.3.  Provider Configuration Verification
4.  String Operations
5.  IANA Considerations
6.  Security Considerations
7.  References
    7.1.  Normative References
    7.2.  Informative References
Appendix A.  Acknowledgements
Appendix B.  Notices
Appendix C.  Document History
§  Authors' Addresses

1.  Introduction

In order for an OpenID Client to utilize OpenID Connect services for a user, the Client needs to know where the OpenID Provider is. OpenID Connect uses Simple Web Discovery (Jones, M. and Y. Goland, “Simple Web Discovery,” December 2011.) [SWD] to locate the OpenID Provider for an End-User.

Once an OpenID Provider is identified, the endpoint and other configuration information for that OP is retrieved from a well-known location as a JSON document.

1.1.  Requirements Notation and Conventions

The key words "MUST", "MUST NOT", "REQUIRED", "SHALL", "SHALL NOT", "SHOULD", "SHOULD 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].

Throughout this document, 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.

1.2.  Terminology

This specification uses the terms "Access Token", "Refresh Token", "Authorization Code", "Authorization Grant", "Authorization Server", "Authorization Endpoint", "Client", "Client Identifier", "Client Secret", "Protected Resource", "Resource Owner", "Resource Server", and "Token Endpoint" defined by OAuth 2.0 (Hammer, E., Ed., Recordon, D., and D. Hardt, “OAuth 2.0 Authorization Protocol,” March 2012.) [OAuth2.0], and the terms defined by OpenID Connect Messages 1.0 (Sakimura, N., Recordon, D., Bradley, J., de Medeiros, B., Jones, M., and E. Jay, “OpenID Connect Messages 1.0,” April 2012.) [OpenID.Messages]. This specification also defines the following terms:

Principal

An Entity that is the target of a request in Simple Web Discovery.

Identifier

An Identifier is either an http or https URI (commonly referred to as a URL within this document), or an account URI. This document defines various kinds of Identifiers, designed for use in different contexts.

2.  Provider Discovery

OpenID Provider discovery is optional; if a Relying Party knows the OP information through an out-of-band mechanism, they can skip this step and proceed to Section 3 (Provider Configuration Information).

Provider discovery requires the following information to make a discovery request:

Principal

Identifier of the target End-User who is the subject of the discovery request

Host

Server where a Simple Web Discovery service is hosted

Service

URI identifying the type of service whose location is requested

OpenID Connect uses the following discoverable service in Simple Web Discovery (Jones, M. and Y. Goland, “Simple Web Discovery,” December 2011.) [SWD]:

To start discovery of OpenID endpoints, the End-User supplies an Identifier to the Client or Relying Party. The Client applies the normalization rules to the Identifier to extract the principal and host. Then it makes a HTTPS request to the host's Simple Web Discovery (Jones, M. and Y. Goland, “Simple Web Discovery,” December 2011.) [SWD] endpoint with the principal and service parameters to obtain the location of the requested service. The Client MUST perform a TLS/SSL server certificate check, per RFC 6125 (Saint-Andre, P. and J. Hodges, “Representation and Verification of Domain-Based Application Service Identity within Internet Public Key Infrastructure Using X.509 (PKIX) Certificates in the Context of Transport Layer Security (TLS),” March 2011.) [RFC6125].

What MUST be returned in the response is the issuer. This includes URI scheme, HOST, and OPTIONALLY, port.

2.1.  Identifier Normalization

The purpose of normalization is to extract a normalized principal and host from the user input. This is then used as input to SWD to discover the issuer.

The user Identifier SHOULD be one of the following:

• E-Mail address
• URL

The Identifier normalization rules MAY be extended by additional specifications to enable other identifier types such as telephone numbers or XRIs (Reed, D. and D. McAlpin, “Extensible Resource Identifier (XRI) Syntax V2.0,” November 2005.) [XRI_Syntax_2.0] to also be used.

URLs without a "host" portion are not supported by this specification.

2.1.1.  Identifier Type

1. Identifiers starting with the XRI (Reed, D. and D. McAlpin, “Extensible Resource Identifier (XRI) Syntax V2.0,” November 2005.) [XRI_Syntax_2.0] global context symbols ('=','@', and '!') are RESERVED. Processing of these identifiers is out of scope for this specification.
2. Any Identifier that contains the '@' character in any position other than the first position MUST be treated as an e-mail address.
3. All other Identifiers MUST be treated as URLs. URLs containing the '@' character must escape any '@' characters so that they are represented as %40.

2.1.2.  E-Mail Address

Identifiers using e-mail address syntax MUST conform to the "addr-spec" syntax of RFC 5322 (Resnick, P., Ed., “Internet Message Format,” October 2008.) [RFC5322] and MUST NOT contain any syntax designated by that specification as being obsolete. If the Identifier is an e-mail address, the SWD principal value is the entire e-mail address and the SWD host value is the "domain" portion of the "addr-spec".

2.1.3.  URL

A URL Identifier is normalized according to the following rules:

• If the URL does not have an RFC 3986 (Berners-Lee, T., Fielding, R., and L. Masinter, “Uniform Resource Identifier (URI): Generic Syntax,” January 2005.) [RFC3986] "scheme" portion, the "https" scheme is prefixed to the URL, with the "scheme" portion being separated from the "authority" portion by a "://" delimiter string.
• If the URL contains a fragment portion, it MUST be stripped off together with the fragment delimiter character "#".
• The resulting URL is used as the SWD principal. The SWD host value is extracted from the "authority" portion of the URL, as defined by RFC 3986 (Berners-Lee, T., Fielding, R., and L. Masinter, “Uniform Resource Identifier (URI): Generic Syntax,” January 2005.) [RFC3986], by concatenating the "host" and "port" portions of the URL, separating them with a colon (':') character. See Section 2.2.3 (Hostname & Port) for a non-normative example.

2.2.  Non-Normative Examples

2.2.1.  E-Mail Address

To find the issuer for the given e-mail address, joe@example.com, the SWD parameters are as follows:

Following the SWD specification, the Client would make the following request to get the discovery information:

GET /.well-known/simple-web-discovery?principal=joe%40example.com&service=http%3A%2F%2Fopenid.net%2Fspecs%2Fconnect%2F1.0%2Fissuer HTTP/1.1
Host: example.com

HTTP/1.1 200 OK
Content-Type: application/json

{
 "locations":["https://server.example.com"]
}

2.2.2.  URL

To find the issuer for the given URL, https://example.com/joe, the SWD parameters are as follows:

Following the SWD specification, the Client would make the following request to get the discovery information:

GET /.well-known/simple-web-discovery?principal=https%3A%2F%2Fexample.com%2Fjoe&service=http%3A%2F%2Fopenid.net%2Fspecs%2Fconnect%2F1.0%2Fissuer HTTP/1.1
Host: example.com

HTTP/1.1 200 OK
Content-Type: application/json

{
 "locations":["https://server.example.com"]
}

2.2.3.  Hostname & Port

To find the issuer for the given hostname, example.com:8080, the SWD parameters are as follows:

Following the SWD specification, the Client would make the following request to get the discovery information:

GET /.well-known/simple-web-discovery?principal=https%3A%2F%2Fexample.com%3A8080%2F&service=http%3A%2F%2Fopenid.net%2Fspecs%2Fconnect%2F1.0%2Fissuer HTTP/1.1
Host: example.com:8080

HTTP/1.1 200 OK
Content-Type: application/json

{
 "locations":["https://server.example.com"]
}

2.3.  Redirection

In cases where the SWD request is to be handled at a host or location other than the one derived from the End-User's Identifier, the host will return a JSON object containing the new location. (Support for service redirection is a required feature of Simple Web Discovery (Jones, M. and Y. Goland, “Simple Web Discovery,” December 2011.) [SWD].)

To enable service level redirection, a SWD server MAY return a 200 OK to an HTTPS request with a content type of application/json (or whatever other content type has been negotiated) that contains a JSON object that contains a member pair whose name is the string SWD_service_redirect whose value is a JSON object with a member pair whose name is location and whose value is a string that encodes a URI. Optionally the JSON object value of SWD_service_redirect MAY also contain a member whose name is expires and whose value is a JSON number that encodes an integer.

The location member identifies the URI that the caller MUST redirect all SWD requests for that domain to until the expires time is met. SWD requests for the redirected domain MUST be constructed by taking the URI returned in the location and using it as the base URI to which the SWD form arguments are then added as query parameters. The location URI MUST NOT include a query component.

GET /.well-known/simple-web-discovery?principal=joe%40example.com&service=http%3A%2F%2Fopenid.net%2Fspecs%2Fconnect%2F1.0%2Fissuer HTTP/1.1
Host: example.com

HTTP/1.1 200 OK
Content-Type: application/json

{
 "SWD_service_redirect":
  {
   "location":"https://example.net/swd_server"
  }
}

GET /swd_server?principal=joe%40example.com&service=http%3A%2F%2Fopenid.net%2Fspecs%2Fconnect%2F1.0%2Fissuer HTTP/1.1
Host: example.net

HTTP/1.1 200 OK
Content-Type: application/json

{
 "locations":["https://server.example.com"]
}

3.  Provider Configuration Information

This step is optional. The OpenID Provider endpoints and configuration information may be obtained out-of-band.

Using the issuer discovered in Section 2 (Provider Discovery) or through direct configuration, the OpenID Provider's configuration can be retrieved.

OpenID Providers MUST make a JSON document available at the path formed by concatenating the string /.well-known/openid-configuration to the issuer. The syntax and semantics of .well-known are defined in RFC 5785 (Nottingham, M. and E. Hammer-Lahav, “Defining Well-Known Uniform Resource Identifiers (URIs),” April 2010.) [RFC5785]. openid-configuration MUST point to a JSON document compliant with this specification.

OpenID Providers MUST support receiving SWD requests via TLS 1.2 RFC 5246 (Dierks, T. and E. Rescorla, “The Transport Layer Security (TLS) Protocol Version 1.2,” August 2008.) [RFC5246] and/or TLS 1.0 [RFC2246] (Dierks, T. and C. Allen, “The TLS Protocol Version 1.0,” January 1999.) and MAY support other transport layer security mechanisms of equivalent security.

3.1.  Provider Configuration Request

An OpenID Provider Configuration Document MUST be queried using an HTTPS GET request at the previously specified path. The Client MUST perform a TLS/SSL server certificate check, per RFC 6125 (Saint-Andre, P. and J. Hodges, “Representation and Verification of Domain-Based Application Service Identity within Internet Public Key Infrastructure Using X.509 (PKIX) Certificates in the Context of Transport Layer Security (TLS),” March 2011.) [RFC6125].

The Client would make the following request to the issuer to get the Configuration information, if the issuer contains no path component.

GET /.well-known/openid-configuration HTTP/1.1
Host: example.com

If the issuer value contains a path component any terminating / MUST be removed before appending /.well-known/openid-configuration. The Client would make the following request to the issuer to get the Configuration information, if the issuer string were https://example.com/issuer1

GET /issuer1/.well-known/openid-configuration HTTP/1.1
Host: example.com

3.2.  Provider Configuration Response

The response is a set of Claims about the OpenID Provider's configuration, including all necessary endpoints, supported scopes, and public key location information.

The response MUST return a plain text JSON object that contains a set of Claims that are a subset of those defined below.

Claims that return multiple values are JSON arrays. Claims with 0 elements must be omitted from the response.

Other Claims MAY also be returned.

Example response:

{
 "authorization_endpoint": "https://server.example.com/connect/authorize",
 "issuer" : "https://server.example.com",
 "token_endpoint": "https://server.example.com/connect/token",
 "token_endpoint_auth_types_supported": ["client_secret_basic", "private_key_jwt"],
 "userinfo_endpoint": "https://server.example.com/connect/user",
 "check_id_endpoint": "https://server.example.com/connect/check_id",
 "refresh_session_endpoint": "https://server.example.com/connect/refresh_session",
 "end_session_endpoint": "https://server.example.com/connect/end_session",
 "jwk_url": "https://server.example.com/jwk.json",
 "registration_endpoint": "https://server.example.com/connect/register",
 "scopes_supported": ["openid", "profile", "email", "address", "phone"],
 "response_types_supported": ["code", "code id_token", "token id_token"],
 "acrs_supported": ["1","2","http://id.incommon.org/assurance/bronze"],
 "user_id_types_supported": ["public", "pairwise"],
 "userinfo_algs_supported": ["HS256", "RS256", "A128CBC", "A128KW", "RSA1_5"],
 "id_token_algs_supported": ["HS256", "RS256", "A128CBC", "A128KW", "RSA1_5"],
 "request_object_algs_supported": ["HS256", "RS256", "A128CBC", "A128KW", "RSA1_5"]
 }

3.3.  Provider Configuration Verification

If the configuration response contains the issuer element, the value MUST exactly match the issuer for the URL that was directly used to retrieve the configuration. Since the discovery process allows for multiple levels of redirection (Redirection), this issuer URL may be different from the one originally used to begin the discovery process.

4.  String Operations

Processing some OpenID Connect messages requires comparing values in the messages to known values. For example, the member names in the provider configuration response might be compared to specific member names such as issuer. Comparing Unicode strings, however, has significant security implications.

Therefore, comparisons between JSON strings and other Unicode strings MUST be performed as specified below:

1. Remove any JSON applied escaping to produce an array of Unicode code points.
2. Unicode Normalization (Davis, M., Whistler, K., and M. Dürst, “Unicode Normalization Forms,” 09 2009.) [USA15] MUST NOT be applied at any point to either the JSON string or to the string it is to be compared against.
3. Comparisons between the two strings MUST be performed as a Unicode code point to code point equality comparison.

In several places, this specification uses space delimited lists of strings. In all such cases, only the ASCII space character (0x20) MAY be used for this purpose.

5.  IANA Considerations

Per RFC 5785 (Nottingham, M. and E. Hammer-Lahav, “Defining Well-Known Uniform Resource Identifiers (URIs),” April 2010.) [RFC5785], the following registration is requested:

URI suffix

openid-configuration

Change controller

OpenID Foundation

Specification document

This document

6.  Security Considerations

TBD

7.  References

7.1. Normative References

7.2. Informative References

Appendix A.  Acknowledgements

Appendix B.  Notices

Copyright (c) 2012 The OpenID Foundation.

The OpenID Foundation (OIDF) grants to any Contributor, developer, implementer, or other interested party a non-exclusive, royalty free, worldwide copyright license to reproduce, prepare derivative works from, distribute, perform and display, this Implementers Draft or Final Specification solely for the purposes of (i) developing specifications, and (ii) implementing Implementers Drafts and Final Specifications based on such documents, provided that attribution be made to the OIDF as the source of the material, but that such attribution does not indicate an endorsement by the OIDF.

The technology described in this specification was made available from contributions from various sources, including members of the OpenID Foundation and others. Although the OpenID Foundation has taken steps to help ensure that the technology is available for distribution, it takes no position regarding the validity or scope of any intellectual property or other rights that might be claimed to pertain to the implementation or use of the technology described in this specification or the extent to which any license under such rights might or might not be available; neither does it represent that it has made any independent effort to identify any such rights. The OpenID Foundation and the contributors to this specification make no (and hereby expressly disclaim any) warranties (express, implied, or otherwise), including implied warranties of merchantability, non-infringement, fitness for a particular purpose, or title, related to this specification, and the entire risk as to implementing this specification is assumed by the implementer. The OpenID Intellectual Property Rights policy requires contributors to offer a patent promise not to assert certain patent claims against other contributors and against implementers. The OpenID Foundation invites any interested party to bring to its attention any copyrights, patents, patent applications, or other proprietary rights that may cover technology that may be required to practice this specification.

Appendix C.  Document History

[[ To be removed from the final specification ]]

-08

• Remove the no path component restriction from issuer, per issue #513
• Updated Notices
• Updated References

-07

• Rename iso29115_supported to acrs_supported
• Rename jwk_document to jwk_url
• specify full email address to be used for the principal parameter
• Added token_endpoint_auth_types_supported for list of Token Endpoint authentication types
• Added token_endpoint_auth_algs_supported for Token Endpoint supported authentication algorithms
• Added 'pairwise' and 'public' to supported identifier types
• Added valid signature and encryption algorithms for OpenID Request Object
• Added URLs for JWK and X509 encryption keys
• Use RFC 6125 to verify TLS endpoints
• Removed fallback mechanism when discovery endpoint is unreachable
• Removed Account URI scheme
• Changed 'contact' to 'contacts', 'redirect_uri' to 'redirect_uris'
• Added section about string comparison rules needed
• Allows extensions to identifier normalization via specifications
• Clarifies the host in a URL
• Update John Bradley email and affiliation for Implementer's Draft
• Change flows_supported to response_types_supported
• Register openid-configuration .well-known path in IANA Considerations
• Corrected instances of x509_url_encryption to x509_encryption_url and jwk_url_encryption to jwk_encryption_url

-06

• Changed Check Session Endpoint to Check ID Endpoint to match Basic.
• Changed certs_url to x509_url to match registration and JWE format.

-05

• Ticket #46 Added text to 3.3
• Deleted duplicate check session endpoint from 4.2
• Ticket #40 Added clarification of issuer url to 4.2
• Ticket #39 Cleaned up issuer examples and added verification text.

-04

• Changes associated with renaming "Lite" to "Basic Client" and replacing "Core" and "Framework" with "Messages" and "Standard".
• Numerous cleanups, including updating references.

-03

• Corrected examples.

-02

• Correct issues raised by Johnny Bufu and discussed on the 7-Jul-11 working group call.

-01

• Incorporate working group decisions from 5-Jul-11 spec call.
• Consistency and cleanup pass, including removing unused references.

-00

• Initial version based upon former openid-connect-swd-1_0 spec.

Authors' Addresses