OpenID Connect Client Initiated Backchannel Authentication Flow

OpenID Connect Client Initiated Backchannel Authentication Flow - Core 1.0 draft-03 Telefonica I+D

gonzalo.fernandezrodriguez@telefonica.com

Deutsche Telekom AG

F.Walter@telekom.de

Deutsche Telekom AG

axel.nennker@telekom.de

Moneyhub

dave.tonge@moneyhub.com

Ping Identity

bcampbell@pingidentity.com

OpenID Mobile Profile Working Group 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 has the concept of a Consumption Device (on which the user interacts with the Relying Party) and an Authentication Device (on which the user authenticates with the OpenID Provider and grants consent). This specification allows a Relying Party that has an identifier for a user to obtain tokens from the OpenID Provider. The user starts the flow with the Relying Party at the Consumption Device, but authenticates and grants consent on the Authentication Device.

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 . 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: The Consumption Device is the device that helps the user consume the service. In the CIBA use case, the user is not necessarily in control of the CD. For example, the CD may be in the control of an RP agent (e.g. at a bank teller) or may be an RP controlled device (e.g. a petrol pump). The device on which the user will authenticate and authorize the request, often a smartphone.

Client Initiated Backchannel Authentication (CIBA) enables a Client to initiate the authentication of an end-user by means of out-of-band mechanisms. The Client shall make an "HTTP POST" request to the Backchannel Authentication Endpoint to ask for end-user authentication. The OP will respond immediately with a unique identifier that identifies that authentication while it tries to authenticate the user in the background. The Client will receive the ID Token, Access Token and optionally Refresh Token by means of either the Poll, Ping or Push modes, this choice MUST be established by the Client at registration time. When configured in Poll mode, the Client will poll the token endpoint to get a response with the tokens. When configured in Ping mode, the OP will send a request to a callback URI previously registered by the Client with the unique identifier returned from the Backchannel Authentication Endpoint. Upon receipt of the notification, the Client makes a request to the token endpoint to obtain the tokens. When configured in Push mode, the OP will send a request with the tokens to a callback URI previously registered by the Client.

