OIDC (OpenID Connect)

OpenID Connect (OIDC) is an identity layer built on top of OAuth 2.0. It adds authentication to the authorization capabilities of OAuth, allowing applications not only to obtain access tokens, but also to verify a user’s identity and retrieve basic profile information.

When integrating with TrustBuilder using OIDC, your application can authenticate users through the Authorization Server and receive an ID Token containing identity claims about the user (e.g. name, email, unique ID). This ID Token is a signed JWT that allows your application to verify who the user is.

OIDC is commonly used in scenarios where user login is required:

Example
A user logs in to your application using their TrustBuilder credentials. After successful authentication, your app receives an ID Token confirming the user’s identity, as well as an Access Token to access APIs on their behalf.

Set up an OIDC-based integration

Login to the Admin Portal.
Go to Applications > Applications > + Set up app integration.
Select OIDC.
In General section, fill in the fields:

Parameter	Description
Name	Give your application a clear and descriptive name. This name will appear in the applications list and on authentication pages.
Description	(Optional) Add a short description for your application.
Logo	Upload an image file. The logo will be visible in the applications list and on the authentication pages.

Choose an Application Type.
It determines how your application communicates with the Authorization Server and whether it can securely store secrets.
- Regular Web App, for traditional web applications (e.g., HTML, CSS, JavaScript) accessed via browser. Choose this if your app runs on a secure server.
  - Uses Authorization Code flow.
  - Confidential Application can securely store a client secret.
- Public Application, for Single Page Applications (SPA) and mobile apps, browser extensions. Choose this if your app runs in an environment where storing secrets securely is not possible.
  - Uses the Authorization Code flow with PKCE(Proof Key for Code Exchange).
    PKCE is enabled by default, it prevents authorization code interception attacks. It can be edited.
  - Public app cannot store a client secret.
Click on Next.
Fill in the mandatory fields:

Parameter	Description
Subject Management	Select the user attribute that uniquely identifies the user. This value will be used as the `sub` claim in the ID token to identify the user. `email`: the user's email address will be used to authenticate the principal. `user_id`: the unique identifier of the user will be used to authenticate the principal. `username`: the user's username will be used to authenticate the principal. `predefined`: use this option if the subject has manually been defined. This requires manual setup via API calls to specific subject value. ⚠️ This process is not yet documented.
API & Scopes	Select which APIs (resource servers) your application can access, and the scopes (permissions) it is allowed to request. Internal API: click View to display available scopes, then select one or more to grant access to this API. Each selected scope defines a specific permission your app will request during authentication.
Authentication method	(only for Regular app) Choose how the application authenticates to the Authorization Server when exchanging the authorization code for tokens. This step, called client authentication, ensures that the request comes from a trusted application and not from a malicious source. Client secret POST: sends the client ID and secret in the request body. Client secret Basic: sends the client ID and secret in the HTTP Authorization header (Base64). Client secret JWT: authenticates using a JWT signed with the client secret. Private key JWT: authenticates using a JWT signed with a private key (asymmetric cryptography). Import the corresponding public key by uploading a `.pem` file or pasting the public key content in `.pem` format.
Redirect URIs	Specify one or more redirect URIs where users will be sent after successful authorization. These URIs will be whitelisted to receive authorization codes or access tokens. Make sure the URI(s) exactly match the values used by your application.
Policies	Select the authorization policy that defines the access rules for this application. If not created click on Create a new authorization policy. More information
Access Token	An access token is a signed JWT that allows an application to access protected resources on behalf of a user. Select the JWT signature algorithm used to sign the token: RS256: RSA signature with SHA-256 hashing - widely used and secure. RS384: RSA signature with SHA-384 hashing - stronger than RS256 but less common. RS512: RSA signature with SHA-512 hashing - highest security level, used when maximum strength is needed.

Click on Submit.
If you selected Regular Web app, copy the client secret from the pop-up. ⚠️ It will not be displayed again for security reasons.
To revoke and generate a new client secret, see Revoke client secret below.
Click on Done.
The main configuration is complete.
You can now configure your application in more detail.

Tab and parameter	Description
SECURITY SETTINGS
Authorization Code Lifetime	Set the validity period of the authorization code (in seconds). The authorization code is issued after the Resource Owner's authentication and is used by the application to request access tokens. Default: 60 seconds.
Access Token Lifetime	Set the validity period of the access token (in seconds). The access token is a signed JWT allowing the app to access protected resources on behalf of the user. Default: 900 seconds.
Certificate	Select the certificate that secures OIDC token exchanges with your application, ensuring integrity and confidentiality.
ID Token lifetime	Set the validity period of the ID token (in seconds). The ID token is issued by the Identity Provider and contains information about the authenticated user's identity. Default: 86400 seconds (24 hours).
Refresh Token	Set the validity period of the refresh token (in seconds). This token allows the application to obtain new access tokens without requiring the user to re-authenticate. Default: 86400 seconds (24 hours). Refresh tokens can also be disabled (enabled by default).
Allowed Origins	Enter the URLs or domains authorized to initiate authentication requests to the Identity Provider. This helps protect against unauthorized interception or redirection attacks.
APIS & SCOPES
OpenID Connect (OIDC) settings	Not fully functional – available soon Standard OIDC scopes are supported automatically, no need to add them. Use this parameter only for custom scopes. To add a custom scope: Click + Add new OIDC scope and claims to define which user data your application can access. Select or enter a scope name: Choose where to include the data: `token_id` (included in the ID token) `user_info` (available through the UserInfo endpoint) Select the user attributes (claims) you want to expose. Click Save.
APP SETTINGS
Consent Management	Define how user consent is handled regarding their personal data. Skip consent: if enabled, the consent page is skipped. Disabled (default) means TrustBuilder handles consent. If you skip it, your Application or Service must handle consent itself. Consent lifetime: set the duration for which the user's consent remains valid (in seconds). Default: 86,400 seconds (24 hours).

In Endpoints tab, you can copy the various endpoints:
- OIDC User Info: URL to retrieve user profile information after authentication.
- OAuth Authorization: Endpoint to initiate the OAuth authorization process (user login and consent).
- OAuth Token: Endpoint to exchange an authorization code for access and refresh tokens.
- OAuth Introspection: Endpoint to validate and inspect the status and metadata of an access token.
- OAuth Revocation: Endpoint to revoke access or refresh tokens, invalidating them.
- OAuth JWKS (JSON Web Key Set): Endpoint providing the public keys used to verify JWT signatures issued by the server.
- Well-Known URL: Metadata endpoint providing standard discovery information about the OAuth/OIDC server configuration.

Revoke a client secret

At any time you can revoke a client secret. This means … A new client secret will be genereated and display.

Be careful when you revoke your client secret, you must change it in all applications and you will no longer be able to log in with it.

To revoke a client secret:

Navigate to Access Management > Applications.
Click on your application.
Go to Credentials tab.
Click on Revoke.
Click on Revoke to confirme the action.
It cannot be undone.

The client secret is successfully revoked. A new one has been generated. Copy it as it will not be shown again for security reasons.