Authentication

Core Exchange uses the OpenID Connect protocol (OIDC) to authenticate your customers. OIDC is an extension of OAuth2. Plaid will use the OIDC flow to get authorization from the end user. This authorization allows Plaid to access your Core Exchange API on their behalf. In order to successfully allow your users to complete the authorization flow, you must:

• Create an OIDC-compliant server
• Issue Plaid a client ID and client secret
• Guide your users through all the steps in the authorization flow

You can generate an OIDC-compliant server in any of the following ways:

• Using your existing OAuth identity provider. (For example, Okta, Auth0, Ping Identity, Azure Active Directory, AWS Cognito)
  • If you don't yet have an identity provider, Plaid recommends our partner, Okta. Okta is an industry-leading, independent provider with expertise onboarding data partners to OAuth integrations. Contact us for help getting started with Okta.
• Building a server with an OIDC-certified open source or commercial implementation
• Building a server from scratch (not recommended)

The /.well-known/openid-configuration endpoint of the OIDC server is a public endpoint that accepts HTTP GET requests without authentication. It returns a JSON object containing the minimum following values:

Plaid's request:

1curl GET 'https://auth.firstplatypusbank.com/.well-known/openid-configuration'

Your response:

1{
2  "authorization_endpoint": "https://auth.firstplatypusbank.com/oauth2/v1/authorize",
3  "token_endpoint": "https://auth.firstplatypusbank.com/oauth2/v1/token",
4  "userinfo_endpoint": "https://auth.firstplatypusbank.com/oauth2/v1/userinfo",
5  "token_endpoint_auth_methods_supported": ["client_secret_basic"],
6  "response_types_supported": ["code"],
7  "scopes_supported": ["openid", "offline_access"]
8}

In order to allow Plaid to authenticate its request for an access token, you must issue Plaid a client ID and client secret. These allow Plaid to identify itself. You may create the client ID and client secret using your preferred method, but we provide some guidance in the sections below.

A client ID is a public identifier that you assign to Plaid. While it is not secret, we recommend choosing a client ID that is not easy to guess.

Note: The client ID must be between 8 and 256 characters long.

One way to create a client ID is to use a random 32-character hex string. Example:

1import crypto from "crypto";
2const randomString = crypto.randomBytes(16).toString("hex");
3console.log(randomString)

The client secret is essentially a password that you assign to Plaid. In order to keep it secure, please follow these best practices:

• Generate the client secret in a way that makes it impossible to guess or backwards-generate. (For example, do not use a UUID as many common libraries take into account the timestamp or MAC address of the generating server.)
• Never store the client secret in plain text—always keep it encrypted or hashed.
• Make the client secret visually different from the client ID. (This reduces the risk of a user copy/paste error when handling the client ID and client secret.)

Note: The client secret must be between 8 and 256 characters long.

One way to securely generate a client secret is to follow the steps below:

1. Create a 256-bit value using a cryptographically secure pseudo random number generator (CSPRNG)
2. Convert the value from step 1 to a hexadecimal representation

Example:

1import crypto from "crypto";
2const randomString = crypto.randomBytes(32).toString("hex");
3console.log(randomString)

Once you have an OIDC-compliant server and have issued Plaid a client ID and client secret, the authorization flow occurs as follows:

1. Plaid redirects the end user to your authorization_endpoint
2. The user completes all authentication steps and you generate an authorization code
3. Plaid uses the authorization code to request an access token
4. Plaid uses the access token to:
   • Identify the user
   • Authenticate Plaid's requests to your Core Exchange API

(This flow conforms to commonly implemented patterns for the OIDC spec. Plaid welcomes partner feedback.)

When your user first initiates the process of linking their account, Plaid redirects their browser to the authorization_endpoint specified in your well-known configuration. Plaid's redirect includes the following query parameters:

Plaid's redirect:

1https://auth.firstplatypus.com/oauth2/v1/authorize?response_type=code&client_id=dc1fe34ae9e5e98147f2fd76060016a4&redirect_uri=https%3A%2F%2Fcdn.plaid.com%2Flink%2Fv2%2Fstable%2Foauth.html&state=v2.9f77edf0-a328-4501-9528-4a5f460cf770.0.0&scope=openid%20offline_access%20accounts%20transactions&prompt=login&code_challenge=4dKRcTlKg7PbBxYokEH5gbfwfXcUdvDVYVdFZniVq4s&code_challenge_method=S256

This page will be requested directly by the user's device. Your authorization endpoint must support TLS and be publicly accessible. Control of user authentication has now been handed off to you. A typical authentication flow will include a username and password submission form and a 2FA step. For partners with native mobile applications, Plaid strongly recommends enabling support for App2App and using biometric authentication to improve the user's authentication experience.

After the user completes all required authentication steps, your organization generates a temporary authorization code and redirects the user's browser back to the redirect_uri. The following query parameters must be included with the request:

Your response:

