MODRNA-based Discovery Flow

This discovery process for ZenKey uses OpenID Connect MODRNA (Mobile Operator Discovery, Registration & AutheNticAtion) extensions. More information on MODRNA can be found here.

In this model, merchants make two distinct requests. The first is for discovery and the second is to the identified carrier for the authorization code.

The following is a high-level sequence diagram illustrating this flow. service_provider refers to the merchant.

How It Works

This model has two discovery endpoints:

  1. A user experience endpoint using a browser client (or native client that can open a browser tab).
  2. An API endpoint that returns the correct carrier's OIDC configuration.

Carrier Discovery UI

  • Redirecting to this endpoint navigates to choosing your carrier UI
    -Required url parameters include client_id and redirect_uri
    -Optional url parameters include state, sdk_version and prompt
  • When the user selects their carrier, they're redirected to their redirect_uri
    -The response has url parameters mccmnc, state and login_hint_token (for secondary devices)

OIDC Discovery Issuer

  • A GET request to this endpoint returns the OpenID configuration document
    -Required url parameters include client_id and mccmnc
    -Optional url parameters include sub, phone_number and ip
  • The response is JSON with OpenID configurations including issuer, authorization_endpoint, token_endpoint and user_endpoint

Request Auth Code from authorization_endpoint

  • Redirecting to this endpoint navigates to the carrier specific authorization_endpoint
    -The required url parameters include client_id, redirect_uri, response_type, scope and state
    -The response_type=code for ZenKey purposes
    -The optional url parameters include login_hint_token (for secondary devices)
  • When authorization request is received the user is redirected to their redirect_uri

The response has url parameters code, state, mccmnc, correlation_id, error, and error_description.


Optimized Discovery Flow

If you're interested in the Optimized Discovery Flow you can view documentation here.

Did this page help you?