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:
The user clicks on the IDPartner Button to initiate the login/verification process.
The
origin_url
is called with the client ID and a visitor ID as query parameters.The visitor ID is a fingerprint generated by the IDPartner button, which helps identify the user based on browser properties.
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}
.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.After the user selects an identity provider from the IDPartner widget, they are redirected back to the
origin_url
with additional query parametersiss
andidp_id
, which represent the issuer URL.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)
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 acode_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 thecode_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
: Theidp_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"
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 theredirect_uri
returned from the previous step.The IDP Authorization Server redirects the user to the login and authorization prompt.
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.
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)
To obtain identity information from the IDP, the Web Application needs to use the
token_endpoint
obtained from the OpenID Provider Configuration.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.
In a sandbox environment, the Web Application should use the client secret provided by the IDPartner for authentication.
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.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.
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.
Last updated