This specification introduces the CIBA grant type (an extension grant type as defined by Section 4.5 of OAuth 2.0) with the value: urn:openid:params:grant-type:ciba The following authorization server metadata parameters are introduced by this specification for OPs publishing their support of the CIBA flow and details thereof. backchannel_token_delivery_modes_supported: REQUIRED. JSON array containing one or more of the following values: poll, ping and push. backchannel_authentication_endpoint: REQUIRED. URL of the OP's Backchannel Authentication Endpoint as defined in . backchannel_authentication_request_signing_alg_values_supported: OPTIONAL. JSON array containing a list of the JWS signing algorithms (alg values) supported by the OP for signed authentication requests, which are described in . If omitted, signed authentication requests are not supported by the OP. backchannel_user_code_parameter_supported: OPTIONAL. Boolean value specifying whether the OP supports use of the user_code parameter, with true indicating support. If omitted, the default value is false. The CIBA grant type is used in the grant_types_supported field of discovery metadata for OPs that support the ping or poll delivery modes. The supported client authentication methods and, when applicable, the associated JWS signing algorithms of the OP's Backchannel Authentication Endpoint are the same as those indicated by the token_endpoint_auth_methods_supported and token_endpoint_auth_signing_alg_values_supported metadata parameters respectively. Clients registering to use CIBA MUST indicate a token delivery mode. When using the ping or poll mode, the Client MUST include the CIBA grant type in the "grant_types" field. When using the ping or push mode, the Client MUST register a client notification endpoint. Clients intending to send signed authentication requests MUST register the signature algorithm that will be used. The following parameters are introduced by this specification: backchannel_token_delivery_mode: REQUIRED. One of the following values: poll, ping or push. backchannel_client_notification_endpoint: REQUIRED if the token delivery mode is set to ping or push. This is the endpoint to which the OP will post a notification after a successful or failed end-user authentication. It MUST be an HTTPS URL. backchannel_authentication_request_signing_alg: OPTIONAL. The JWS algorithm alg value that the Client will use for signing authentication request, as described in . When omitted, the Client will not send signed authentication requests. backchannel_user_code_parameter: OPTIONAL. Boolean value specifying whether the Client supports the user_code parameter. If omitted, the default value is false. This parameter only applies when OP parameter backchannel_user_code_parameter_supported is true. The token_endpoint_auth_method indicates the registered authentication method for the client to use when making direct requests to the OP, including requests to both the token endpoint and the backchannel authentication endpoint. In order to use the Poll or Ping mode with Pairwise Pseudonymous Identifiers (PPIDs), the Client needs to register a URI that is of its ownership and use it during the authentication process in a way that demonstrates that the URI belongs to it, which allows the OP to consider the host component of that URI as the Sector Identifier for the pairwise identifier calculation per Section 8.1 of OpenID Connect Core. In OpenID Connect Core the sector_identifier_uri contains a document with a list of redirect_uris and the Sector Identifier is defined as either the host component of the sector_identifier_uri or if this is not provided then the host component of the redirect_uri. In CIBA Poll and Ping modes the jwks_uri is used in place of the redirect_uri. In CIBA Push mode the backchannel_client_notification_endpoint is used in place of the redirect_uri. In situations where the PPID must be shared among multiple RPs, then a sector_identifier_uri can be registered. This specification extends the purpose of the sector_identifier_uri such that it can contain jwks_uris and backchannel_client_notification_endpoints as well as redirect_uri. In order to support Pairwise Pseudonymous Identifiers in Ping and Poll modes, the RP must provide either a sector_identifier_uri or a jwks_uri at the registration phase when the urn:openid:params:grant-type:ciba grant type is registered. In that way the OpenID Provider can use the host component of the sector_identifier_uri or jwks_uri as the Sector Identifier to generate the PPIDs for the Client. When an OpenID Provider that supports PPIDs receives a dynamic registration request for a Client that indicates that it wishes to use the Poll or Ping CIBA modes, it MUST check if a valid jwks_uri is set when the subject_type is pairwise. If a sector_identifier_uri is explicitly provided, then the jwks_uri must be included in the list of URIs pointed to by the sector_identifier_uri. But having registered a "jwks_uri" is not enough to use PPIDs, Client needs somehow to demonstrate that such "jwks_uri" belongs to it, which can be accomplished by proving possession of a private key corresponding to one of the public keys published at the "jwks_uri". Such proof can be demonstrated with signed authentication requests using the asymmetric keys provided by the "jwks_uri" or by authenticating to the OP using one of the following two mechanisms in conjunction with a key from its "jwks_uri": Using the Self-Signed Certificate Mutual TLS OAuth Client Authentication Method as defined in section 2.2 of . Using the private_key_jwt method as per the section 9 Client Authentication of . When using the Push mode, the PPIDs will use the host component of the "backchannel_client_notification_endpoint" as the Sector Identifier. In case a "sector_identifier_uri" is explicitly provided, then the "backchannel_client_notification_endpoint" must be included in the list of URIs pointed to by the "sector_identifier_uri".

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

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. A call center agent wants to authenticate a caller. Using additional scopes like e.g. "profile" or "phone" the call center agent would get access to claims about the user like "phone_number" and "phone_number_verified". A bank teller wants to authenticate a customer in a bank branch - using CIBA for authentication in a face-to-face scenario. A user wants to use their smartphone to authorize a payment they are making at a point of sale terminal.

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 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 or authentication methods defined by extension in other specifications. Note that there's some potential ambiguity around the appropriate audience value to use when JWT client assertion based authentication is employed. To address that ambiguity the Issuer Identifier of the OP SHOULD be used as the value of the audience. In order to facilitate interoperability the OP MUST accept its Issuer Identifier, Token Endpoint URL, or Backchannel Authentication Endpoint URL as values that identify it as an intended audience. An authentication request is composed of the following parameters and MAY contain additional parameters defined by extension or profile: REQUIRED. The scope of the access request as described by Section 3.3 of . OpenID Connect implements authentication as an extension to OAuth 2.0 by including the openid scope value in the authorization requests. Consistent with that, CIBA authentication requests MUST therefore contain the openid scope value. The behavior when the openid scope value is not present is left unspecified by this document, thus allowing for the potential definition of the behavior in a non OpenID context, such as an OAuth authorization flow. Other scope values MAY be present, including but not limited to the profile, email, address and phone scope values from Section 5.4 of . REQUIRED if the Client is registered to use Ping or Push modes. It is a bearer token provided by the Client that will be used by the OpenID Provider to authenticate the callback request to the Client. The length of the token MUST NOT exceed 1024 characters and it MUST conform to the syntax for Bearer credentials as defined in Section 2.1 of . Clients MUST ensure that it contains sufficient entropy (a minimum of 128 bits while 160 bits is recommended) to make brute force guessing or forgery of a valid token computationally infeasible - the means of achieving this are implementation specific, with possible approaches including secure pseudorandom number generation or cryptographically secured self-contained tokens. OPTIONAL. Requested Authentication Context Class Reference values. Space-separated string that specifies the acr values that the OpenID Provider is being requested to use for processing this Authentication Request, with the values appearing in order of preference. The actual means of authenticating the end-user, however, are ultimately at the discretion of the OP and the Authentication Context Class satisfied by the authentication performed is returned as the acr Claim Value of the ID Token. When the acr_values parameter is present in the authentication request, it is highly RECOMMENDED that the resulting ID Token contain an acr Claim. OPTIONAL. A token containing information identifying the end-user for whom authentication is being requested. The particular details and security requirements for the login_hint_token as well as how the end-user is identified by its content are deployment or profile specific. OPTIONAL. An ID Token previously issued to the Client by the OpenID Provider being passed back as a hint to identify the end-user for whom authentication is being requested. If the ID Token received by the Client from the OP was asymmetrically encrypted, to use it as an id_token_hint, the client MUST decrypt the encrypted ID Token to extract the signed ID Token contained in it. OPTIONAL. A hint to the OpenID Provider regarding the end-user for whom authentication is being requested. The value may contain an email address, phone number, account number, subject identifier, username, etc., which identifies the end-user to the OP. The value may be directly collected from the user by the Client before requesting authentication at the OP, for example, but may also be obtained by other means. OPTIONAL. A human readable identifier or message intended to be displayed on both the consumption device and the authentication device to interlock them together for the transaction by way of a visual cue for the end-user. This interlocking message enables the end-user to ensure that the action taken on the authentication device is related to the request initiated by the consumption device. The value SHOULD contain something that enables the end-user to reliably discern that the transaction is related across the consumption device and the authentication device, such as a random value of reasonable entropy (e.g. a transactional approval code). Because the various devices involved may have limited display abilities and the message is intending for visual inspection by the end-user, the binding_message value SHOULD be relatively short and use a limited set of plain text characters. The invalid_binding_message defined in is used in the case that it is necessary to inform the Client that the provided binding_message is unacceptable. OPTIONAL. A secret code, such as password or pin, known only to the user but verifiable by the OP. The code is used to authorize sending an authentication request to user's authentication device. This parameter should only be present if client registration parameter backchannel_user_code_parameter indicates support for user code. OPTIONAL. A positive integer allowing the client to request the expires_in value for the auth_req_id the server will return. The server MAY use this value to influence the lifetime of the authentication request and is encouraged to do so where it will improve the user experience, for example by terminating the authentication when as it knows the client is no longer interested in the result. 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):

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. An exception to this is requested_expiry, which may be sent as either a JSON string or a JSON number, the OP must accept either type. An extension or profile may define additional authentication request parameters, these may be defined to be any JSON type. 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 regarding asymmetric signatures. The JWT MUST also contain the following registered claims: The Audience claim MUST contain the value of the Issuer Identifier for the OP, which identifies the Authorization Server as an intended audience. The Issuer claim MUST be the client_id of the OAuth Client. An expiration time that limits the validity lifetime of the signed authentication request. The time at which the signed authentication request was created. The time before which the signed authentication request is unacceptable. A unique identifier for the signed authentication request. 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):

