T. Lodderstedt | |
Deutsche Telekom AG | |
J. Bradley | |
Ping Identity | |
July 25, 2015 |
OpenID Connect Mobile Discovery Profile 1.0
draft-mobile-discovery-03
OpenID Connect Discovery 1.0 [OpenID.Discovery] section 2.1 specifies a way to normalize a user identifier to derive a resource and especially a host for OpenID Provider Issuer Discovery. While this works well for identifiers as email addresses and urls, it does not work for typical identifiers from the mobile network space. In a mobile environment, MSISDN's or ip-addresses are typical resources identifying a user or the respective mobile network operator (MNO). The structure of those identifiers does not allow for an algorithmic normalization. Thus it will be necessary to have a specific service to perform the normalization.
The OpenID Connect Mobile Discovery Profile specifies the interface of this service. Part of the interface specification will be the identification of possible user input identifier types relevant in the Mobile Connect scenario. Remark: Some of those user input identifier types may not identify a single user/device but may be sufficient to identify the right mobile operator. An example for this is the MNC/MCC tuple (mobile network code/ mobile contry code) or the IP address range.
This profile also specifies how a client registers with the MNO discovery service and how Account Chooser service [Account.Chooser] can be used to further improve user experience in the overall Mobile Connect flow.
OpenID Connect Mobile Discovery Profile 1.0 is a profile of the OpenID Connect Discovery 1.0 [OpenID.Discovery] specification that stipulates how a OpenID Connect relying party (RP) can use mobile network specific identifiers to determine the authoritative issuer for a identifier thereby enabling to detemine the OpenID OP belonging to a particular MNO.
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 [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.
This specification uses the terms "Refresh Token", "Client Identifier",and "Client Secret" defined by OAuth 2.0 [RFC6749]. This specification uses the terms "OpenID Provider (OP)" and Relying Party (RP) defined by OpenID Connect Core [OpenID.Core].
This specification also defines the following terms:
This specification defines two different discovery flows intended to fit the needs of both server-based web as well as native applications residing on mobile devices.
The protocol design is guided by to following requirements:
OpenID Connect RPs using this specification are encouraged to use the OpenID Account chooser service [Account.Chooser]. This allows them to bypass discovery for users that already have account information cached.
This section gives an overview on the redirect-based flow, which is intended to be used by server-side web application. The design of this flow is inspired by the OAuth 2.0 authorization code flow [RFC6749].
Note: This flow, in contrast to the POST-based flow, does support lookup of the MNO based on the user's MSISDN.
The following figure shows the message flow during the discovery process.
+---------+ +---------------+ | |--(A)- Existing Account? ----->| Account | | |<-(B)-- Account Data ----------| Chooser CDS | | | +---------------+ | | +---------------------------------+ | | | Mobile Issuer Discovery Service | | | | | | | +------------------+ | | |--(C)-- Discovery Request ---->| User Interaction | | | Relying |<-(D)----- Code ---------------| Endpoint | | | Party | +------------------+ | | | +------------------+ | | |--(E)----- Code -------------->| Issuer | | | |<-(F)--- Issuer ---------------| Endpoint | | | | +------------------+ | | | +---------------------------------+ | | +---------------+ | |--(G)----- Issuer ------------>| MNO's OP | | |<-(H)--- openid configuration -| | +---------+ +---------------+
Figure 1 Redirect-based flow (Abstract Protocol Flow)
The User Interaction and Issuer Endpoints are specified in sections Section 3.1 and Section 3.2 , respectively.
Access to the OP's meta data (steps (G) and (H)) is defined in [OpenID.Discovery], section 4, and is therefore outside of the scope of this specification.
Note: After the RP logged the user in sucessfully with a particular OP (and has remembered the respective Issuer URL), there is no need to conduct the full issuer process again. The RP can instead directly obtain the OP's meta data using the openid configuration (steps G and H).
This section gives an overview on the POST-based flow, which is intended to be used by native apps residing on mobile devices. The rationale is to allow apps to conduct issuer discovery without the need to use a web browser, which would degrade user experience and increase complexity and implementation effort. The assumption is that such apps cannot reliably be authenticated and authorized, so MSISDN-based lookup is not offered.
The following figure shows the message flow during the discovery process.
+---------+ +---------------------------------+ | | | Mobile Issuer Discovery Service | | | +------------------+ | | |--(A)---discovery data ------->| Issuer | | | |<-(B)--- Issuer ---------------| Endpoint | | | Relying | +------------------+ | | Party | +---------------------------------+ | | +---------------+ | |--(C)----- Issuer ------------>| MNO's OP | | |<-(D)--- openid configuration -| | +---------+ +---------------+
Figure 2 POST-based flow (Abstract Protocol Flow)
TBD: what if the service cannot determine MNO? Right now, we let the discovery fail. Alternatively, the RP could also be provided with a list of potential MNOs, which it can present to the user for selection?
The Mobile Issuer Discovery Service exposes the user interaction and issuer endpoint, which are specified in this section. It may also expose a registration endpoint (see below).
The User Interaction Endpoint provides the user interface to the discovery service. It is used to enter the MSISDN, let the user select her MNO and automatically determining the RP device's IP address. The RP is supposed to redirect the user agent to this endpoint. If the interactive process succeeds, the RP is provided with a code, which it then exchanges at the Issuer Endpoint for the actual Issuer data and (optionally) user-specific data.
The request to the User Interaction endpoint contains the following parameters:
For example, the RP could ask for discovery with the following request (line breaks are for display purposes only):
GET /discovery_ui?client_id=example_client& redirect_uri=https%3A%2F%2Fclient%2Eexample%2Ecom%2Fdiscovery& state=xy&mcc=901&mnc=99 HTTP/1.1 Host: discovery.example.com
The discovery service returns the following parameters:
The following shows how the discovery service redirects the user agent back to the RP:
HTTP/1.1 302 Found Location: https://client.example.com/discovery?code=SplxlOBeZQQYbYS6WxSbIA &state=xyz
If the request fails due to a missing, invalid, or mismatching redirection URI, or if the client identifier is missing or invalid, the discovery server SHOULD inform the end-user of the error and MUST NOT automatically redirect the user-agent to the invalid redirection URI. If the request fails for reasons other than a missing or invalid redirection URI, the discovery server informs the RP by adding the following parameters to the query component of the redirection URI using the "application/x-www-form-urlencoded" format:
This endpoint provides the RP with issuer data. It supports two use cases:
This is reflected in the "signature" of the request:
Either code, mcc or IMSI must be present in the request. The discovery service first validates the client credentials and the RP's authorization to perform the request.
If code is present, the discovery service verifies, whether (1) this code had been issued to this RP and (2) whether "redirect_uri" matches the redirect URI used in the original request to the User Interaction Endpoint (TBD: really needed? we need to conduct a threat analysis).
If "mcc" and "mnc" are present, the discovery service tries to determine the MNO based on this data. The same holds true, if "imsi" is found in the request.
TBD: does it sense to introduce a request type parameter (or different endpoints) to distinguish redirect (code) and direct use?
TBD: client secrets via authorization header
For example, the RP could send the following request (line breaks are for display purposes only):
POST /discovery_issuer HTTP/1.1 Host: discovery.example.com client_id=example_client&client_secret=secret&code=SplxlOBeZQQYbYS6WxSbIA& redirect_uri=https%3A%2F%2Fclient%2Eexample%2Ecom%2Fdiscovery
The response from the issuer endpoint is a JSON object containing the following top level elements:
The following is a non-normative example of the Issuer response:
HTTP/1.1 200 OK Content-Type: application/json;charset=UTF-8 Cache-Control: no-store Pragma: no-cache { "iss": "https://example_provider.com", "login_hint_token": "eyJhbGciOiJSU0EtT0FFUCIsImVuYyI6IkEyNTZHQ00ifQ. OKOawDo13gRp2ojaHV7LFpZcgV7T6DVZKTyKOMTYUmKoTCVJRgckCL9kiMT03JGe ipsEdY3mx_etLbbWSrFr05kLzcSr4qKAq7YN7e9jwQRb23nfa6c9d-StnImGyFDb Sv04uVuxIp5Zms1gNxKKK2Da14B8S4rzVRltdYwam_lDp5XnZAYpQdb76FdIKLaV mqgfwX7XWRxv2322i-vDxRfqNzo_tETKzpVLzfiwQyeyPGLBIO56YJ7eObdv0je8 1860ppamavo35UgoRdbYaBcoh9QcfylQr66oc6vFWXRcZ_ZT2LawVCWTIy3brGPi 6UklfCpIMfIjf7iGdXKHzg. 48V1_ALb6US04U3b. 5eym8TW_c8SuK0ltJ3rpYIzOeDQz7TALvtu6UG9oMo4vpzs9tX_EFShS8iB7j6ji SdiwkIr3ajwQzaBtQD_A. XFBoMYUZodetZdvTiFvSkQ" }
The discovery server respondes with an HTTP 401 status code if the client credentials are invalid and an HTTP 403 status code if the RP is not authorized to request the particular service.
In all other error conditions, the discovery server responds with an HTTP 400 (Bad Request) status code and includes a JSON object containing the following top level elements:
The following is a non-normative example of a error response:
HTTP/1.1 400 Bad Request Content-Type: application/json;charset=UTF-8 Cache-Control: no-store Pragma: no-cache { "error":"invalid_request" }
[TBD]The RP must register with the discovery service and have a valid client_id.
It is recommended that Web server clients use the Account Chooser Central Data Store (CDS) for discovering the users preferred account.
Account Chooser [Account.Chooser] is invoked with the following script:
<script type="text/javascript" src="https://www.accountchooser.com/ac.js" /> <script> accountchooser.CONFIG.uiConfig = { title: 'Sign in to Example.com', favicon: 'http://example.com/favicon.ico', branding: 'http://example.com/branding/ac-blurb.html' }; </script>
If the user clicks on one of the accounts, ac.js sends an HTTP POST to a status checker (userStatusUrl:/account-status) that the client has to to implement. The status checker will receive up to five arguments as URL query parameters.
The paramaters if available are:
For example (with line wraps within values for display purposes only):
POST /token HTTP/1.1 Host: server.example.com Content-Type: application/x-www-form-urlencoded email=555-1212@babytel.com& displayName=i1WsRn1uB1& photoUrl=s6BhdRkqt3& providerId=babytel.com& login_hint_token=eyJhbGciOiJSU0EtT0FFUCIsImVuYyI6IkEyNTZHQ00ifQ. OKOawDo13gRp2ojaHV7LFpZcgV7T6DVZKTyKOMTYUmKoTCVJRgckCL9kiMT03JGe ipsEdY3mx_etLbbWSrFr05kLzcSr4qKAq7YN7e9jwQRb23nfa6c9d-StnImGyFDb Sv04uVuxIp5Zms1gNxKKK2Da14B8S4rzVRltdYwam_lDp5XnZAYpQdb76FdIKLaV mqgfwX7XWRxv2322i-vDxRfqNzo_tETKzpVLzfiwQyeyPGLBIO56YJ7eObdv0je8 1860ppamavo35UgoRdbYaBcoh9QcfylQr66oc6vFWXRcZ_ZT2LawVCWTIy3brGPi 6UklfCpIMfIjf7iGdXKHzg. 48V1_ALb6US04U3b. 5eym8TW_c8SuK0ltJ3rpYIzOeDQz7TALvtu6UG9oMo4vpzs9tX_EFShS8iB7j6ji SdiwkIr3ajwQzaBtQD_A. XFBoMYUZodetZdvTiFvSkQ
Identity providers will populate the account information in Account Chooser's browser local storrage as the result of a successful loggin before redirecting the user back to the RP.
If the user account has not been provisioned in the Browsers local storage, the OP MUST offer to store the account before redirecting the user back to the RP.
The following is an example of the script elements invoking ac.js offering to store an account:
<script type="text/javascript" src="https://www.accountchooser.com/ac.js" /> <script type="text/javascript"> accountchooser.CONFIG = { // Sets the home-page URL to "/top" homeUrl: '/top', // Instructs ac.js to offer storage of an account via // accountchooser.com storeAccount: { email: "555-1212@babytel.com", displayName: "Santa Claus", providerId: : "babytel.com", login_hint_token: "eyJhbGciOiJSU0EtT0FFUCIsImVuYyI6IkEyNTZHQ00ifQ. OKOawDo13gRp2ojaHV7LFpZcgV7T6DVZKTyKOMTYUmKoTCVJRgckCL9kiMT03JGe ipsEdY3mx_etLbbWSrFr05kLzcSr4qKAq7YN7e9jwQRb23nfa6c9d-StnImGyFDb Sv04uVuxIp5Zms1gNxKKK2Da14B8S4rzVRltdYwam_lDp5XnZAYpQdb76FdIKLaV mqgfwX7XWRxv2322i-vDxRfqNzo_tETKzpVLzfiwQyeyPGLBIO56YJ7eObdv0je8 1860ppamavo35UgoRdbYaBcoh9QcfylQr66oc6vFWXRcZ_ZT2LawVCWTIy3brGPi 6UklfCpIMfIjf7iGdXKHzg. 48V1_ALb6US04U3b. 5eym8TW_c8SuK0ltJ3rpYIzOeDQz7TALvtu6UG9oMo4vpzs9tX_EFShS8iB7j6ji SdiwkIr3ajwQzaBtQD_A. XFBoMYUZodetZdvTiFvSkQ", providerId: "babytel.com" } }; </script>
TBD
Open Redirector (user interaction endpoint)
TBD
confidentiality of MSISDN
This document makes no requests of IANA.
[Account.Chooser] | , , "Account Chooser (AC)", May 2013. |
[MODRNA.Authentication] | Connotte, J. and J. Bradley, "OpenID Connect Mobile Authentication Profile 1.0", June 2015. |
[OpenID.Core] | Sakimura, N., Bradley, J., Jones, M., de Medeiros, B. and C. Mortimore, "OpenID Connect Core 1.0", November 2014. |
[OpenID.Discovery] | Sakimura, N., Bradley, J., Jones, M. and E. Jay, "OpenID Connect Discovery 1.0", November 2014. |
[RFC2119] | Bradner, S., "Key words for use in RFCs to Indicate Requirement Levels", BCP 14, RFC 2119, DOI 10.17487/RFC2119, March 1997. |
[RFC6749] | Hardt, D., "The OAuth 2.0 Authorization Framework", RFC 6749, DOI 10.17487/RFC6749, October 2012. |
The OpenID Community would like to thank the following people for their contributions to the development of this specification:
Copyright (c) 2014 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.
[[ To be removed from the final specification ]]
-01
-02
-03