1https://cdn.plaid.com/link/v2/stable/oauth.html?code=1284918391&state=eyJvYXV0aF9zdGF0ZV

Note: If a user does not complete all the required steps (for example, if they choose to cancel rather than authorize) you should handle it as an error. See the user cancellation section for more information.

Plaid sends a request to your token_endpoint. Unlike the two previous steps, the request to the token_endpoint is a backend-to-backend call and must be authenticated. The authentication credentials consist of the client ID and client secret you issued to Plaid. The authentication method will be one of the authentication methods specified in your well-known configuration. For example, if the authentication method is set to client_secret_basic, Plaid will include a basic authentication header in its request.

Plaid will send the parameters listed in the table below in the body of the request, in application/x-www-form-urlencoded format.

Plaid's request (using basic authentication):

1curl --request POST 'https://auth.firstplatypusbank.com/oauth2/v1/token' \
2--header 'Content-Type: application/x-www-form-urlencoded' \
3--header "Authorization: Basic YzVhNTI0NWIwNjJiZjg0MjBkMTFhYjQzNjFiMjhhMTU6clZYWU9vUVM0ckhVRzc5bl80OGFs"
4--data-raw '{
5    "grant_type": "authorization_code",
6    "code": "1284918391",
7    "redirect_url": "https://cdn.plaid.com/link/v2/stable/oauth.html"
8}'

Your organization validates that the client_id, client_secret, code and redirect_uri all match the expected values. Your response must contain access_token, id_token, and refresh_token, all of which Plaid needs to later access your Core Exchange API:

Your response:

1{
2  "access_token": "agstynmdygjdghabrgraeh...",
3  "expires_in": 900,
4  "id_token": "snsyjrhvjdtvyjvsgcegaethstj...",
5  "refresh_token": "dhcsrtjsrgayvkdisfdgntshstu..."
6}

After it receives this response, Plaid has everything it needs to access your Core Exchange API.

How to handle errors that occur during the authorization flow.

If the request fails due to an incorrect, missing, invalid, or mismatched redirect_uri, notify Plaid of the error and do not redirect the user to the redirect_uri. We recommend displaying an error page to notify the user that an error has occurred.

If the user cancels the request or if the request fails for any other reason other than an incorrect URI, include the following required query parameters with the request. (Please see the OAuth spec for a complete list of possible parameters.)

If Plaid sends an expired access_token for any reason, send a 401 response with an error code of "602 not authorized".

See the table below for a full list of possible errors, as defined in the OAuth spec.

Your response:

1https://cdn.plaid.com/link/v2/stable/oauth.html?error=access_denied&state=eyJvYXV0aF9zdGF0ZV

For some use cases, Plaid needs to periodically fetch fresh data on behalf of the user. To get a new access token, Plaid makes another request to your token_endpoint with a different set of parameters.

Note: The request body will be encoded in the application/x-www-form-urlencoded format.

Plaid's request (using basic authentication):

1curl --request POST 'https://auth.firstplatypusbank.com/oauth2/v1/token' \
2--header 'Content-Type: application/x-www-form-urlencoded' \
3--header "Authorization: Basic YzVhNTI0NWIwNjJiZjg0MjBkMTFhYjQzNjFiMjhhMTU6clZYWU9vUVM0ckhVRzc5bl80OGFs"
4--data-raw '{
5    "grant_type": "refresh_token",
6    "refresh_token": "dhcsrtjsrgayvkdisfdgntshstu..."
7}'

Your response:

1{
2  "access_token": "lngarogglkcangasgabba...",
3  "expires_in": 900,
4  "id_token": "snsyjrhvjdtvyjvsgcegaethstj..."
5}

See the previous section for descriptions of these response parameters.

See the table below for a full list of possible errors that may occur during the refresh flow. (Note: These errors do not appear in the OAuth spec.)

App2app is a mechanism that allows mobile apps performing OAuth2 or OpenID Connect based authentication to offer a much simpler, faster flow if the user already has an app provided by the authorization server owner installed on their mobile device.

Follow the steps below to implement App2app with your Core Exchange API:

Set up claimed HTTPS URLs so that the OAuth redirect launches the app (if installed) instead of the mobile web page. Ensure fallback to web if the app is not installed or is not available. (For example, if the user is on a desktop.)

See the resources below for instructions on how to set up deep link URLs:

• iOS: Universal links
• Android: App Links

• Native experience (Recommended): Build a fully in-app flow whereby the users completes the authentication flow and the authorization code is issued from within the app, before redirecting back to Plaid.
• Semi-native experience (Alternative): If a fully native experience cannot be resourced we can discuss alternative options, but there will be UX trade-offs.

Plaid recommends that the data partner provides Plaid with two redirect URLs:

• An App2app flow redirect URL
• A regular web-based flow redirect URL

This allows Plaid to control the user path and isolate any issues that may arise. (For example, if a specific developer ("app") incorrectly implements the App2app flow.)