Where the following is the JWT payload (with line wraps and added whitespace for display purposes only): Note that encrypted JWT authentication requests are not supported.

CIBA supports the optional use of "user codes" as a mechanism to prevent unsolicited authentication requests from appearing on a user's authentication device. A "user code" is a secret known to the user, but which is not the user's password at the OP. When an OP supports this feature then Clients are required to ask the user for their "user code" in order to start a CIBA flow. This prevents malicious Clients or malicious end-users from starting unsolicited CIBA flows for a particular user for whom they know the login_hint or equivalent. 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 the User Code mechanism (e.g. web applications that use CIBA for step-up authentication or call center applications where a caller ID is used to identify the user). In addition clients who don't use static user identifiers as login hints should be allowed without requiring the User Code mechanism. 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 or another 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: Authenticate the Client per the authentication method registered or configured for its client_id. It is RECOMMENDED that Clients not send shared secrets in the Authentication Request but rather that public key cryptography be used. If the authentication request is signed, validate the JWT sent with the request parameter, which includes verifying the signature and ensuring that the JWT is valid in all other respects per . Validate all the authentication request parameters. In the event the request contains more than one of the hints specified in Authentication Request, the OpenID Provider MUST return an "invalid_request" error response as per . The OpenID Provider MUST process the hint provided to determine if the hint is valid and if it corresponds to a valid user. The type, issuer (where applicable) and maximum age (where applicable) of a hint that an OP accepts should be communicated to Clients. How the OP validates hints and informs Clients of its hint requirements is out-of-scope of this specification. If the hint is not valid or if the OP is not able to determine the user then an error should be returned to the Client as per Section . The OpenID Provider MUST verify that all the REQUIRED parameters are present and their usage conforms to this specification. OpenID Providers SHOULD ignore unrecognized request parameters. If the OpenID Provider encounters any error, it MUST return an error response, per .

