TOC 
DraftN. Sakimura
 NRI
 J. Bradley, Ed.
 Protiviti
 M. Jones
 Microsoft
 E. Jay
 MGI1
 July 28, 2011


OpenID Connect Discovery 1.0 - draft 03

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 consists of Core, UserInfo, Protocol Bindings, Discovery, Dynamic Client Registration, Session Management, and Framework. This specification is the "Discovery" part of the suite that defines how user and server endpoints are discovered.

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 (Bradner, S., “Key words for use in RFCs to Indicate Requirement Levels,” March 1997.) [RFC2119].



Table of Contents

1.  Introduction
2.  Terminology
3.  Provider Discovery
    3.1.  Identifier Normalization
        3.1.1.  Identifyer Type
        3.1.2.  E-mail Address
        3.1.3.  URL
    3.2.  Non-Normative Examples
        3.2.1.  E-Mail Address
        3.2.2.  URL
        3.2.3.  Account URI
        3.2.4.  Hostname & Port
    3.3.  Redirection
    3.4.  Error
4.  Provider Configuration Information
    4.1.  Provider Configuration Request
    4.2.  Provider Configuration Response
5.  IANA Considerations
6.  Security Considerations
7.  Open Issues and Things To Be Done (TBD)
8.  References
    8.1.  Normative References
    8.2.  Informative References
Appendix A.  Acknowledgements
Appendix B.  Document History
§  Authors' Addresses




 TOC 

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., Ed. and Y. Goland, “Simple Web Discovery,” July 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.



 TOC 

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 (Hammer-Lahav, E., Ed., Recordon, D., and D. Hardt, “OAuth 2.0 Authorization Protocol,” July 2011.) [OAuth2.0], and the terminology defined in the OpenID Connect Core 1.0 (Recordon, D., Sakimura, N., Bradley, J., de Medeiros, B., Jones, M., and E. Jay, “OpenID Connect Core 1.0,” July 2011.) [OpenID.Core] 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.


 TOC 

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 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 (SWD):

Service TypeURI
OpenID Connect Issuer http://openid.net/specs/connect/1.0/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 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.



 TOC 

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:

The identifyer normalization rules are not extensable.

URLs without a host segment are not supported by this discovery specification.



 TOC 

3.1.1.  Identifyer 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] 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.


 TOC 

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.



 TOC 

3.1.3.  URL

A URL identifier is normalized according to the following rules:



 TOC 

3.2.  Non-Normative Examples



 TOC 

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:

SWD ParameterValue
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"]
}



 TOC 

3.2.2.  URL

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

SWD ParameterValue
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:

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/auth"]
}



 TOC 

3.2.3.  Account URI

To find the issuer for the given URI, acct://joe@example.com, the SWD parameters are as follows:

SWD ParameterValue
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/auth"]
}



 TOC 

3.2.4.  Hostname & Port

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

SWD ParameterValue
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/auth"]
}



 TOC 

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.

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"]
}



 TOC 

3.4.  Error

