Integrating with MANTL as a Relying Party (RP) allows end users to navigate from the Confirmation page of the MANTL Online Account Opening System to the Online/Mobile system of the partner financial institution.

Security Requirements

All interactions must confirm to the OAuth Security Specification.

All network traffic must go over TLS/SSL.
The redirect_uri passed to the authorize endpoint must exactly match the ones given by the service provider, or our system will reject the request.
We require the use of PKCE with theS256transformation method (RFC 7636).
We highly recommend passing a random nonce parameter to the authorize endpoint to protect against replay vulnerabilities.
We highly recommend passing a state parameter to the authorize endpoint to protect against CSRF vulnerabilities.

Requirements Gathering

Relying Party Requirements

The Relying Party must provide MANTL with a set of redirect_uri's and a trigger_url.

The redirect_uri, provided as a parameter to the authorization endpoint, is where we will redirect the browser after the user has been successfully verified and MUST EXACTLY match one of the redirect_uri's provided during setup. These URLs are commonly referred to as OAuth callback URLs. For example, https://omb.com/oauth/2.0/callback

Note: redirect_uri's cannot be wildcard references. For example, https://*.omb.com/callback

MANTL stores theseredirect_uri's in our system in accordance with the OIDC standard to prevent common security vulnerabilities.

Thetrigger_urlis a Relying Party hosted endpoint that initiates the sign on flow by calling theauthorizationendpoint on MANTL's end. Because OIDC does not have a Provider-initiated flow, similar to SAML, thetrigger_urlacts as mechanism to notify the RP that the End-User has requested the service.

Thetrigger_urlis accessed directly by the User-Agent via an HTTPS GET request and is intended to be stateless. Mantl relies on secure cookies to identify the User-Agent upon return to theauthorizationendpoint.

MANTL Requirements

Once the service provider requirements have been received, MANTL will provide the following:

client_id The OAuth client id used to identify you as a service provider bound to your tenant.
client_secret The OAuth client secret used when trading authorization codes for tokens.
discovery_url The well-known discovery URL for your tenant that informs you of all endpoints required to perform the OIDC authorization flow.

Endpoints

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

MANTL provides the following OIDC APIs. You can discover these endpoints programmatically by using the well-known OIDC URL for your tenant.

OIDC Ref	Endpoint	Description
discovery	/api/3.0/sso/outbound/oidc/.well-known/openid-configuration	Displays the supported OIDC methods and endpoints for executing an authorization flow.
jwks	/api/3.0/sso/outbound/oidc/jwks	Displays the RSA keys used for signing JWT (JSON Web Tokens) (id_tokens, access_tokens).
authorize	/api/3.0/sso/outbound/oidc/authorize	Allows a registered (trusted) service provider to request an authorization code used to trade for an access_token.
token	/api/3.0/sso/outbound/oidc/token	Allows a registered (trusted) service provider to trade an authorization code for an access_token.
userinfo	/api/3.0/sso/outbound/oidc/userinfo	Allows a registered (trusted) service provider to use their access_token to pull user profile information.

Example:

https://neuebusiness-ss.uat.mantl.com/api/3.0/sso/outbound/oidc/.well-known/openid-configuration

Data Exchange

OAuth Authorization Flow

A customer successfully completes their application for a new account in MANTL and opts to be automatically enrolled in online mobile banking.
MANTL redirects the User-Agent to the trigger_url that triggers an RP-initiated OAuth authorization flow.

The Relay Party constructs an authorization URL including the following parameters and redirects the User-Agent to its result:

GET /api/3.0/sso/outbound/oidc/auth?client_id=MANTL_PROVIDED_CLIENT_ID
 &scope: 'openid mantl_core',
 &response_type: 'code',
 &redirect_uri=SERVICE_PROVIDER_GIVEN_REDIRECT_URI
 &state=SERVICE_PROVIDER_SESSION_ID
 &nonce=SERVICE_PROVIDER_RANDOM_NONCE
 &code_challenge=SERVICE_PROVIDER_CODE_CHALLENGE
 &code_challenge_method=S256

