Skip to main content

OIDC Integration for Identity Providers

  • Updated

    Bringing authenticated customers from an Online/Mobile Banking (OMB) platform into the MANTL Online Account Opening System using OpenID Connect (OIDC) to securely identity the user.


    This article assumes the reader has a decent understanding of the OIDC 1.0 identity layer and OAuth 2.0 protocol.

    Links to the standards and other resources can be found here:

    Additional OIDC Resources

     

    Authorization Code Flow with OIDC

    When a user clicks a call-to-action in an OIDC enabled OMB, the browser is redirected to a "trigger" endpoint on MANTL's side. MANTL's API initiates an authorization request and redirects the browser to the authorization_endpoint defined in the Identity Provider's Discovery endpoint.
    MANTL only supports Authorization Code flow with Proof Key for Code Exchange (PKCE).

    MANTL uses a minimal set of claims from the userinfo endpoint, as we prefer to pull all necessary information directly from the core once we've successfully and securely identified the user.

    OIDC and OAuth offer a lot of functionality by way of authorization that MANTL does not use. We provide OIDC as an easy, secure method to identify the user coming from an OMB.

     

    OpenID Provider Requirements​

    As part of the configuration setup, the OpenID Provider (OP) will need to provide MANTL with the following information:

    • client_id The OAuth client id used to identify MANTL as a service provider in your system.
    • client_secret The OAuth client secret used when trading authorization codes for tokens.
    • discovery_url The well-known Discovery URL for your identity provider that informs MANTL of all the endpoints required to perform the OIDC authorization flow.
    • The names of claim(s) that will include the data MANTL needs to query the core for the End-User. Generally, we need to know the claim for the user's ID directly in the core or their tax ID. Credit unions may prefer to provide a member ID.
    • By default, our authorization request will only include a scope param of "openid". If you need additional scopes or other parameters, such as acr_values, be sure to notify your CSM manager.

    Important: The OAuth client ID and secret are sensitive and MUST be passed using a secure mechanism. Please do not email them to MANTL.

    MANTL Requirements​

    Information on the origin of the URL: Environments and URL Domains

    In order to pre-register MANTL as a Relying Party (RP) with the OP, we will provide the following:

    • trigger_url 
      • Allows MANTL to initiate the authorization flow.
      • Upon receiving an HTTPS GET request to this endpoint, MANTL will immediately redirect the User-Agent to the authorization endpoint.
      • {origin}/api/3.0/sso/inbound/oidc/trigger

    Examples:

    https://neuebusiness-ss.uat.mantl.com/api/3.0/sso/inbound/oidc/trigger
https://open.the-bank.org/api/3.0/sso/inbound/oidc/trigger
    • redirect_url 
      • To which the authorization endpoint response will be sent.
      • This value will EXACTLY match the redirect_url parameter MANTL provides to the authorization endpoint (RFC 3986).
      • {origin}/api/3.0/sso/inbound/oidc/callback

    Examples:

    https://neuebusiness-ss.uat.mantl.com/api/3.0/sso/inbound/oidc/callback
https://open.the-bank.org/api/3.0/sso/inbound/oidc/callback

     

    Product Specific Interactions

    The default behavior of a successful OIDC login will land the user on the MANTL product selection page, which has a curated list of product offerings for the given Financial Institution. However, a common use case is to have the call-to-action in the OMB be product specific. In this case, the user will land in an already open application for the given product type.

    To facilitate this, the OMB can optionally include a Product ID as the query parameter product_id to the initial trigger endpoint.
    Product IDs themselves will be provided by your CSM manager. They're slugs that can look like the following: personalSavings, 12monthCD>250k, etc.
    Ensure the values are correctly URL encoded per RFC 3986.

     

    Product Selection Filtering

    The OMB can designate a specific view of the MANTL product selection page by including optional query params to the {origin}/api/3.0/sso/inbound/oidc/trigger URL.

    customer_category: e.g. personal, business, minor

    product_type: e.g. savings, checking, certificate

    Example: .../trigger?customer_category=personal&product_type=savings

    Ensure the values are correctly URL encoded per RFC 3986.

     

    Marketing Parameters

    Any of the marketing parameters supported by the MANTL product selection page (promo code, UTM parameters, etc.) can be included as query parameters to the trigger URL.

    Example: .../trigger?promo_code=save_today&utm_campaign=spring_sale&...

    Related articles