If the Simple Web Discovery endpoint is unreachable or returns a error, then the RP may prepend https: to the host from Sec 3.1 (Provider Discovery) and use that as the issuer.



 TOC 

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 (Provider Discovery) 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 (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 as defined in RFC 5246 (Dierks, T. and E. Rescorla, “The Transport Layer Security (TLS) Protocol Version 1.2,” August 2008.) [RFC5246] and MAY support other transport layer security mechanisms of equivalent security.



 TOC 

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 get the Configuration information

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



 TOC 

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.



ClaimTypeDescription
version string Version of the provider response. "3.0" is the default.
issuer string The URL the OP asserts as issuer
authorization_endpoint string URL of the OP's Authentication and Authorization Endpoint [OpenID.Core] (Recordon, D., Sakimura, N., Bradley, J., de Medeiros, B., Jones, M., and E. Jay, “OpenID Connect Core 1.0,” July 2011.)
token_endpoint string URL of the OP's OAuth 2.0 Token Endpoint [OpenID.Core] (Recordon, D., Sakimura, N., Bradley, J., de Medeiros, B., Jones, M., and E. Jay, “OpenID Connect Core 1.0,” July 2011.)
introspection_endpoint string URL of the OP's Introspection Endpoint [OpenID.Framework] (Sakimura, N., Bradley, J., Jones, M., de Medeiros, B., Mortimore, C., and E. Jay, “OpenID Connect Framework 1.0,” July 2011.)
user_info_endpoint string URL of the OP's UserInfo Endpoint [OpenID.UserInfo] (Sakimura, N., Bradley, J., de Medeiros, B., Jones, M., Jay, E., and G. George, “OpenID Connect UserInfo 1.0,” July 2011.)
check_session_endpoint string URL of the OP's Check Session Endpoint [OpenID.Session] (Sakimura, N., Bradley, J., Jones, M., de Medeiros, B., Mortimore, C., and E. Jay, “OpenID Connect Session Management 1.0,” July 2011.)
refresh_session_endpoint string URL of the OP's Refresh Session Endpoint [OpenID.Session] (Sakimura, N., Bradley, J., Jones, M., de Medeiros, B., Mortimore, C., and E. Jay, “OpenID Connect Session Management 1.0,” July 2011.)
end_session_endpoint string URL of the OP's End Session Endpoint [OpenID.Session] (Sakimura, N., Bradley, J., Jones, M., de Medeiros, B., Mortimore, C., and E. Jay, “OpenID Connect Session Management 1.0,” July 2011.)
jwk_document string URL of the OP's JSON Web Key [JWK] (Jones, M., “JSON Web Key (JWK),” July 2011.) document
registration_endpoint string URL of the OP's Dynamic Client Registration Endpoint [OpenID.Registration] (Sakimura, N., Bradley, J., Ed., and M. Jones, “OpenID Connect Dynamic Client Registration 1.0,” July 2011.)
scopes_supported array A JSON array containing a list of the OAuth 2.0 (Hammer-Lahav, E., Ed., Recordon, D., and D. Hardt, “OAuth 2.0 Authorization Protocol,” July 2011.) [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",
 "token_endpoint": "https://example.com/connect/token"
 "introspection_endpoint": "https://example.com/connect/introspection",
 "user_info_endpoint": "https://example.com/connect/user",
 "check_session_endpoint": "https://example.com/connect/check_session",
 "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"]
}



 TOC 

5.  IANA Considerations

This document makes no request of IANA.



 TOC 

6.  Security Considerations



 TOC 

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:



 TOC 

8.  References



 TOC 

8.1. Normative References

[JWK] Jones, M., “JSON Web Key (JWK),” July 2011.
[OpenID.Core] Recordon, D., Sakimura, N., Bradley, J., de Medeiros, B., Jones, M., and E. Jay, “OpenID Connect Core 1.0,” July 2011.
[OpenID.Framework] Sakimura, N., Bradley, J., Jones, M., de Medeiros, B., Mortimore, C., and E. Jay, “OpenID Connect Framework 1.0,” July 2011.
[OpenID.Registration] Sakimura, N., Bradley, J., Ed., and M. Jones, “OpenID Connect Dynamic Client Registration 1.0,” July 2011.
[OpenID.Session] Sakimura, N., Bradley, J., Jones, M., de Medeiros, B., Mortimore, C., and E. Jay, “OpenID Connect Session Management 1.0,” July 2011.
[OpenID.UserInfo] Sakimura, N., Bradley, J., de Medeiros, B., Jones, M., Jay, E., and G. George, “OpenID Connect UserInfo 1.0,” July 2011.
[RFC2119] Bradner, S., “Key words for use in RFCs to Indicate Requirement Levels,” BCP 14, RFC 2119, March 1997 (TXT, HTML, XML).
[RFC3986] Berners-Lee, T., Fielding, R., and L. Masinter, “Uniform Resource Identifier (URI): Generic Syntax,” STD 66, RFC 3986, January 2005 (TXT, HTML, XML).
[RFC5246] Dierks, T. and E. Rescorla, “The Transport Layer Security (TLS) Protocol Version 1.2,” RFC 5246, August 2008 (TXT).
[RFC5785] Nottingham, M. and E. Hammer-Lahav, “Defining Well-Known Uniform Resource Identifiers (URIs),” RFC 5785, April 2010 (TXT).
[SWD] Jones, M., Ed. and Y. Goland, “Simple Web Discovery,” July 2011.


 TOC 

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 (HTML, PDF).


 TOC 

Appendix A.  Acknowledgements



 TOC 

Appendix B.  Document History

[[ To be removed from the final specification ]]

-03

-02

-01

-00



 TOC 

Authors' Addresses

  Nat Sakimura
  Nomura Research Institute, Ltd.
Email:  n-sakimura@nri.co.jp
  
  John Bradley (editor)
  Protiviti Government Services
Email:  jbradley@mac.com
  
  Michael B. Jones
  Microsoft Corporation
Email:  mbj@microsoft.com
  
  Edmund Jay
  MGI1
Email:  ejay@mgi1.com