Open ID Connect Flow

The following steps outline the process for integrating OIDC (OpenID Connect) with IDPartner. OIDC allows your application to authenticate users through IDPartner's identity providers. This documentation will guide you through the account selection process, OIDC flow initiation, and handling the callback to obtain identity information.

Account Selection Process:

1. The user clicks on the IDPartner Button to initiate the login/verification process.

2. The origin_url is called with the client ID and a visitor ID as query parameters.

3. The visitor ID is a fingerprint generated by the IDPartner button, which helps identify the user based on browser properties.

4. The Web Application should redirect the user to the IDPartner Account Selector using the following URL: https://auth-api.idpartner.com/oidc-proxy/auth/select-accounts?client_id={clientId}&visitor_id={visitorId}.

5. Ensure that the visitor_id is always forwarded to the account selection redirect URL. If a user has previously selected a bank in a previous transaction, the visitor ID will auto-select that provider.

6. After the user selects an identity provider from the IDPartner widget, they are redirected back to the origin_url with additional query parameters iss and idp_id, which represent the issuer URL.

7. For security purposes, store the iss in a session as it will be used later during the redirect callback.

Open ID Process

Request (origin_url)

1. Request (origin_url):

   • Start the OIDC flow using the iss obtained from the previous step.

   • All identity providers in the network require PKCE security. Generate a unique string value called code_verifier and hash/encode it as a code_challenge.

   • The Web Application should pass the following parameters to initiate the OIDC flow:

     • redirect_uri: The redirect URL configured in the application.

     • code_challenge_method: The method used to verify the code challenge, typically "S256".

     • code_challenge: The hashed/encoded code challenge generated using the code_verifier.

     • state: A random string/UUID to maintain the state of the request.

     • nonce: A random string/UUID to associate with the user's authentication session.

     • scope: Scopes indicating the requested user data, e.g., "openid email address".

     • client_id: The client ID obtained from the IDPartner console.

     • identity_provider_id: The idp_id obtained from the query parameters.

     • response_type: The response type, usually "code".

     • response_mode: Indicates how the authorization response will be delivered, it must be "jwt"

2. Start the authentication flow by redirecting the user to the authorization_endpoint obtained from the OpenID Provider Configuration (accessible via {iss}/.well-known/openid-configuration), using the redirect_uri returned from the previous step.

3. The IDP Authorization Server redirects the user to the login and authorization prompt.

4. The user authenticates using one of the configured login options and may see a consent page listing the permissions the identity provider will grant to the Web Application.

5. The IDP Authorization Server redirects the user back to the Web Application with an authorization code, which is valid for one use.

Handling Callback (redirect_url)

1. To obtain identity information from the IDP, the Web Application needs to use the token_endpoint obtained from the OpenID Provider Configuration.

2. In a production environment, the Web Application should use mutual TLS (mTLS) when communicating with the token endpoint. The user needs to create a Certificate Signing Request (CSR), upload it into the IDPartner console, and receive a certificate for mTLS authentication.

3. In a sandbox environment, the Web Application should use the client secret provided by the IDPartner for authentication.

4. The web application is responsible for sending the authorization code, which should be extracted from the JWT token found in the query parameter named "response." This code, along with the application's Client ID and the necessary authentication credentials (either an mTLS certificate or client secret), should be forwarded to the token_endpoint of the IDP Authorization Server.

5. The IDP Authorization Server will respond with an access token and, if requested, additional identity information.

Table of Supported Scopes

These scopes can be configured in the Authorization request to return the following claims from the Token endpoint.

Scope	Returned Claims	Description	Example
openid	sub	Subject identifier: a consistent unique identifier for an individual.	"sub":"aceaa425-7769-4ad7-af6b-34d25623be9",
profile	birthdate, name , given_name, family_name, gender,	Returns claims that represent basic profile information.	"birthdate":"1988-08-08, "name":"John Smith", "given_name":"John", "family_name":"Smith"
address	address	Address information embedded in a separate structure.	"address": {"street_address":"4360 Dragon Dr", "locality":"Saluda", "region":"Virginia", "postal_code":"23149", "country":"US"}
email	email, email_verified	Email address.	"email":"[e-mail]"
phone	phone_number, phone_number_verified	Phone number.	"phone_number":"408-123-4567"
payment_details	payment_details	The bank instructions	{ "bankId": "125000024", "identifier": "454992210071", "identifierType": "ACCOUNT_NUMBER", "type": "US_ACH", "transferIn": true, "transferOut": true, "accountId": "g833202fb0866d0ad83472c429" }

Currently, these scopes conform to the OpenID Core standard

Security Proofs

To enhance the security of your OIDC integration with IDPartner, it is important to understand and implement essential security proofs. This section provides an explanation of three key security proofs: State, Nonce, and Code Verifier (for PKCE).

These measures protect against CSRF attacks, replay attacks, and authorization code interception attacks, ensuring the integrity and safety of your authentication process.

State

The state parameter in OAuth helps prevent Cross-Site Request Forgery (CSRF) attacks by associating a unique and non-guessable value with each authentication request, which is stored and compared during the redirect back to the application.

Nonce

Nonce is a security measure that guards against replay attacks by tying each ID Token to a specific client session, ensuring that the token cannot be maliciously reused.

Code Verifier (for PKCE)

Code Verifier, used in Proof Key for Code Exchange (PKCE), prevents Authorization Code Interception Attacks by acting as a shared secret between the requesting app and the token exchange endpoint, ensuring that a malicious app cannot successfully exchange the intercepted authorization code without the verifier.