If the is validated as per Section , 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: REQUIRED. This is a unique identifier to identify the authentication request made by the Client. It MUST contain sufficient entropy (a minimum of 128 bits while 160 bits is recommended) to make brute force guessing or forgery of a valid auth_req_id computationally infeasible - the means of achieving this are implementation specific, with possible approaches including secure pseudorandom number generation or cryptographically secured self-contained tokens. The OpenID Provider MUST restrict the characters used to 'A'-'Z', 'a'-'z', '0'-'9', '.', '-' and '_', to reduce the chance of the client incorrectly decoding or re-encoding the auth_req_id; this character set was chosen to allow the server to use unpadded base64url if it wishes. The identifier MUST be treated as opaque by the client. REQUIRED. A JSON number with a positive integer value indicating the expiration time of the "auth_req_id" in seconds since the authentication request was received. A Client calling the token endpoint with an expired auth_req_id will receive an error, see . OPTIONAL. A JSON number with a positive integer value indicating the minimum amount of time in seconds that the Client MUST wait between polling requests to the token endpoint. This parameter will only be present if the Client is registered to use the Poll or Ping modes. If no value is provided, clients MUST use 5 as the default value.

The following is a non-normative example of an authentication response:

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 . 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 . 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 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 . 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). For polling requests the OP may implement long polling, where the OP responds to the token request only when the authentication result has become available or a timeout has occurred. A timeout of 30 seconds is recommended for long polling requests, as specified in Section 5.5 of RFC6202, Best Practices for Long Polling. Clients should be prepared to wait at least 30 seconds for a response when using polling mode. The OP should not take longer than 30 seconds to respond to a request, even when using long polling. The polling interval is measured from the instant when a polling request is sent. To implement long polling the OP may respond slower than interval. A Client MUST NOT send two overlapping requests with same auth_req_id. Rather the client must always wait until receiving the response to the previous request before sending out the next request. If the interval has passed when the response is received, then the client may immediately send out the next request. An OP in a meltdown type situation may return an HTTP 503 with a Retry-After response header as described in Section 7.1.3 of HTTP/1.1. Clients should respect such headers and only retry the token request after the time indicated in the header. Here are some illustations of how a Client should behave based on different OP responses, assuming a default interval of 5s: The Client makes a token request and the OP returns an authorization_pending error after 30s. In this case the Client can immediately make the next token request. The Client makes a token request and the OP returns an authorization_pending error after 2s. In this case the Client must wait 3s before making the next request. The Client makes a token request and the OP doesn't return any response within 30s. In this case the Client may cancel the request and make a new request. 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: REQUIRED. Value MUST be urn:openid:params:grant-type:ciba REQUIRED. It is the unique identifier to identify the authentication request (transaction) made by the Client. The OP MUST check whether the auth_req_id was issued to this Client in response to an . Otherwise, an error MUST be returned.

