G. Fernandez | |
Telefonica | |
F. Walter | |
A. Nennker | |
Deutsche Telekom AG | |
March 6, 2017 |
OpenID Connect MODRNA Client initiated Backchannel Authentication Flow 1.0
openid-connect-modrna-client-initiated-backchannel-authentication-1_0
OpenID Connect MODRNA Client initiated Backchannel Authentication Flow 1.0 is an authentication flow like OpenID Connect. Unlike OpenID Connect there is a direct Relying Party to OpenID Provider communication without redirects through the user's browser. This specification allows an Relying Party that knows the user's identitfier to obtain tokens from the OpenID Provider. The user consent is given at the user's Authentication Device mediated by the OpenID Provider.
OpenID Connect [OpenID.Core] allows Relying Parties (RP) to authenticate their users for clients of all types, including browser-based JavaScript and native mobile apps, to launch sign-in flows and receive verifiable assertions about the identity of signed-in users.
In all of these flows initiated by the RP, the end-user interaction from the consumption device is required and, they are based on HTTP redirection mechanisms. However, some use cases not covered by these flows have been raised, where the RP needs to be the initiator of the user authentication flow and the end-user interaction from the consumption device is not needed.
The MODRNA Client initiated Backchannel Authentication Flow specifies a new authentication flow, by means of which the RP's that know the user identifier they want to authenticate (e-mail, phone number), will be able to initiate an interaction flow to authenticate their users without having end-user interaction from the consumption device. The flow is a direct communication from the Client to the OpenID Provider without redirect through the user's browser (consumption device).
This specification does not change the semantic of the OpenID Connect Authentication flow. It introduces a new endpoint to which the authentication request is posted. It indroduces a new asynchronous method for authentication result delivery. It does no introduce new scope values nor does it change the semantic of standard OpenID Connect parameters. Some OpenID Connect parameters which are required in a redirect based protocol are meaningless in this server-to-server communication. A few new parameters are introduced e.g. those required for the asynchronous authentication result delivery.
Remark: As the user has no consumption device through which the user is interacting with the Client, this flow will not cause any user credentials to go through the RP. So it should be highlighted that traditional username/password authentication could not be used because only out-band mechanisms will work in conjunction with this flow.
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 "OpenID Provider (OP)" and "Relying Party (RP)" as defined by OpenID Connect Core [OpenID.Core]. Furthermore it uses the term "client" as defined by OAuth 2.0 [RFC6749]. OAuth 2.0 Authentication Servers implementing OpenID Connect and CIBA are also referred to as OpenID Providers (OPs). OAuth 2.0 Clients using OpenID Connect and CIBA are also referred to as Relying Parties (RPs). This specification also uses the following terms:
Client Initiated Backchannel Authentication (CIBA) enables a Client to initiate the authentication of an end-user by means of out-band mechanisms.
This specification allows the Client to get the authentication result in two ways: polling and notification.
If the Client expects to be notified about the authentication result asynchronously then it has to specify a Client Notification Endpoint during its registration at the OpenID Provider.
Otherwise the authentication response is retrieved by the Client by polling the OP's token endpoint using a new grant type.
CIBA polling is illustrated in the following diagram:
+--------+ +--------+ | | | | | |<---(1) CIBA Request-------------------------->| | | | | | | | +--------+ | | | | | | | | | Client | | AD |<--(2) User interactions --------->| OP | | | | | | | | | +--------+ | | | | | | | |----(3a) CIBA Polling Request----------------->| | | |<---(3b) CIBA Polling Response-----------------| | | | | | +--------+ +--------+
CIBA notification is illustrated in the following diagram:
+--------+ +--------+ | | | | | |<---(1) CIBA Request-------------------------->| | | | | | | | +--------+ | | | | | | | | | Client | | AD |<--(2) User interactions --------->| OP | | | | | | | | | +--------+ | | | | | | | |<---(3) CIBA Notification Callback ------------| | | | | | +--------+ +--------+
The following use cases are non-normative examples to illustrate the usage of this specification.
The Backchannel Authentication Endpoint performs Authentication of the End-User. This is done by sending an HTTP POST message directly from the Client to the OpenID Provider's Backchannel Authentication Endpoint, using request parameters defined by OAuth 2.0 and additional parameters and parameter values defined by OpenID Connect.
Communication with the Backchannel Authentication Endpoint MUST utilize TLS. See Section 16.17 [OpenID.Core] for more information on using TLS.
An Authentication Request uses most of the parameters of an OAuth 2.0 [RFC6749] Authorization Request. The parameters used are not changed in their meaning and no new values for those parameters are introduced. Some of an OAuth 2.0 Authorization Request parameters make no sense in a server to server communication and are therefore not part of a CIBA Authentication Request.
MODRNA Client initiated Backchannel Authentication defines an authentication request that is requested directly from the Client to the OpenID Provider without going through the user's browser. The Client MUST send an authentication request to the OpenID Provider by building an "HTTP POST" request that will take to the OpenID Provider all the information needed to authenticate the user without asking them for their identifier.
The Client MUST authenticate to the Backchannel Authentication Endpoint using the authentication method registered for its client_id, as described in Section 9 of [OpenID.Core].
Authentication Requests are made using OpenID Connect MODRNA Authentication Profile 1.0. Only the following parameters are taken into consideration in the Client initiated Backchannel Authentication flow. The rest of the request parameters defined in OAuth 2.0 [RFC6749] MUST be ignored by the OpenID Provider.
As the Client initiated Backchannel Authentication flow does not have an interaction with the end-user through a consumption device, it is REQUIRED that the Client provides one (and only one) of the hints specified above in the authentication request, that is "login_hint_token", "id_token_hint" or "login_hint".
The following is a non-normative example from an authentication request (with line wraps within values for display purposes only):
POST /bc-authorize HTTP/1.1 Host: server.example.com Authorization: Basic czZCaGRSa3F0MzpnWDFmQmF0M2JW Content-Type: application/json { "scope": "openid", "client_notification_token": "8d67dc78-7faa-4d41-aabd-67707b374255", "acr_values": "mod-mf", "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 OpenID Provider MUST validate the request received as follows:
As specified in OAuth 2.0 [RFC6749], OpenID Providers SHOULD ignore unrecognized request parameters.
If the OpenID Provider encounters any error, it MUST return an error response, per Section 3.1.2.6 of [OpenID.Core].
If the Authentication Request is validated as per Section Authentication Request Validation, the OpenID Provider will return an HTTP 200 OK response to the Client to indicate that the authentication request has been accepted and it is going to be processed. The body of this response will contain:
The following is a non-normative example from an authentication response
HTTP/1.1 200 OK Content-Type: application/json Cache-Control: no-store { "auth_req_id": "1c266114-a1be-4252-8ad1-04986c5b9ac1", "expires_in": 3600, "interval": 2 }
If the Client receives an HTTP 200 OK, it MUST validate that all the required parameters are received. The Client should keep the authentication request identifier auth_req_id in order to match it with token response.
The Client will have to keep the expiration time as well to be able to discard the authentication request acknowledgment.
After the OP has validated the Authentication Request and the OP identifies the user's Authentication Device. The OP chooses a channel to best contact the AD and fullfil the Client's requirements regarding acr_values.
Once the End-User is authenticated, the OpenID Provider MUST obtain an authorization decision before releasing information to the Client. As in OAuth2 and as in OpenID Connect the OP informs the user about the current Authentication Request e.g.: Which Client is requesting which information and which access.
When using the Client initiated Backchannel Authentication flow, there is not any interactive dialogue between the OpenID Provider and the end-user through the user's consumption device. There might be an agent of the Client involved who transfers the binding_message to the user.
The consent establishing only can take place via the authentication device or by establishing consent via conditions for processing the request or other means (for example, via previous administrative consent). Sections 2 and 5.3 of [OpenID.Core] describe information release mechanisms.
NOTE: the current version of the Client initiated Backchannel Authentication Flow spec. does not specify any mechanism to use the authentication device to obtain the end-user consent.
If the Client didn't register any callback URI for the "client_notification_endpoint" with the OpenID Provider, the Polling mode to get the token is set. The Client must poll the token endpoint until the end-user grants or denies the request.
The Client polls at reasonable interval which MUST NOT exceed the minimum interval provided by the OpenID Provider via the "interval" parameter (if provided).
The Client makes a "POST" request to the token endpoint by sending the following parameters using the "application/x-www-form-urlencoded" format with a character encoding of UTF-8 in the HTTP request entity-body:
The following is a non-normative example of a token request (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 Authorization: Basic czZCaGRSa3F0MzpnWDFmQmF0M2JW grant_type=urn%3Aopenid%3Aparams%3Amodrna%3Agrant-type%3Abackchannel_request &auth_req_id=1c266114-a1be-4252-8ad1-04986c5b9ac1
The OpenID Provider will return the token as an HTTP response to the Client's poll request. If the user is well authenticated, the OpenID Provider will return a succesful response that includes an ID Token and an Access Token. Otherwise it responses with an error as defined in Token Error Response.
The following is a non-normative example of a token response sending as an HTTP 200 OK Response to the Client's poll request (with line wraps within values for display purposes only).
HTTP/1.1 200 OK Content-Type: application/json Cache-Control: no-store { "access_token": "SlAV32hkKG", "token_type": "Bearer", "refresh_token": "8xLOxBtZp8", "expires_in": 3600, "id_token": "eyJhbGciOiJSUzI1NiIsImtpZCI6IjFlOWdkazcifQ.ewogImlzc yI6ICJodHRwOi8vc2VydmVyLmV4YW1wbGUuY29tIiwKICJzdWIiOiAiMjQ4Mjg5 NzYxMDAxIiwKICJhdWQiOiAiczZCaGRSa3F0MyIsCiAibm9uY2UiOiAibi0wUzZ fV3pBMk1qIiwKICJleHAiOiAxMzExMjgxOTcwLAogImlhdCI6IDEzMTEyODA5Nz AKfQ.ggW8hZ1EuVLuxNuuIJKX_V8a_OMXzR0EHR9R6jgdqrOOF4daGU96Sr_P6q Jp6IcmD3HP99Obi1PRs-cwh3LO-p146waJ8IhehcwL7F09JdijmBqkvPeB2T9CJ NqeGpe-gccMg4vfKjkM8FcGvnzZUN4_KSP0aAp1tOJ1zZwgjxqGByKHiOtX7Tpd QyHE5lcMiKPXfEIQILVq0pc_E2DzL7emopWoaoZTF_m0_N0YzFC6g6EJbOEoRoS K5hoDalrcvRYLSrQAZZKflyuVCyixEoV9GfNQC3_osjzw2PAithfubEEBLuVVk4 XUVrWOLrLl0nx7RkKU8NXNHq-rvKMzqg" }
If the Client is registered for Client notifications (Notification mode), the OpenID Provider will send the token response making a "POST HTTP Request" to the Client's client_notification_endpoint. If the user is well authenticated, the OpenID Provider returns a successful response that includes an ID Token and an Access Token and a Refresh Token. If the request failed Client authentication or is invalid, the OpenID Provider sends an error_message as described in Token Error Response.
All the parameters in the successful response are defined in Section 4.1.4 of OAuth 2.0 [RFC6749] except the new one "auth_req_id" that will be the same received in the request as defined in Successful Authentication Response [successful_authentication_request_acknowdlegment]. The response uses the application/json media type.
The following is a non-normative example of a token response sending as a HTTP POST request to the callback uri specified in the "client_notification_endpoint" parameter by the Client (with line wraps within values for display purposes only). The request is authenticated through a bearer token that is the value of the "client_notification_token" provided by the Client in the Authentication Request.
POST /cb HTTP/1.1 Host: client.example.com Authorization: Bearer 8d67dc78-7faa-4d41-aabd-67707b374255 Content-Type: application/json { "auth_req_id": "1c266114-a1be-4252-8ad1-04986c5b9ac1", "access_token": "SlAV32hkKG", "token_type": "Bearer", "refresh_token": "8xLOxBtZp8", "expires_in": 3600, "id_token": "eyJhbGciOiJSUzI1NiIsImtpZCI6IjFlOWdkazcifQ.ewogImlzc yI6ICJodHRwOi8vc2VydmVyLmV4YW1wbGUuY29tIiwKICJzdWIiOiAiMjQ4Mjg5 NzYxMDAxIiwKICJhdWQiOiAiczZCaGRSa3F0MyIsCiAibm9uY2UiOiAibi0wUzZ fV3pBMk1qIiwKICJleHAiOiAxMzExMjgxOTcwLAogImlhdCI6IDEzMTEyODA5Nz AKfQ.ggW8hZ1EuVLuxNuuIJKX_V8a_OMXzR0EHR9R6jgdqrOOF4daGU96Sr_P6q Jp6IcmD3HP99Obi1PRs-cwh3LO-p146waJ8IhehcwL7F09JdijmBqkvPeB2T9CJ NqeGpe-gccMg4vfKjkM8FcGvnzZUN4_KSP0aAp1tOJ1zZwgjxqGByKHiOtX7Tpd QyHE5lcMiKPXfEIQILVq0pc_E2DzL7emopWoaoZTF_m0_N0YzFC6g6EJbOEoRoS K5hoDalrcvRYLSrQAZZKflyuVCyixEoV9GfNQC3_osjzw2PAithfubEEBLuVVk4 XUVrWOLrLl0nx7RkKU8NXNHq-rvKMzqg" }
The Client Notification Endpoint is set by the Client during the registration phase. This endpoint is intended to receive the result of the authentication (id_token, access_token and refresh token) and it requires the request to be authenticated using a "bearer token" created by the Client and sent to the OP in the Authentication request as the value of the parameter "client_notification_token".
Communication with the Client Notification Authentication Endpoint MUST utilize TLS. See Section 16.17 [OpenID.Core] for more information on using TLS.
If the Token Request is invalid or unauthorized, the OpenID Provider constructs the error response according to the section 3.1.3.4 Token Error Response of [OpenID.Core]. In addition to the error codes defined in Section 5.2 of [RFC6749], the following error codes are specific for the Client Initiated Backchannel flow:
An Authentication Error Response is an OAuth 2.0 Authorization Error Response message returned from the OP's Authorization Endpoint in response to the Authorization Request message sent by the Client.
If the End-User denies the request or the End-User authentication fails, the OP (Authorization Server) informs the Client by using the follow Error Responses, many of them are defined in Section 4.1.2.1 of OAuth 2.0 [RFC6749], however they cannot be sent using a redirection as OAuth 2.0 does because there isn't any User Agent through which send the error to the Client.
Errors will be sent directly to the client as HTTP Error Responses, whose body will contain a json with two parameters
List of authentication error codes associated to a HTTP Errors.
The following is a non-normative example from an authentication error response:
HTTP/1.1 403 Forbidden Content-Type: application/json { "error": "unauthorized_client", "error_description": "The client 'client.example.org' is not allowed to use Client Backchannel Authentication." }
The login hint token SHOULD be digitally signed by the issuer. This ensures authenticity of the data and reduces the threat of an injection attack. The signature allows the OP to authenicate and authorize the sender of the hint and prevent collecting of phone numbers by rogue Clients.
The OP SHOULD ensure that the "client_notification_endpoint" configured at registration time is in the administrativ authority of the Client. Otherwise the OP would post authentication results to the wrong Client.
How this check in done is outside the scope of this specification.
Using MODRNA Client initiated Backchannel Authentication it is possible for the Client to authenticate a user without knowing e.g. the MSISDN of the user. Users might be reluctant to provide their MSISDN to Clients because they fear misuse through automated calls or theirs number being leaked. The login hint token is encrypted in order to protect the user's MSISDN from being revealed to the Client unintentionally.
[I-D.ietf-oauth-amr-values] | Jones, M., Hunt, P. and A. Nadalin, "Authentication Method Reference Values", Internet-Draft draft-ietf-oauth-amr-values-06, February 2017. |
[MODRNA.Authentication] | Connotte, J. and J. Bradley, "OpenID Connect MODRNA Authentication Profile 1.0", March 2017. |
[OpenID.Core] | Sakimura, N., Bradley, J., Jones, M., de Medeiros, B. and C. Mortimore, "OpenID Connect Core 1.0", August 2015. |
[RFC2119] | Bradner, S., "Key words for use in RFCs to Indicate Requirement Levels", BCP 14, RFC 2119, DOI 10.17487/RFC2119, March 1997. |
[RFC3986] | Berners-Lee, T., Fielding, R. and L. Masinter, "Uniform Resource Identifier (URI): Generic Syntax", STD 66, RFC 3986, DOI 10.17487/RFC3986, January 2005. |
[RFC6749] | Hardt, D., "The OAuth 2.0 Authorization Framework", RFC 6749, DOI 10.17487/RFC6749, October 2012. |
The following have contributed to the development of this specification.
Copyright (c) 2017 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