To support Service Providers who are looking to reuse existing OpenID connect logic and code, ZenKey created a new Optimized Discovery endpoint. This endpoint can receive the full OIDC request, and once discovery is complete it will immediately redirect the request to the correct carrier.

The following is a high-level sequence diagram illustrating this flow:

Implications of the ZenKey Auth Endpoint

• A Service Provider will still make three high-level requests (authcode request, token request, and userinfo request).
• While ZenKey does support flows similar to OIDC CIBA with server-initiated requests, ZenKey does not support OIDC implicit flows.
• A Service Provider will need to see the MCCMNC that accompanies the authcode. This MCCMNC will inform the Service Provider which carrier services this subscriber. That will inform the Service Provider which token and userinfo endpoints need to be used.
  -Since token and userinfo requests contain user identifiable data in the responses, they are not visible to the central ZenKey service.

Steps for the New ZenKey Auth Endpoint

This endpoint (https://auth.myzenkey.com/v1/auth) will not be defined in an OpenID configuration file as the configuration files will contain the authentication_endpoint for the correct carrier of this subscriber.

This endpoint URI may change.

The Service Provider solution will need to be defined with this variable:

• GET request to this endpoint will redirect to the Carrier Discovery UI.
  -Required url parameters include all the standard OIDC attributes that a Service Provider would define (e.g. client_id, redirect_uri, scope and state).
  -Optional url parameters include acr_values, context and prompt.
  -Any additional parameters provided are automatically forwarded to the carrier’s authorization endpoint.

• ZenKey may cache OIDC request parameters while the discovery process steps are being completed.

• Discovery UI will be used to determine the correct carrier for this subscriber.
  -Testers may notice that the Optimized Discovery Service substitutes its own redirect_url and state so that it can handle the redirect response, but the state variable will be the original value when the request is sent to the carrier.
  -The discovery redirect_url may also be replaced with a temporary value, but will be the correct Service Provider redirect when the request is sent to the carrier.
  -The discovery service response will include a login_hint_token when using a secondary device.

• After discovery is complete the users “user agent” (browser) will be redirected to the correct carrier with any needed login_hint_token added to the request.

• After the request is completed on the user’s primary device the redirect_uri will be opened in the user agent (browser).
  -Response will contain url parameters including code, state, mccmnc, correlation_id, error, and error_description as defined in the current auth request response.

Requests After New Discovery Flow

Once the new discovery flow is complete, the Service Provider will have to make calls to the carrier Token and UserInfo endpoints:

1. Token Request to token_endpoint

• This request occurs on the client server because it requires an Authorization header that includes the client secret.
• The post request from client server to this endpoint submits a form.
  -Required form parameters include token_url, grant_type, code and redirect_uri
• The response is JSON with access_token, id_token, refresh_token and correlation_id.

2. Request User Info from user_endpoint

• This request occurs on the client server because user info should be transferred safely.
  -The get request from the client server to this endpoint containing the auth header.
  -This requires the access token in authorization header and key binding signature in x-authorization header.
• This request returns JSON with user info.

📘

MODRNA-Based Discovery Flow

If you're interested in the MODRNA-Based Discovery Flow you can view documentation here.