Draft N. Sakimura NRI J. Bradley, Ed. Independent M. Jones Microsoft E. Jay MGI1 September 30, 2011 OpenID Connect Discovery 1.0 - draft 06 Abstract OpenID Connect is an identity protocol that provides authentication, authorization, and attribute transmission capability. It allows third party attested claims from distributed sources. The specification suite builds on OAuth 2.0 and consists of Building Blocks (Messages, Discovery, Dynamic Client Registration, Session Management, JSON Web Token, JSON Web Signature, JSON WEB Encryption, JSON Web Keys, Simple Web Discovery), Protocol Bindings (e.g., Standard and Basic Client) and Extensions. This specification is the "Discovery" part of the suite that defines how user and server endpoints are discovered. Sakimura, et al. [Page 1] OpenID Connect Discovery 1.0 - draft 06 September 2011 Requirements Language 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 [RFC2119]. Table of Contents 1. Introduction . . . . . . . . . . . . . . . . . . . . . . . . . 3 2. Terminology . . . . . . . . . . . . . . . . . . . . . . . . . 4 3. Provider Discovery . . . . . . . . . . . . . . . . . . . . . . 5 3.1. Identifier Normalization . . . . . . . . . . . . . . . . . 5 3.1.1. Identifier Type . . . . . . . . . . . . . . . . . . . 6 3.1.2. E-mail Address . . . . . . . . . . . . . . . . . . . . 6 3.1.3. URL . . . . . . . . . . . . . . . . . . . . . . . . . 6 3.2. Non-Normative Examples . . . . . . . . . . . . . . . . . . 6 3.2.1. E-Mail Address . . . . . . . . . . . . . . . . . . . . 6 3.2.2. URL . . . . . . . . . . . . . . . . . . . . . . . . . 7 3.2.3. Account URI . . . . . . . . . . . . . . . . . . . . . 8 3.2.4. Hostname & Port . . . . . . . . . . . . . . . . . . . 8 3.3. Redirection . . . . . . . . . . . . . . . . . . . . . . . 9 3.4. Error . . . . . . . . . . . . . . . . . . . . . . . . . . 10 4. Provider Configuration Information . . . . . . . . . . . . . . 11 4.1. Provider Configuration Request . . . . . . . . . . . . . . 11 4.2. Provider Configuration Response . . . . . . . . . . . . . 11 4.3. Provider Configuration Verification . . . . . . . . . . . 13 5. IANA Considerations . . . . . . . . . . . . . . . . . . . . . 15 6. Security Considerations . . . . . . . . . . . . . . . . . . . 16 7. Open Issues and Things To Be Done (TBD) . . . . . . . . . . . 17 8. References . . . . . . . . . . . . . . . . . . . . . . . . . . 18 8.1. Normative References . . . . . . . . . . . . . . . . . . . 18 8.2. Informative References . . . . . . . . . . . . . . . . . . 18 Appendix A. Acknowledgements . . . . . . . . . . . . . . . . . . 19 Appendix B. Document History . . . . . . . . . . . . . . . . . . 20 Authors' Addresses . . . . . . . . . . . . . . . . . . . . . . . . 22 Sakimura, et al. [Page 2] OpenID Connect Discovery 1.0 - draft 06 September 2011 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 [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. Sakimura, et al. [Page 3] OpenID Connect Discovery 1.0 - draft 06 September 2011 2. Terminology In addition to 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" that are defined by OAuth 2.0 [OAuth2.0], and the terminology defined in the OpenID Connect Messages 1.0 [OpenID.Messages] specification, the following terms are defined: Principal A resource that is the target of a request in Simple Web Discovery. Issuer A verifiable identifier for the OpenID Provider. An "issuer" is a HTTPS URL with no path component. 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. Sakimura, et al. [Page 4] OpenID Connect Discovery 1.0 - draft 06 September 2011 3. 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 4. 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 (SWD): +----------------------+--------------------------------------------+ | Service Type | URI | +----------------------+--------------------------------------------+ | OpenID Connect | http://openid.net/specs/connect/1.0/issuer | | Issuer | | +----------------------+--------------------------------------------+ To start discovery of OpenID end points, the end-user supplies an identifier to the client or relying party. The client performs normalization rules to the identifier to extract the principal and host. Then it makes a HTTPS request to the host's Simple Web Discovery endpoint with the "principal" and "service" parameters to obtain the location of the requested service. What MUST be returned in the response is the "issuer". This includes URI scheme, HOST, and OPTIONALLY, port. 3.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 can be one of the following: o xri Sakimura, et al. [Page 5] OpenID Connect Discovery 1.0 - draft 06 September 2011 o E-mail address o URL The identifier normalization rules are not extensible. URLs without a host segment are not supported by this discovery specification. 3.1.1. Identifier Type 1. Identifiers starting with the XRI [XRI_Syntax_2.0] characters ('=','@', and '!') are reserved. Processing of these is out of scope for this document. 2. Any identifier that contains the character '@' in any other position other than the first position must be treated as an e-mail address. 3. All other identifiers are treated as a URL. 3.1.2. E-mail Address If the identifier is an e-mail address, the principal is the e-mail address and the host is the portion to the right of the '@' character. 3.1.3. URL A URL identifier is normalized according to the following rules: o If the URL does not have a Scheme part, the string "https://" is prefixed to the URL as the Scheme [RFC3986]. o If the URL contains a fragment part, it MUST be stripped off together with the fragment delimiter character "#". o The resulting URL is used as the principal and the host is extracted from it according to URI [RFC3986] syntax rules. 3.2. Non-Normative Examples 3.2.1. E-Mail Address To find the "issuer" for the given e-mail address, "joe@example.com", the SWD parameters are as follows: Sakimura, et al. [Page 6] OpenID Connect Discovery 1.0 - draft 06 September 2011 +---------------+--------------------------------------------+ | SWD Parameter | Value | +---------------+--------------------------------------------+ | principal | joe@example.com | | | | | host | example.com | | | | | service | http://openid.net/specs/connect/1.0/issuer | +---------------+--------------------------------------------+ 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%2Ecom&service=http%3A%2F%2Fopenid%2Enet%2Fspecs%2Fconnect%2F1%2E0%2Fissuer HTTP/1.1 Host: example.com HTTP/1.1 200 O.K. Content-Type: application/json { "locations":["https://example.com/auth"] } 3.2.2. URL To find the "issuer" for the given URL, "https://example.com/joe", the SWD parameters are as follows: +---------------+--------------------------------------------+ | SWD Parameter | Value | +---------------+--------------------------------------------+ | principal | https://example.com/joe | | | | | host | example.com | | | | | service | http://openid.net/specs/connect/1.0/issuer | +---------------+--------------------------------------------+ Following the SWD specification, the client would make the following request to get the discovery information: Sakimura, et al. [Page 7] OpenID Connect Discovery 1.0 - draft 06 September 2011 GET /.well-known/simple-web-discovery?principal=https%3A%2F%2Fexample%2Ecom%2Fjoe&service=http%3A%2F%2Fopenid%2Enet%2Fspecs%2Fconnect%2F1%2E0%2Fissuer HTTP/1.1 Host: example.com HTTP/1.1 200 O.K. Content-Type: application/json { "locations":["https://example.com"] } 3.2.3. Account URI To find the "issuer" for the given URI, "acct://joe@example.com", the SWD parameters are as follows: +---------------+--------------------------------------------+ | SWD Parameter | Value | +---------------+--------------------------------------------+ | principal | acct://joe@example.com/ | | | | | host | example.com | | | | | service | http://openid.net/specs/connect/1.0/issuer | +---------------+--------------------------------------------+ Following the SWD specification, the client would make the following request to get the discovery information: GET /.well-known/simple-web-discovery?principal=acct%3A%2F%2Fjoe%40example%2Ecom%2F&service=http%3A%2F%2Fopenid%2Enet%2Fspecs%2Fconnect%2F1%2E0%2Fissuer HTTP/1.1 Host: example.com HTTP/1.1 200 O.K. Content-Type: application/json { "locations":["https://example.com"] } 3.2.4. Hostname & Port To find the "issuer" for the given hostname, "example.com:8080", the SWD parameters are as follows: Sakimura, et al. [Page 8] OpenID Connect Discovery 1.0 - draft 06 September 2011 +---------------+--------------------------------------------+ | SWD Parameter | Value | +---------------+--------------------------------------------+ | principal | https://example.com:8080/ | | | | | host | example.com:8080 | | | | | service | http://openid.net/specs/connect/1.0/issuer | +---------------+--------------------------------------------+ 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%2Ecom%3A8080%2F&service=http%3A%2F%2Fopenid%2Enet%2Fspecs%2Fconnect%2F1%2E0%2Fissuer HTTP/1.1 Host: example.com:8080 HTTP/1.1 200 O.K. Content-Type: application/json { "locations":["https://example.com"] } 3.3. Redirection In cases where the SWD request is 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. To enable service level redirection a SWD server MAY return a 200 O.k. 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. Sakimura, et al. [Page 9] OpenID Connect Discovery 1.0 - draft 06 September 2011 GET /.well-known/simple-web-discovery?principal=joe%40example%2Ecom&service=http%3A%2F%2Fopenid%2Enet%2Fspecs%2Fconnect%2F1%2E0%2Fissuer HTTP/1.1 Host: example.com HTTP/1.1 200 O.K. Content-Type: application/json { "SWD_service_redirect": { "location":"https://example.net/swd_server" } } GET /swd_server?principal=joe%40example%2Ecom&service=http%3A%2F%2Fopenid%2Enet%2Fspecs%2Fconnect%2F1%2E0%2Fissuer HTTP/1.1 Host: example.net HTTP/1.1 200 O.K. Content-Type: application/json { "locations":["https://example.net/auth"] } 3.4. Error If the Simple Web Discovery endpoint is unreachable or returns an error, then the RP may prepend https: to the host from Sec 3.1 (Section 3) and use that as the "issuer". Sakimura, et al. [Page 10] OpenID Connect Discovery 1.0 - draft 06 September 2011 4. 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 3 or through direct configuration the OpenID Provider's configuration can be retrieved. OpenID Providers MUST make available a JSON document at the path .well-known/openid-configuration. The syntax and semantics of ".well-known" are defined in RFC 5785 [RFC5785]. "openid-configuration" MUST point to a JSON document compliant with this specification. OpenID Providers MUST support receiving SWD requests via TLS 1.2 as defined in RFC 5246 [RFC5246] and MAY support other transport layer security mechanisms of equivalent security. 4.1. Provider Configuration Request An OpenID Provider Configuration Document is queried using a HTTPS GET request with the previously specified path. The client would make the following request to the "issuer "using TLS to get the Configuration information GET /.well-known/openid-configuration HTTP/1.1 Host: example.com 4.2. Provider Configuration Response The response is a set of claims about the OpenID Provider's configuration, including all necessary endpoint, supported scope, 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. Sakimura, et al. [Page 11] OpenID Connect Discovery 1.0 - draft 06 September 2011 +--------------------------+--------+-------------------------------+ | Claim | Type | Description | +--------------------------+--------+-------------------------------+ | version | string | Version of the provider | | | | response. "3.0" is the | | | | default. | | | | | | issuer | string | The https: URL with no path | | | | component the OP asserts as | | | | "its issuer identifier" | | | | | | authorization_endpoint | string | URL of the OP's | | | | Authentication and | | | | Authorization Endpoint | | | | [OpenID.Messages] | | | | | | token_endpoint | string | URL of the OP's OAuth 2.0 | | | | Token Endpoint | | | | [OpenID.Messages] | | | | | | user_info_endpoint | string | URL of the OP's UserInfo | | | | Endpoint [OpenID.Messages] | | | | | | check_id_endpoint | string | URL of the OP's Check ID | | | | Endpoint [OpenID.Session] | | | | | | refresh_session_endpoint | string | URL of the OP's Refresh | | | | Session Endpoint | | | | [OpenID.Session] | | | | | | end_session_endpoint | string | URL of the OP's End Session | | | | Endpoint [OpenID.Session] | | | | | | jwk_document | string | URL of the OP's JSON Web Key | | | | [JWK] document | | | | | | x509_url | string | URL of the OP's X.509 | | | | certificates in PEM format. | | | | | | registration_endpoint | string | URL of the OP's Dynamic | | | | Client Registration Endpoint | | | | [OpenID.Registration] | | | | | Sakimura, et al. [Page 12] OpenID Connect Discovery 1.0 - draft 06 September 2011 | scopes_supported | array | A JSON array containing a | | | | list of the OAuth 2.0 | | | | [OAuth2.0] scopes that this | | | | server supports. The server | | | | MUST support the "openid" | | | | scope. | | | | | | flows_supported | array | A JSON array containing a | | | | list of the OAuth 2.0 flows | | | | that this server supports. | | | | The server MUST support the | | | | code flow. | | | | | | iso29115_supported | array | A JSON array containing a | | | | list of the ISO 29115 | | | | assurance contexts that this | | | | server supports. | | | | | | identifiers_supported | array | A JSON array containing a | | | | list of the user identifier | | | | types that this server | | | | supports | +--------------------------+--------+-------------------------------+ Table 1: Reserved Claim Definitions Example response { "authorization_endpoint": "https://example.com/connect/authorize", "issuer" : "https://example.com", "token_endpoint": "https://example.com/connect/token" "user_info_endpoint": "https://example.com/connect/user", "check_id_endpoint": "https://example.com/connect/check_id", "refresh_session_endpoint": "https://example.com/connect/refresh_session", "end_session_endpoint": "https://example.com/connect/end_session", "jwk_document": "https://example.com/jwk.json", "registration_endpoint": "https://example.com/connect/register", "scopes_supported": ["openid"], "flows_supported": ["code", "token"], "iso29115_supported": ["http://www.idmanagement.gov/schema/2009/05/icam/openid-trust-level1.pdf"], "identifiers_supported": ["public", "ppid"] } 4.3. Provider Configuration Verification If the configuration response contains the "issuer" element, the value MUST exactly match the "issuer" URL that was used to retrieve Sakimura, et al. [Page 13] OpenID Connect Discovery 1.0 - draft 06 September 2011 it. Sakimura, et al. [Page 14] OpenID Connect Discovery 1.0 - draft 06 September 2011 5. IANA Considerations This document makes no request of IANA. Sakimura, et al. [Page 15] OpenID Connect Discovery 1.0 - draft 06 September 2011 6. Security Considerations TBD Sakimura, et al. [Page 16] OpenID Connect Discovery 1.0 - draft 06 September 2011 7. Open Issues and Things To Be Done (TBD) [[ To be removed from the final specification ]] Following items remain to be done in this draft: o Should "issuer" be in the Provider Configuration Response? o Should "issuer" be explicitly restricted to the https:// scheme? Sakimura, et al. [Page 17] OpenID Connect Discovery 1.0 - draft 06 September 2011 8. References 8.1. Normative References [JWK] Jones, M., "JSON Web Key (JWK)", July 2011. [OpenID.Messages] Sakimura, N., Recordon, D., Bradley, J., de Medeiros, B., Jones, M., and E. Jay, "OpenID Connect Messages 1.0", September 2011. [OpenID.Registration] Sakimura, N., Bradley, J., Ed., and M. Jones, "OpenID Connect Dynamic Client Registration 1.0", September 2011. [OpenID.Session] Sakimura, N., Bradley, J., Jones, M., de Medeiros, B., Mortimore, C., and E. Jay, "OpenID Connect Session Management 1.0", September 2011. [RFC2119] Bradner, S., "Key words for use in RFCs to Indicate Requirement Levels", BCP 14, RFC 2119, March 1997. [RFC3986] Berners-Lee, T., Fielding, R., and L. Masinter, "Uniform Resource Identifier (URI): Generic Syntax", STD 66, RFC 3986, January 2005. [RFC5246] Dierks, T. and E. Rescorla, "The Transport Layer Security (TLS) Protocol Version 1.2", RFC 5246, August 2008. [RFC5785] Nottingham, M. and E. Hammer-Lahav, "Defining Well-Known Uniform Resource Identifiers (URIs)", RFC 5785, April 2010. [SWD] Jones, M., Ed. and Y. Goland, "Simple Web Discovery", July 2011. 8.2. Informative References [OAuth2.0] Hammer-Lahav, E., Ed., Recordon, D., and D. Hardt, "OAuth 2.0 Authorization Protocol", July 2011. [XRI_Syntax_2.0] Reed, D. and D. McAlpin, "Extensible Resource Identifier (XRI) Syntax V2.0", November 2005. Sakimura, et al. [Page 18] OpenID Connect Discovery 1.0 - draft 06 September 2011 Appendix A. Acknowledgements Sakimura, et al. [Page 19] OpenID Connect Discovery 1.0 - draft 06 September 2011 Appendix B. Document History [[ To be removed from the final specification ]] -06 o Changed Check Session Endpoint to Check ID Endpoint to match Basic. o Changed certs_url to x509_url to match registration and JWE format. -05 o Ticket #46 Added text to 3.3 o Deleted duplicate check session endpoint from 4.2 o Ticket #40 Added clarification of issuer url to 4.2 o Ticket #39 Cleaned up issuer examples and added verification text. -04 o Changes associated with renaming "Lite" to "Basic Client" and replacing "Core" and "Framework" with "Messages" and "Standard". o Numerous cleanups, including updating references. -03 o Corrected examples. -02 o Correct issues raised by Johnny Bufu and discussed on the 7-Jul-11 working group call. -01 o Incorporate working group decisions from 5-Jul-11 spec call. o Consistency and cleanup pass, including removing unused references. -00 Sakimura, et al. [Page 20] OpenID Connect Discovery 1.0 - draft 06 September 2011 o Initial version based upon former openid-connect-swd-1_0 spec. Sakimura, et al. [Page 21] OpenID Connect Discovery 1.0 - draft 06 September 2011 Authors' Addresses Nat Sakimura Nomura Research Institute, Ltd. Email: n-sakimura@nri.co.jp John Bradley (editor) Independent Email: ve7jtb@ve7jtb.com Michael B. Jones Microsoft Corporation Email: mbj@microsoft.com Edmund Jay MGI1 Email: ejay@mgi1.com Sakimura, et al. [Page 22]