The following is a non-normative example of a token request (with line wraps within values for display purposes only).

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 . Once redeemed for a successful token response, the auth_req_id value that was used is no longer valid. 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 .

The following is a non-normative example of a successful token response (with line wraps within values for display purposes only).

If the Client is registered in Ping mode, the OpenID Provider will send an HTTP POST Request to the 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). 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 .

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 . Error conditions associated with the authentication request are delivered to the Client by sending a to the . 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 . 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 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. 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 . 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 . 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:

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 . In addition to the error codes defined in Section 5.2 of , the following error codes defined in the OAuth Device Flow are also applicable: The authorization request is still pending as the end-user hasn't yet been authenticated. A variant of "authorization_pending", the authorization request is still pending and polling should continue, but the interval MUST be increased by at least 5 seconds for this and all subsequent requests. The auth_req_id has expired. The Client will need to make a new Authentication Request. The end-user denied the authorization request. 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 . If a Client continually polls quicker than the interval, the OP may return an invalid_request error. If a Client receive an invalid_request error it must not make any further requests for the same auth_req_id. 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. The Client is not authorized as it is configured in Push Mode Note, when a Client receives a 4xx response code with a JSON payload then it should inspect the payload in order to determine the error rather than relying on the HTTP status code alone.

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: OPTIONAL. Human-readable ASCII [USASCII] text providing additional information, used to assist the client 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 REQUIRED. A single ASCII error code from one present in the list below. REQUIRED. The authentication request identifier. Error codes applicable to the push error payload: The end-user denied the authorization request. The auth_req_id has expired. The Client will need to make a new Authentication Request. OpenID Providers are not required to send this error, but Clients SHOULD support receiving this error. The OpenID Provider encountered an unexpected condition that prevented it from successfully completing the transaction. This general case error code can be used to inform the Client that the CIBA transaction was unsuccessful for reasons other than those explicitly defined by access_denied and expired_token.

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: REQUIRED. A single ASCII error code from one present in the list below. OPTIONAL. Human-readable ASCII [USASCII] text providing additional information, used to assist the client 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. 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. List of authentication error codes associated to HTTP Errors. The request is missing a required parameter, includes an invalid parameter value, includes a parameter more than once, contains more than one of the hints, or is otherwise malformed. The requested scope is invalid, unknown, or malformed. The login_hint_token provided in the authentication request is not valid because it has expired. The OpenID Provider is not able to identify which end-user the Client wishes to be authenticated by means of the hint provided in the request (login_hint_token, id_token_hint or login_hint). The Client is not authorized to use this authentication flow. User code is required but was missing from the request. User code was invalid. The binding message is invalid or unacceptable for use in the context of the given request. Client authentication failed (e.g., invalid client credentials, unknown client, no client authentication included, or unsupported authentication method). The resource owner or OpenID Provider denied the request. Note that as the authentication error response is received prior to any user interaction, such an error would only be received if a resource owner or OpenID Provider had made a decision to deny a certain type of request or requests from a certain type of client. The mechanism for such a decision to be made is outside the scope of this specification.

The following is a non-normative example from an authentication error response:

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. In some scenarios it may be appropriate for the RP to pass metadata to the OP about the context of the session it has with the user. For example the RP could send the geolocation of the consumption device and the OP could verify that against the geolocation of the authentication device. This specification does not require such metadata to be sent, nor does it define the method by which such metadata would be conveyed.

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: CIBA supports the use of ID Tokens as an id_token_hint in the authentication request. If the OP has previously issued an ID Token to the Client that contains a pairwise identifier and no personally identifiable information, then a CIBA flow can be initialized without the RP asking the user for a static identifier. This ID Token may have been obtained by the Client via a standard front-channel redirect flow. The OP could generate a single-use identifier which could be transferred from the Authentication Device to the Consumption Device at the start of the flow. For example, the user could authenticate on the AD and request an identifier for a CIBA flow. This could be displayed as a QR code, the user could scan this QR code at the CD. The RP would then decode the identifier and embed it in a login_hint_token which it would use to initiate a CIBA flow. The OP would then gain consent from the end-user for the access requested by the RP. For some ecosystems the RP may be able to send the user to a discovery service and receive back an encrypted login_hint_token which it can use in the authentication request. The OP would decrypt the token, identify the user and continue the CIBA flow.