MANTL will perform the following steps to verify the RPs request:
- Verify the client_id.
- Verify that the redirect_uri exactly matches one given by the RP.
- Verify the user is authenticated via an active session.
- Append an authorization code and redirect the user's browser the redirect_uri.
  {{redirect_uri}}?code=MANTL_GENERATED_AUTHORIZATION_CODE
The RP will use the code provided to the redirect_uri and trade it for an access_token on their servers' backend by making a POST request withContent-Type: x-form-urlencoded.
```
POST /api/3.0/sso/outbound/oidc/token

Content-Type: application/x-www-form-urlencoded
client_id=MANTL_PROVIDED_CLIENT_ID
&client_secret=MANTL_PROVIDED_CLIENT_SECRET
&code=MANTL_PROVIDED_AUTH_CODE_FROM_REDIRECT
&code_verifier=SERVICE_PROVIDER_CODE_VERIFIER
&redirect_uri=SERVICE_PROVIDER_GIVEN_REDIRECT_URI
```
Note: API version <3.0 required the client_id and client_secret to be in the body of the form request. As of 3.0, HTTP Basic authentication is also supported (RFC 2617) and the preferred choice per OAuth RFC 6749.
MANTL will respond to the token request with an access_token for the user that the authorization code belonged to.
```
{
  "access_token": "JWT_ENCODED_ACCESS_TOKEN"
}
```
The Relying Party will now be able to use the access_token to request data from the userinfo endpoint on their server by passing theaccess_token in the Authoization header.
```
GET /api/3.0/sso/outbound/oidc/userinfo

Authorization: Bearer {{access_token}}
```

Userinfo Response

The data returned from the userinfo endpoint will vary between partner financial institutions based on product offerings, details of core implementations, MANTL configuration, and API version. However, the claims support should be consistent per integration.

Claims and Scopes

Claim	Type	Description
sub	string	The Subject string as the unique identifier. A MANTL UUID that will have little benefit to consumers beyond debugging.
name	string	Full name of the subject
given_name	string	Last name of the subject
family_name	string	First name of the subject
email	string	Email address of the subject
email_verified	boolean	This value is always provided as true
https://mantl.com/claims/core_id	string	The unique identifier of the subject in the FI's core. Depending on the core, this value may be referred to CIF, RM #, CMID, NetTeller ID, etc. Not all core integrations have a single, unique value for the subject. In those cases, this claim may not be provided or may be an internal UUID from MANTL.
https://mantl.com/claims/member_id	string	Only available for some credit union integrations. When available, the member ID is usually more useful than the core ID.
https://mantl.com/claims/tax_id	string	The tax ID of the subject. Commonly the SSN of the user. Even when business accounts are opened, this value is the tax ID of the applicant, not the EIN of the business.
https://mantl.com/claims/minor_member_id	string	Only available for some credit union integrations. In the case of opening a share for a minor the Subject refers to the guardian, as the guardian is the user.

Scope	Claims
openid	Enables OIDC by requesting the ID Token (in addition to an access token). Without this scope, the request is not OIDC, but merely OAuth 2.0. sub
profile	name, family_name, given_name
email	email, email_verified
mantl_core	https://mantl.com/claims/core_id, https://mantl.com/claims/member_id, https://mantl.com/claims/tax_id
mantl_auxiliary	Context specific information about the account the user most recently viewed. Not good OIDC practice, but some FIs need it. https://mantl.com/claims/minor_member_id

Examples of Userinfo Response

scope=openapi

{
  "sub": "e79a4099-941c-41ca-bfa3-d7eb0af58106"
}

scope=openapi mantl_core

{
  "sub": "e79a4099-941c-41ca-bfa3-d7eb0af58106",
  "https://mantl.com/claims/core_id": "FINANCIAL_INSTITUTION_CORE_IDENTIFIER",
  "https://mantl.com/claims/tax_id": "555555555"
}

scope=openapi profile email mantl_core

{
  "sub": "e79a4099-941c-41ca-bfa3-d7eb0af58106",
  "name": "John Doe",
  "given_name": "John",
  "family_name": "Doe",
  "email": "john.doe@yahoo.com",
  "email_verified": true,
  "https://mantl.com/claims/core_id": "FINANCIAL_INSTITUTION_CORE_IDENTIFIER",
  "https://mantl.com/claims/tax_id": "555555555"
}