| G. Fernandez | |
| Telefonica | |
| F. Walter | |
| A. Nennker | |
| Deutsche Telekom AG | |
| D. Tonge | |
| Moneyhub | |
| B. Campbell | |
| Ping Identity | |
| January 16, 2019 |
OpenID Connect Client Initiated Backchannel Authentication Flow - Core 1.0 draft-02
openid-client-initiated-backchannel-authentication-core-02
OpenID Connect Client Initiated Backchannel Authentication Flow is an authentication flow like OpenID Connect. However, unlike OpenID Connect, there is direct Relying Party to OpenID Provider communication without redirects through the user's browser. This specification allows a Relying Party that knows the user's identifier 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 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 end-user interaction from the consumption device is not needed.
Client Initiated Backchannel Authentication (CIBA) is a new authentication flow in which RPs, that can obtain a valid identifier for the user they want to authenticate, will be able to initiate an interaction flow to authenticate their users without having end-user interaction from the consumption device. The flow involves direct communication from the Client to the OpenID Provider without redirect through the user's browser (consumption device).
This specification does not change the semantics of the OpenID Connect Authentication flow. It introduces a new endpoint to which the authentication request is posted. It introduces a new asynchronous method for authentication result notification or delivery. It does not introduce new scope values nor does it change the semantics of standard OpenID Connect parameters.
As the user does not provide authentication credentials directly to the consumption device, supporting this flow requires the to OP have some mechanism of initiating user authentication out-of-band from the interaction with the consumption device.
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. Furthermore, it uses the term "Client" as defined by OAuth 2.0. OAuth 2.0 Authorization 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-of-band mechanisms.
The following is a non-normative example from a dynamic registration request that contains the CIBA grant type as required and a "jwks_uri" (with line wraps within values for display purposes only).
POST /connect/register HTTP/1.1
Content-Type: application/json
Accept: application/json
Host: server.example.com
Authorization: Bearer eyJhbGciOiJSUzI1NiJ9.eyJ ...
{
"application_type": "web",
"client_name": "My Example",
"logo_uri": "https://client.example.org/logo.png",
"subject_type": "pairwise",
"token_endpoint_auth_method": "private_key_jwt",
"grant_types": ["urn:openid:params:grant-type:ciba"],
"backchannel_token_delivery_mode": "poll",
"jwks_uri": "https://client.example.org/my_public_keys.jwks",
"userinfo_encrypted_response_alg": "RSA1_5",
"userinfo_encrypted_response_enc": "A128CBC-HS256",
"contacts": ["ve7jtb@example.org", "mary@example.org"]
}
This specification allows the Client to get the authentication result in three ways: poll, ping or push.
In the Poll mode, the authentication result is retrieved by the Client by polling the OP's token endpoint using the new grant type.
In the Ping mode, the OP will post the unique identifier of the authentication session to the Client, the Client will then retrieve the authentication result from the token endpoint using the new grant type.
In the Push mode, the OP will post the full authentication result to the Client.
CIBA Poll Mode is illustrated in the following diagram:
+--------+ +--------+
| | | |
| |<---(1) CIBA Request-------------------------->| |
| | | |
| | +--------+ | |
| | | | | |
| Client | | AD |<--(2) User interactions---------->| OP |
| | | | | |
| | +--------+ | |
| | | |
| |----(3a) CIBA Polling Request----------------->| |
| |<---(3b) CIBA Polling Response-----------------| |
| | ... | |
| |----(3a) CIBA Polling Request----------------->| |
| |<---(3b) CIBA Polling Response-----------------| |
| | | |
+--------+ +--------+
CIBA Ping Mode is illustrated in the following diagram:
+--------+ +--------+
| | | |
| |<---(1) CIBA Request-------------------------->| |
| | | |
| | +--------+ | |
| | | | | |
| Client | | AD |<--(2) User interactions---------->| OP |
| | | | | |
| | +--------+ | |
| | | |
| |<---(3) CIBA Ping Callback---------------------| |
| | | |
| |----(4a) CIBA Token Request------------------->| |
| |<---(4b) CIBA Token Response-------------------| |
+--------+ +--------+
CIBA Push Mode is illustrated in the following diagram:
+--------+ +--------+
| | | |
| |<---(1) CIBA Request-------------------------->| |
| | | |
| | +--------+ | |
| | | | | |
| Client | | AD |<--(2) User interactions---------->| OP |
| | | | | |
| | +--------+ | |
| | | |
| |<---(3) CIBA Push Callback---------------------| |
| | | |
+--------+ +--------+
The following use cases are non-normative examples to illustrate the usage of this specification.
The Backchannel Authentication Endpoint is used to initiate an out-of-band 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 a request defined in the following subsections.
Communication with the Backchannel Authentication Endpoint MUST utilize TLS. See Section 16.17 [OpenID.Core] for more information on using TLS.
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, such as the authentication methods from Section 9 of [OpenID.Core] or authentication methods defined by extension in other specifications.
An authentication request is composed of the following parameters and MAY contain additional parameters defined by extension or profile:
As in the CIBA flow the OP does not have an interaction with the end-user through the 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".
An authentication request is made using the HTTP POST method with the aforementioned parameters in the application/x-www-form-urlencoded format and a character encoding of UTF-8 in the HTTP request entity-body. When applicable, additional parameters required by the given client authentication method are also included (e.g. JWT assertion based client authentication uses client_assertion and client_assertion_type while Mutual TLS client authentication uses client_id).
The following is a non-normative example of 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/x-www-form-urlencoded
scope=openid%20email%20example-scope&
client_notification_token=8d67dc78-7faa-4d41-aabd-67707b374255&
binding_message=W4SCT&
login_hint_token=eyJraWQiOiJsdGFjZXNidyIsImFsZyI6IlJTMjU2In0.eyJ
zdWJqZWN0Ijp7InN1YmplY3RfdHlwZSI6InBob25lIiwicGhvbmUiOiIrMTMzMDI
4MTgwMDQifX0.YB8_8OksJd1FwfVsIUlH-rs9cPhkIa0DUi7OVW_Da9gP6huBxf7
aSDl3qKXA20uT1zThuSiYz0bdz8J_KPRHuC6vwoFlz9yBJ9ksWOP28sHPPi19_4-
xidwnb8P12-RoXwY2eAF82_NAn2vmpvqUjluoWyNHay8vguChIutqziV0bFl-7oa
xp36i4elbvT_DYeg20a0jz4wIBKc_46K8I28ErkwbI5O35GfElPXl-4J55NHkkOs
DxuUYQtWjSM3wme19735XWq2DIT2nmLFi4HzzT27W0cnJg7L_ai9uNNBvIx_Mp5A
bcmkR83apR4jxnQuE5Xf23qyRpAhawe7IPQ
A signed authentication request is made by encoding all of the authentication request parameters as claims of a signed JWT, with each parameter name as the claim name and its value as a JSON string. The JWT MUST contain all of the authentication request parameters. The JWT MUST be secured with an asymmetric signature and follow the guidance from Section 10.1 of [OpenID.Core] regarding asymmetric signatures. The JWT MUST also contain the following [RFC7519] registered claims:
The signed authentication request JWT is passed as an application/x-www-form-urlencoded HTTP request parameter with the name request. Authentication request parameters MUST NOT be present outside of the JWT, in particular they MUST NOT appear as HTTP request parameters. Additional HTTP request parameters as required by the given client authentication method, however, MUST be included as application/x-www-form-urlencoded parameters (e.g. Mutual TLS client authentication uses client_id while JWT assertion based client authentication uses client_assertion and client_assertion_type).
For example, a signed authentication request using the same authentication request parameters and values as the example from the previous section would look like the following (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/x-www-form-urlencoded
request=eyJraWQiOiJsdGFjZXNidyIsImFsZyI6IlJTMjU2In0.eyJpc3MiOiJz
NkJoZFJrcXQzIiwiYXVkIjoiaHR0cHM6Ly9zZXJ2ZXIuZXhhbXBsZS5jb20iLCJl
eHAiOjE1Mzc4MjAwODYsImlhdCI6MTUzNzgxOTQ4NiwibmJmIjoxNTM3ODE4ODg2
LCJqdGkiOiI0TFRDcUFDQzJFU0M1QldDbk4zajU4RW5BIiwic2NvcGUiOiJvcGVu
aWQgZW1haWwgZXhhbXBsZS1zY29wZSIsImNsaWVudF9ub3RpZmljYXRpb25fdG9r
ZW4iOiI4ZDY3ZGM3OC03ZmFhLTRkNDEtYWFiZC02NzcwN2IzNzQyNTUiLCJiaW5k
aW5nX21lc3NhZ2UiOiJXNFNDVCIsImxvZ2luX2hpbnRfdG9rZW4iOiJleUpyYVdR
aU9pSnNkR0ZqWlhOaWR5SXNJbUZzWnlJNklsSlRNalUySW4wLmV5SnpkV0pxWldO
MElqcDdJbk4xWW1wbFkzUmZkSGx3WlNJNkluQm9iMjVsSWl3aWNHaHZibVVpT2lJ
ck1UTXpNREk0TVRnd01EUWlmWDAuWUI4XzhPa3NKZDFGd2ZWc0lVbEgtcnM5Y1Bo
a0lhMERVaTdPVldfRGE5Z1A2aHVCeGY3YVNEbDNxS1hBMjB1VDF6VGh1U2lZejBi
ZHo4Sl9LUFJIdUM2dndvRmx6OXlCSjlrc1dPUDI4c0hQUGkxOV80LXhpZHduYjhQ
MTItUm9Yd1kyZUFGODJfTkFuMnZtcHZxVWpsdW9XeU5IYXk4dmd1Q2hJdXRxemlW
MGJGbC03b2F4cDM2aTRlbGJ2VF9EWWVnMjBhMGp6NHdJQktjXzQ2SzhJMjhFcmt3
Ykk1TzM1R2ZFbFBYbC00SjU1Tkhra09zRHh1VVlRdFdqU00zd21lMTk3MzVYV3Ey
RElUMm5tTEZpNEh6elQyN1cwY25KZzdMX2FpOXVOTkJ2SXhfTXA1QWJjbWtSODNh
cFI0anhuUXVFNVhmMjNxeVJwQWhhd2U3SVBRIn0.IBuxW3F_L9tj9f6fGC7FnVsH
9B9RoJYA8QyxtnxgOgMc1kcnufyGxdtd7lU1TjPCVNsbkR0vfGasCmoMYSMohPOb
nwAlkm8Yf0uglhxM83B0dj_I10vwlMGnVFvydaH9wnacM4Ln7E-JIYOxtZa33abf
1PB3fLs29GKOBmgNPn3NrxJ0iCLb0F243556Ypzdhcyj7vM8ukNzkKT3eQ0ZWJ1v
VRToThgKyIN-HvLFpeSfJtSH5ycMYOjob-qXUgKpQryUbgbpqsM1XnUV-8aBD5d8
VF5fQoz0PQWq63B_zpC22nstIFxNmfxztSFpnW0vgX0htNKOtL_HMwFRfwh71g
Where the following is the JWT payload (with line wraps and added whitespace for display purposes only):
{
"iss": "s6BhdRkqt3",
"aud": "https://server.example.com",
"exp": 1537820086,
"iat": 1537819486,
"nbf": 1537818886,
"jti": "4LTCqACC2ESC5BWCnN3j58EnA",
"scope": "openid email example-scope",
"client_notification_token": "8d67dc78-7faa-4d41-aabd-67707b374255",
"binding_message": "W4SCT",
"login_hint_token": "eyJraWQiOiJsdGFjZXNidyIsImFsZyI6IlJTMjU2I
n0.eyJzdWJqZWN0Ijp7InN1YmplY3RfdHlwZSI6InBob25lIiwicGhvbmUiO
iIrMTMzMDI4MTgwMDQifX0.YB8_8OksJd1FwfVsIUlH-rs9cPhkIa0DUi7OV
W_Da9gP6huBxf7aSDl3qKXA20uT1zThuSiYz0bdz8J_KPRHuC6vwoFlz9yBJ
9ksWOP28sHPPi19_4-xidwnb8P12-RoXwY2eAF82_NAn2vmpvqUjluoWyNHa
y8vguChIutqziV0bFl-7oaxp36i4elbvT_DYeg20a0jz4wIBKc_46K8I28Er
kwbI5O35GfElPXl-4J55NHkkOsDxuUYQtWjSM3wme19735XWq2DIT2nmLFi4
HzzT27W0cnJg7L_ai9uNNBvIx_Mp5AbcmkR83apR4jxnQuE5Xf23qyRpAhaw
e7IPQ"
}
Note that encrypted JWT authentication requests are not supported.
User code is a mechanism to prevent unsolicited authentication requests from appearing on a user's authentication device.
It is optional for the OP to implement user code functionality. If the OP implements user code functionality then it may allow 1) clients without user code and 2) users without user code.
Typically clients that establish a security context with the user prior to sending a CIBA request should be allowed without user code. Example use cases of client security context are web applications that use CIBA for step-up authentication or call center applications where a caller ID is used to identify the user.
The OP declares support for user code with the provider metadata parameter backchannel_user_code_parameter_supported.
The Client registration parameter backchannel_user_code_parameter specifies if support for user code is required from the Client.
A client may detect users who require a user code from the authentication request error code. For example a client may first attempt an authentication request without a user code, and only prompt for a user code if it receives the error code missing_user_code.
The Client MUST NOT store the user code, but should rather request it from the user for each CIBA flow.
Registering a user code for a user is not in scope of this specification. Examples include a facility provided by the authentication device, SMS text messages or other service provided by the OP. OPs should provide a method for the user to change the user code.
The OpenID Provider MUST validate the request received as follows:
OpenID Providers SHOULD ignore unrecognized request parameters.
If the OpenID Provider encounters any error, it MUST return an error response, per Section 13.
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 of 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 MUST keep the auth_req_id in order to validate the callbacks received in Ping and Push modes or to use when making a token request in Poll and Ping modes.
The Client should store the expiration time in order to clean up authentication requests for which no Ping Callback or Push Callback is received.
After the OP has validated the Authentication Request, the OP identifies the user and chooses a channel to best authenticate the user and authorize the request, in line with the Client's requests regarding acr_values. Typically this involves the OP initiating an interactive session on the user's authentication device.
Once the end-user is authenticated, the OpenID Provider MUST obtain an authorization decision as described in Section 3.1.2.4 of [OpenID.Core].
When using the Client Initiated Backchannel Authentication flow, there is no 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 Client Notification Endpoint is set by the Client during Registration and Discovery Metadata. It is the endpoint the OP will call after a successful or failed end-user authentication.
It MUST be an HTTPS URL and Communication with the Client Notification Endpoint MUST utilize TLS. See Section 16.17 [OpenID.Core] for more information on using TLS.
When the Client is configured in Ping mode, the endpoint receives a notification from the OP that an Authentication Result is ready to be retrieved from the Token Endpoint.
When the Client is configured in Push mode, the endpoint receives the Authentication Result (an ID Token, an Access Token and, optionally, a Refresh Token or in the event that the user did not grant authorization, an error).
Requests to the Client Notification Endpoint must 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".
The token delivery mode for the Client (Poll, Ping or Push) is determined at registration time.
A Client can only register a single token delivery method and the OP MUST only deliver the Authentication Result to the Client through the registered mode.
If the Client is registered to use Poll or Ping modes, the Client will retrieve the Authentication Result from the token endpoint.
The Client MUST be authenticated as specified in Section 9 of [OpenID.Core].
If the Client is registered to use the Poll mode, then the Client polls the token endpoint at reasonable interval, which MUST NOT be more frequent than the minimum interval provided by the OpenID Provider via the "interval" parameter (if provided).
If the Client is registered to use the Ping mode, then when the Client receives a notification to its Client Notification Endpoint containing an auth_req_id that is verified against a client_notification_token, it must call the token endpoint to retrieve the authentication result.
NOTE: A Client configured in Ping mode may also poll the token endpoint. The OpenID Provider must treat such a Client as if it had been registered to use the Poll mode.
The Client makes an "HTTP 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%3Agrant-type%3Aciba
&auth_req_id=1c266114-a1be-4252-8ad1-04986c5b9ac1
After receiving and validating a valid and authorized Token Request from the Client and when the end-user associated with the supplied auth_req_id has been authenticated and has authorized the request, the OpenID Provider returns a successful response as specified in Section 3.1.3.3 of [OpenID.Core]. If the end-user associated with the supplied auth_req_id has not been authenticated or has not authorized the request, an error response must be sent as defined in Token Error Response.
The following is a non-normative example of a successful token response (with line wraps within values for display purposes only).
HTTP/1.1 200 OK
Content-Type: application/json
Cache-Control: no-store
{
"access_token": "G5kXH2wHvUra0sHlDy1iTkDJgsgUO1bN",
"token_type": "Bearer",
"refresh_token": "4bwc0ESC_IAhflf-ACC_vjD_ltc11ne-8gFPfA2Kx16",
"expires_in": 3600,
"id_token": "eyJhbGciOiJSUzI1NiIsImtpZCI6IjE2NzcyNiJ9.eyJpc3MiOiJo
dHRwczovL3NlcnZlci5leGFtcGxlLmNvbSIsInN1YiI6IjI0ODI4OTc2MTAwMSIs
ImF1ZCI6InM2QmhkUmtxdDMiLCJlbWFpbCI6ImphbmVkb2VAZXhhbXBsZS5jb20i
LCJleHAiOjE1Mzc4MTk4MDMsImlhdCI6MTUzNzgxOTUwM30.aVq83mdy72ddIFVJ
LjlNBX-5JHbjmwK-Sn9Mir-blesfYMceIOw6u4GOrO_ZroDnnbJXNKWAg_dxVynv
MHnk3uJc46feaRIL4zfHf6Anbf5_TbgMaVO8iczD16A5gNjSD7yenT5fslrrW-NU
_vtmi0s1puoM4EmSaPXCR19vRJyWuStJiRHK5yc3BtBlQ2xwxH1iNP49rGAQe_LH
fW1G74NY5DaPv-V23JXDNEIUTY-jT-NbbtNHAxnhNPyn8kcO2WOoeIwANO9BfLF1
EFWtjGPPMj6kDVrikec47yK86HArGvsIIwk1uExynJIv_tgZGE0eZI7MtVb2UlCw
DQrVlg"
}
If the Client is registered in Ping mode, the OpenID Provider will send an HTTP POST Request to the Client Notification Endpoint after a successful or failed end-user authentication.
In this mode the OP sends the client_notification_token as a bearer token in the Authorization header field and sends only the auth_req_id in the body of the request. The request uses the application/json media type.
The following is a non-normative example of a Ping callback sent as an HTTP POST request to the Client's Notification Endpoint (with line wraps within values for display purposes only).
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"
}
The Client MUST verify the client_notification_token used to authenticate the request is valid and is associated with the auth_req_id received in the Ping callback. If the bearer token is not valid, the Client SHOULD return an HTTP 401 Unauthorized response.
For valid requests, the Client Notification Endpoint SHOULD respond with an HTTP 204 No Content. The OP SHOULD also accept responses with HTTP 200 OK and any body in the response SHOULD be ignored.
The Client MUST NOT return an HTTP 3xx code. The OP MUST NOT follow redirects.
How the OP handles HTTP error codes in the ranges of 4xx and 5xx is out-of-scope of this specification. Administrative action is likely to be needed in these cases.
For valid requests, the Client can now use the received auth_req_id to make a Token Request using the CIBA Grant Type to the Token Endpoint as described in Token Request Using CIBA Grant Type.
If the Client is registered in Push mode and the user is well authenticated and has authorized the request, the OpenID Provider delivers a payload that includes an ID Token, an Access Token and, optionally, a Refresh Token to the Client Notification Endpoint.
Error conditions associated with the authentication request are delivered to the Client by sending a Push Error Payload to the Client Notification Endpoint.
The Push Callback uses the parameters defined for a successful token response in Section 4.1.4 of OAuth 2.0 and Section 3.1.3.3 of [OpenID.Core]. In addition a new parameter "auth_req_id" is included in the payload. This is the authentication request identifier as defined in Successful Authentication Response.
The Push Callback uses the application/json media type.
In order to bind together the ID Token, the Access Token and the auth_req_id, the OP MUST include the hash value of the Access Token and the auth_req_id within the ID Token using the at_hash and urn:openid:params:jwt:claim:auth_req_id claims respectively. In case a Refresh Token is sent to the Client, the hash value of it MUST also be added to the ID token using the urn:openid:params:jwt:claim:rt_hash claim. Section 3.1.3.6 of [OpenID.Core] shows how to calculate the hash value of the access_token for at_hash, the same method can also be applied to calculate the Refresh Token hash value. Note that these claims are only required in Push mode.
The following is a non-normative example of a Push Callback sent as an HTTP POST request to the Client's notification endpoint (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": "G5kXH2wHvUra0sHlDy1iTkDJgsgUO1bN",
"token_type": "Bearer",
"refresh_token": "4bwc0ESC_IAhflf-ACC_vjD_ltc11ne-8gFPfA2Kx16",
"expires_in": 3600,
"id_token": "eyJhbGciOiJSUzI1NiIsImtpZCI6IjE2NzcyNiJ9.eyJpc3MiOiJ
odHRwczovL3NlcnZlci5leGFtcGxlLmNvbSIsInN1YiI6IjI0ODI4OTc2MTAwMS
IsImF1ZCI6InM2QmhkUmtxdDMiLCJlbWFpbCI6ImphbmVkb2VAZXhhbXBsZS5jb
20iLCJleHAiOjE1Mzc4MTk4MDMsImlhdCI6MTUzNzgxOTUwMywiYXRfaGFzaCI6
Ild0MGtWRlhNYWNxdm5IZXlVMDAwMXciLCJ1cm46b3BlbmlkOnBhcmFtczpqd3Q
6Y2xhaW06cnRfaGFzaCI6InNIYWhDdVNwWENSZzVta0REdnZyNHciLCJ1cm46b3
BlbmlkOnBhcmFtczpqd3Q6Y2xhaW06YXV0aF9yZXFfaWQiOiIxYzI2NjExNC1hM
WJlLTQyNTItOGFkMS0wNDk4NmM1YjlhYzEifQ.SGB5_a8E7GjwtoYrkFyqOhLK6
L8-Wh1nLeREwWj30gNYOZW_ZB2mOeQ5yiXqeKJeNpDPssGUrNo-3N-CqNrbmVCb
XYTwmNB7IvwE6ZPRcfxFV22oou-NS4-3rEa2ghG44Fi9D9fVURwxrRqgyezeD3H
HVIFUnCxHUou3OOpj6aOgDqKI4Xl2xJ0-kKAxNR8LljUp64OHgoS-UO3qyfOwIk
IAR7o4OTK_3Oy78rJNT0Y0RebAWyA81UDCSf_gWVBp-EUTI5CdZ1_odYhwB9OWD
W1A22Sf6rmjhMHGbQW4A9Z822yiZZveuT_AFZ2hi7yNp8iFPZ8fgPQJ5pPpjA7u
dg"
}
The Client MUST verify the client_notification_token used to authenticate the request is valid and is associated with the auth_req_id received in the Push Callback. If the bearer token is not valid the Client SHOULD return an HTTP 401 Unauthorized response.
The Client MUST validate the ID Token, which acts as a detached signature, as per Section 3.1.3.7 of [OpenID.Core].
The Client MUST ensure that the value of the urn:openid:params:jwt:claim:auth_req_id claim in the ID Token matches the auth_req_id in the request.
The Client MUST validate the access token received using the at_hash in the ID Token as per Section 3.2.2.9 of [OpenID.Core]. If a refresh token is present, the Client MUST validate it using the urn:openid:params:jwt:claim:rt_hash in the ID Token in a similar manner as the access token is validated.
For valid requests, the Client Notification Endpoint SHOULD respond with an HTTP 204 No Content. The OP SHOULD also accept HTTP 200 OK and any body in the response SHOULD be ignored.
The Client MUST NOT return an HTTP 3xx code. The OP MUST NOT follow redirects.
How the OP handles HTTP error codes in the ranges of 4xx and 5xx is out-of-scope of this specification. Administrative action is likely to be needed in these cases.
The following is a non-normative example of a base64url decoded ID Token sent to the client notification endpoint:
{
"iss": "https://server.example.com",
"sub": "248289761001",
"aud": "s6BhdRkqt3",
"email": "janedoe@example.com",
"exp": 1537819803,
"iat": 1537819503,
"at_hash": "Wt0kVFXMacqvnHeyU0001w",
"urn:openid:params:jwt:claim:rt_hash": "sHahCuSpXCRg5mkDDvvr4w",
"urn:openid:params:jwt:claim:auth_req_id":
"1c266114-a1be-4252-8ad1-04986c5b9ac1"
}
If the Token Request is invalid or unauthorized, the OpenID Provider constructs an error response according to 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 defined in the OAuth Device Flow are also applicable:
If the auth_req_id is invalid or was issued to another Client, an invalid_grant error MUST be returned as described in Section 5.2 of [RFC6749].
If the Client is registered to use the Push Mode then it MUST NOT call the Token Endpoint with the CIBA Grant Type and the following error is returned.
When Clients are configured to use the Push token delivery mode they can receive error payloads at their Client Notification Endpoint. These errors will be sent using the application/json media type with the following three parameters:
Error codes applicable to the push error payload:
An Authentication Error Response is returned directly from the Backchannel Authentication Endpoint in response to the Authentication Request sent by the Client. The applicable error codes are detailed below (some of which are repurposed from OAuth 2.0 Sections 4.1.2.1 and 5.2).
Authentication Error Responses are sent in the same format as Token Error Responses, i.e. the HTTP response body uses the application/json media type with the following parameters:
List of authentication error codes associated to HTTP Errors.
The following is a non-normative example from an authentication error response:
HTTP/1.1 400 Bad Request
Content-Type: application/json
{
"error": "unauthorized_client",
"error_description":
"The client 'client.example.org' is not allowed to use CIBA."
}
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 authenticate and authorize the sender of the hint and prevent collecting of user identifiers by rogue Clients.
The OP SHOULD ensure that the "backchannel_client_notification_endpoint" configured at registration time is in the administrative authority of the Client. Otherwise, the OP would post authentication results to the wrong Client. How this check is done is outside the scope of this specification.
An id_token_hint cannot be validated using standard JWT processing rules because the token is being used in a context (sent from the Client back to the OP) that is different than that for which it was originally issued (typically a short lived token issued by the OP intended to convey claims about the authentication of an end-user to the Client). An expired ID Token therefore could still be considered valid as an id_token_hint so an OP should, for some reasonable period, accept id_token_hints with an expiration time that has passed. The OP should ensure that it is the issuer of the token and that the Client presenting the id_token_hint is listed in the audience claim. The OP should verify the signature to ensure that the token was, in fact, issued by it and hasn't been modified since. Note that due to key rotation, however, the OP may not necessarily have access to the key used to sign the token, so the length of time an ID Token is considered a valid hint will be likely to be limited by the OP's key rotation interval and retention period. Given these restrictions, implementers may consider not verifying the signature at all and only accepting ID Tokens with pairwise subject identifiers as hints. The OP could then validate that the Client authenticated at the Backchannel Authentication Endpoint was issued the pairwise subject identifier (or shares a Sector Identifier with the Client who was issued the pairwise subject identifier).
This specification defines a method of token delivery, "Push Callback", which differs from standard OAuth 2.0 flows. Most OAuth 2.0 and OpenID Connect profiles require the Client to authenticate at the token endpoint in order to retrieve access tokens, ID Tokens and refresh tokens. However with the CIBA Push mode, tokens are delivered directly to the Client at its Client Notification Endpoint. Implementers should ensure that appropriate security controls are in place for this endpoint and its registration with the OP. CIBA requires that a hash of the access token, a hash of the refresh token and the auth_req_id itself are included in the ID Token when the Push mode is used. This allows the Client to verify that the values in the Push Callback have not been tampered with.
This flow requires the Client to obtain an identifier for the end-user. When this identifier is a static global identifier, such as a phone number or email address, there are clear privacy implications. However this flow does not require the use of such identifiers and in deployments with higher privacy requirements, alternative identifiers could be used, such as:
This specification requests registration of the following values in the IANA "OAuth Authorization Server Metadata" registry of [IANA.OAuth.Parameters] established by [RFC8414].
This specification requests registration of the following client metadata definitions in the IANA "OAuth Dynamic Client Registration Metadata" registry of [IANA.OAuth.Parameters] established by [RFC7591]:
This specification requests registration of the following value in the IANA "OAuth Parameters" registry of [IANA.OAuth.Parameters] established by [RFC6749].
This specification makes no request of IANA with respect to the "JSON Web Token Claims" registry at [IANA.JWT] established by [RFC7519]. Public Claim Names where used for the auth_req_id and refresh token hash in the ID Token in Section 10.3.1 in order to avoid further congestion of the registry with application specific claims that are unlikely to be of general applicability. For a Signed Authentication Request, where the the authentication request parameters are encoded as claims of the request JWT, the context of use is sufficiently constrained so as to safely consider those to be Private Claim Names.
| [I-D.ietf-oauth-mtls] | Campbell, B., Bradley, J., Sakimura, N. and T. Lodderstedt, "OAuth 2.0 Mutual TLS Client Authentication and Certificate Bound Access Tokens", Internet-Draft draft-ietf-oauth-mtls-12, October 2018. |
| [OpenID.Core] | Sakimura, N., Bradley, J., Jones, M., de Medeiros, B. and C. Mortimore, "OpenID Connect Core 1.0", November 2014. |
| [OpenID.Registration] | Sakimura, N., Bradley, J. and M. Jones, "OpenID Connect Dynamic Client Registration 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. |
| [RFC6750] | Jones, M. and D. Hardt, "The OAuth 2.0 Authorization Framework: Bearer Token Usage", RFC 6750, DOI 10.17487/RFC6750, October 2012. |
| [RFC7519] | Jones, M., Bradley, J. and N. Sakimura, "JSON Web Token (JWT)", RFC 7519, DOI 10.17487/RFC7519, May 2015. |
| [I-D.ietf-oauth-device-flow] | Denniss, W., Bradley, J., Jones, M. and H. Tschofenig, "OAuth 2.0 Device Flow for Browserless and Input Constrained Devices", Internet-Draft draft-ietf-oauth-device-flow-13, October 2018. |
| [IANA.JWT] | IANA, "JSON Web Token (JWT)" |
| [IANA.OAuth.Parameters] | IANA, "OAuth Parameters" |
| [RFC6749] | Hardt, D., "The OAuth 2.0 Authorization Framework", RFC 6749, DOI 10.17487/RFC6749, October 2012. |
| [RFC7591] | Richer, J., Jones, M., Bradley, J., Machulak, M. and P. Hunt, "OAuth 2.0 Dynamic Client Registration Protocol", RFC 7591, DOI 10.17487/RFC7591, July 2015. |
| [RFC8414] | Jones, M., Sakimura, N. and J. Bradley, "OAuth 2.0 Authorization Server Metadata", RFC 8414, DOI 10.17487/RFC8414, June 2018. |
The following have contributed to the development of this specification.
John Bradley, Ralph Bragg, Geoff Graham, Joseph Heenan, Bjorn Hjelm, Takahiko Kawasaki, Torsten Lodderstedt, James Manger, Charles Marais, Nat Sakimura, and Petteri Stenius.
Copyright (c) 2018 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
-04
-05
-06
-OIDC-CIBA-CORE-01
-OIDC-CIBA-CORE-02