This specification requests registration of the following values in the IANA "OAuth Authorization Server Metadata" registry of established by . Metadata Name: backchannel_token_delivery_modes_supported Metadata Description: Supported CIBA authentication result delivery modes Change Controller: OpenID Foundation MODRNA Working Group - openid-specs-mobile-profile@lists.openid.net Specification Document(s): of this document Metadata Name: backchannel_authentication_endpoint Metadata Description: CIBA Backchannel Authentication Endpoint Change Controller: OpenID Foundation MODRNA Working Group - openid-specs-mobile-profile@lists.openid.net Specification Document(s): of this document Metadata Name: backchannel_authentication_request_signing_alg_values_supported Metadata Description: JSON array containing a list of the JWS signing algorithms supported for validation of signed CIBA authentication requests Change Controller: OpenID Foundation MODRNA Working Group - openid-specs-mobile-profile@lists.openid.net Specification Document(s): of this document Metadata Name: backchannel_user_code_parameter_supported Metadata Description: Indicates whether the OP supports use of the CIBA user_code parameter. Change Controller: OpenID Foundation MODRNA Working Group - openid-specs-mobile-profile@lists.openid.net Specification Document(s): of this document

This specification requests registration of the following client metadata definitions in the IANA "OAuth Dynamic Client Registration Metadata" registry of established by : Client Metadata Name: backchannel_token_delivery_mode Client Metadata Description: CIBA authentication result delivery mode Change Controller: OpenID Foundation MODRNA Working Group - openid-specs-mobile-profile@lists.openid.net Specification Document(s): of this document Client Metadata Name: backchannel_client_notification_endpoint Client Metadata Description: Endpoint to which a notification will be sent after a CIBA end-user authentication event Change Controller: OpenID Foundation MODRNA Working Group - openid-specs-mobile-profile@lists.openid.net Specification Document(s): of this document Client Metadata Name: backchannel_authentication_request_signing_alg Client Metadata Description: The JWS algorithm that the client will use to sign CIBA authentication requests Change Controller: OpenID Foundation MODRNA Working Group - openid-specs-mobile-profile@lists.openid.net Specification Document(s): of this document Client Metadata Name: backchannel_user_code_parameter Client Metadata Description: Indicates whether the Client must support the CIBA user_code parameter. Change Controller: OpenID Foundation MODRNA Working Group - openid-specs-mobile-profile@lists.openid.net Specification Document(s): of this document

This specification requests registration of the following value in the IANA "OAuth Parameters" registry of established by . Parameter name: auth_req_id Parameter usage location: token response Change Controller: OpenID Foundation MODRNA Working Group - openid-specs-mobile-profile@lists.openid.net Specification document(s): of this document

This specification makes no request of IANA with respect to the "JSON Web Token Claims" registry at established by . Public Claim Names where used for the auth_req_id and refresh token hash in the ID Token in 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.

