T. Lodderstedt
Deutsche Telekom AG
J. Bradley
Ping Identity
July 25, 2015

OpenID Connect Mobile Discovery Profile 1.0
draft-mobile-discovery-03

Abstract

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.


Table of Contents

1. Introduction

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.

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 [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 "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:

2. Overview

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.

2.1. Redirect-based flow

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).

2.2. POST-based flow

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?

3. Mobile Issuer Discovery Service

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).

3.1. User Interaction Endpoint

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.

3.1.1. Request

The request to the User Interaction endpoint contains the following parameters:

client_id
REQUIRED. The identifier of the respective RP. This RP must be known to the discovery service in advance.
redirect_uri
REQUIRED. The URI the user agent shall be sent to after the discovery process has been completed. The RP must register its URIs in advance, the redirect_uri parameter must exactly match one of those URIs.
state
OPTIONAL. Value used by the RP to preserve state of a discovery transaction and to prevent XSRF attacks. The discovery service includes this value when redirecting the user-agent back to the RP.
mcc
OTIONAL. The Mobile Country Code as defined by ITU-T E.212
mnc
OTIONAL. The Mobile Network Code as defined by ITU-T E.212
imsi
OTIONAL. The International Mobile Subscriber Identity.
msisdn
TBD

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

3.1.2. Response

The discovery service returns the following parameters:

code
REQUIRED. The code is a temporary credential associated with the ongoing discovery transaction. The RP is supposed to exchange this code for the actual discovery results at the issuer endpoint.
state
REQUIRED if the "state" parameter was present in the discovery request. The exact value received from the RP.

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

3.1.3. Error Response

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:

error
REQUIRED. A single US ASCII error code from the following:
invalid_request
The request is missing a required parameter, includes an invalid parameter value, includes a parameter more than once, or is otherwise malformed.
unauthorized_client
The RP is not authorized to request disovery using this method.
access_denied
The discovery server denied the request.
server_error
The discovery server encountered an unexpected condition that prevented it from fulfilling the request. (This error code is needed because a 500 Internal Server Error HTTP status code cannot be returned to the client via an HTTP redirect.)
temporarily_unavailable
The discovery server is currently unable to handle the request due to a temporary overloading or maintenance of the server. (This error code is needed because a 503 Service Unavailable HTTP status code cannot be returned to the client via an HTTP redirect.)
Values for the "error" parameter MUST NOT include characters outside the set %x20-21 / %x23-5B / %x5D-7E.
error_description
OPTIONAL. Human-readable US ASCII [USASCII] text providing additional information, used to assist the RP developer in understanding the error that occurred. Values for the "error_description" parameter MUST NOT include characters outside the set %x20-21 / %x23-5B / %x5D-7E.
error_uri
OPTIONAL. A URI identifying a human-readable web page with information about the error, used to provide the client developer with additional information about the error. Values for the "error_uri" parameter MUST conform to the URI-reference syntax and thus MUST NOT include characters outside the set %x21 / %x23-5B / %x5D-7E.
state
REQUIRED if the "state" parameter was present in the discovery request. The exact value received from the RP.

3.2. Issuer Endpoint

This endpoint provides the RP with issuer data. It supports two use cases:

  1. It exchanges the code created by the User Interaction Endpoint for issuer data.
  2. RPs may directly request issuer data by passing mobile network data.

3.2.1. Request

This is reflected in the "signature" of the request:

client_id
REQUIRED. The identifier of the respective RP. This RP must be known to the discovery service in advance.
client_secret
REQUIRED. If a client secret had been issued issued to the RP.
code
OPTIONAL. code value issued by the User Interaction Endpoint to this particular RP.
redirect_uri
REQUIRED. If the parameter "code is present. The actual URI used to invoke the user interaction endpoint.
mcc
OTIONAL. The Mobile Country Code as defined by ITU-T E.212
mnc
REQUIRED. If the parameter "mcc" is present. The Mobile Network Code as defined by ITU-T E.212
imsi
OTIONAL. The International Mobile Subscriber Identity.
msisdn
TBD

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

3.2.2. Response

The response from the issuer endpoint is a JSON object containing the following top level elements:

iss
The Issuer URI "iss" for the user who has authorized discovery.
login_hint_token
A Encrypted JSON web token (JWE) that contains the user hint for the issuer. The token MUST be encrypted with the public key of the issuer. This token is passed to the issuer in the authentication request. Usage, structure, and processing rules of the login hint token are specified in [MODRNA.Authentication]

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

3.2.3. Error Response

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:

error
REQUIRED. A single US ASCII error code from the following:
invalid_request
The request is missing a required parameter, includes an invalid parameter value, includes a parameter more than once, or is otherwise malformed.
server_error
The discovery server encountered an unexpected condition that prevented it from fulfilling the request. (This error code is needed because a 500 Internal Server Error HTTP status code cannot be returned to the client via an HTTP redirect.)
temporarily_unavailable
The discovery server is currently unable to handle the request due to a temporary overloading or maintenance of the server. (This error code is needed because a 503 Service Unavailable HTTP status code cannot be returned to the client via an HTTP redirect.)
invalid_code
RP tried to exchange an invalid code for discovery data (TBD: better HTTP status code 403?)
discovery_failed
TBD
Values for the "error" parameter MUST NOT include characters outside the set %x20-21 / %x23-5B / %x5D-7E.
error_description
OPTIONAL. Human-readable US ASCII [USASCII] text providing additional information, used to assist the RP developer in understanding the error that occurred. Values for the "error_description" parameter MUST NOT include characters outside the set %x20-21 / %x23-5B / %x5D-7E.
error_uri
OPTIONAL. A URI identifying a human-readable web page with information about the error, used to provide the client developer with additional information about the error. Values for the "error_uri" parameter MUST conform to the URI-reference syntax and thus MUST NOT include characters outside the set %x21 / %x23-5B / %x5D-7E.

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

4. Dynamic Registration with Discovery Service

[TBD]The RP must register with the discovery service and have a valid client_id.

5. Account Chooser

5.1. AC Client

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:

email

x
displayName

x
photoUrl

x
providerId

x
login_hint_token

x

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
		 

5.2. AC Identity Provider

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>
		 

6. Security Considerations

TBD

Open Redirector (user interaction endpoint)

7. Privacy Considerations

TBD

confidentiality of MSISDN

8. IANA Considerations

This document makes no requests of IANA.

9. Normative References

[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.

Appendix A. Acknowledgements

The OpenID Community would like to thank the following people for their contributions to the development of this specification:

Appendix B. Notices

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.

Appendix C. Document History

[[ To be removed from the final specification ]]

-01

-02

-03

Authors' Addresses

Torsten Lodderstedt Deutsche Telekom AG EMail: torsten@lodderstedt.net
John Bradley Ping Identity EMail: jbradley@pingidentity.com