&OpenID.Core; OAuth Parameters IANA JSON Web Token (JWT) IANA

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 Initial draft -02 Second draft Authentication Request Section: Improving the definition of client_req_id Successful Authentication Request Acknowledgement: a. auth_req_id: to explain that it will not be present in token when using Polling mode b. interval: fixing a misleading description Token Request Using Polling Mechanism: a. Fixing a misleading description about the inclusion of client_notification_endpoint in the authentication request. It does not make sense since Notification or Polling mode is defined at the registration time and client_notification_endpoint. is not sent in the authentication request anymore. b. auth_req_id: fixing misleading description. Changing Successful Token Polling to Successful Token Polling Response Improving descriptions in Successful Token Polling Response and Successful Token Notification expires_in parameter from Successful Authentication Request Acknowledgement refers to the auth_req_id that will be considered overdue to make new polling requests after that time. New unknown_auth_req_id and expired_token erros in Token Error Response Authentication Error Response section is defined and incorporates two new errors: unknown_user_id when OP cannot figure out the user to be authenticated by means of the hint and expired_token to indicate that the login_hint_token or id_token_hint provided is expired. Changing client_req_idto client_notification_token New overview section -03 Following the lead of user questioning remove the term Relying Party in most places. -04 The Client MUST be authenticated. The Client SHOULD use a signed OpenID Connect Request object. 3) The OP MUST support signed OpenID Connect Requests objects and if the validation of the signature fails the request MUST fail. If alg == none another method of Client authentication MUST be used Added text regarding Pairwise Identifiers. Added SIM Applet Authenticator example to illustrate the CIBA flow with an specific authenticator -05 If the OP uses Pairwise Identifiers then registering a sector_identifier_uri at registration time is mandatory. -06 If the OP uses Pairwise Identifiers and the Polling Mechanism to retrieve the token, it is necessary to provide a "jwks_uri" at the registration phase and it is MANDATORY for the Client to authenticate the token endpoint using one of this two mechanisms: Using Mutual TLS Self-Signed Certificate method as defined in section 2.2 of or using the private_key_jwt method as per the section 9 Client Authentication of the at_hash, urn:openid:params:jwt:claim:rt_hash and urn:openid:params:jwt:claim:auth_req_id values have been added within the id_token to bind it with the access_token, refresh_token and the auth_req_id in the push mode. Change acr_values to be optional in the authentication request and define the parameter inline. Clarify that error responses from the Backchannel Authentication Endpoint are as defined in the Authentication Error Response section. Be clear that refresh tokens are optional. Introduce a third mode for getting the tokens so now there's 1) Poll, 2) Ping and 3) Push. Add AS/OP metadata parameter for the Backchannel Authentication Endpoint. More clearly define the authentication request format and client authentication to the Backchannel Authentication Endpoint. Change client_notification_endpoint to backchannel_client_notification_endpoint. -OIDC-CIBA-CORE-01 Changed name to OpenID Connect Client Initiated Backchannel Authentication Flow - Core Removed SimApplet Example Changed Privacy Considerations to be less MNO specific and explain the different identifiers that can be used. -OIDC-CIBA-CORE-02 Update the grant type URI to be more generic and not include MODRNA. Add an invalid_binding_message error code that can be used on the Authentication Error Response if the binding_message is unacceptable. Add the requested_expiry Authentication Request parameter. Add a transaction_failed error code to Push Error Payload as a catch-all. Be explicit that expires_in and interval of the Authentication Request Acknowledgement are positive integers represented as JSON numbers. -OIDC-CIBA-CORE-03 Explicitly state the expectations for the audience value when JWT assertion based client authentication is used at the Backchannel Authentication Endpoint. Clarify that only an asymmetrically encrypted id_token_hint needs to be decrypted. Example changes: use public key crypto for client auth, make the expires_in values more reasonable, remove userinfo_encrypted_response_alg RSA1_5 use that wasn't needed anyway, update the login hint token to use sub_id rather than subject now that https://tools.ietf.org/html/draft-ietf-secevent-subject-identifiers-04 has a "sub_id" JWT Claim definition, change signed request and hint to use ECDSA so they're a little smaller. Define a default value of 5 seconds for interval. More clearly define Consumption Device and Authentication Device in the intro. Added a security consideration around context metadata. Better describe the use of long polling. Improve text around the PPID mechanism and the guidance around verification of ownership of keys at jwks_uri. Clarify that the auth_req_id value is not valid after successful redemption. Update some references. Add a note instructing clients to look error bodies rather than relying on the HTTP status code alone. Add character restrictions for auth_req_id values. Allow requested expiry to be sent as a number or string and state that extensions profiles may define additional authentication request parameters as any JSON type. Add guidance around clients who poll to quickly. Editorial changes to better introduce the user code mechanism.