Skip to main content

OIDC Authentication

Overview​

This guide explains how to configure OIDC (OpenID Connect) authentication for Transact Explorer (TEX).

It provides detailed, step-by-step instructions, configuration examples, and guidance for integrating with external Identity Providers (e.g. Keycloak, Azure AD, WSO2) using the generic OIDC authenticator rather than the API Gateway's built-in Keycloak integration.

Prerequisites​

  • Access to an Identity Provider (e.g. Keycloak, Azure AD, WSO2)
  • Admin access to:
    • TEX configuration files
    • Identity Provider configuration
  • A deployed TEX WAR file

Step 1 — Enable OIDC Authentication​

Update the configuration in TA_Config.js:

top["AUTHENTICATION"] = "OIDC";

This switches TEX from the default authentication (e.g. Keycloak) to OIDC.

Step 2 — Configure Identity Provider Client​

Create/configure a client application in your Identity Provider.

Required URLs​

SettingExample
Root URLhttp://localhost:9089/TemenosExplorer
Redirect URIhttp://localhost:9089/TemenosExplorer/login.html
Logout Redirect URIhttp://localhost:9089/TemenosExplorer
Web Originshttp://localhost:9089

These must match your TEX deployment.

Step 3 — Retrieve OIDC Endpoints​

Locate the OpenID configuration endpoint in your Identity Provider.

Retrieve:

ParameterDescription
IssuerIdentity provider identifier
Authorisation EndpointLogin endpoint
Token EndpointToken retrieval endpoint
Logout EndpointSession termination endpoint

These endpoints are required for TEX to perform authentication handshakes.

Step 4 — Configure Role Mapping​

TEX relies on roles in the token to render screens and control access. Some providers do not include roles in the token by default — a custom role mapper is required.

Example (Keycloak)​

  1. Navigate to: Client → Client Scopes → Mappers
  2. Create a mapper:
FieldValue
Nameclient role
Mapper TypeUser Client Role
Token Claim Nameclient role
Add to ID TokenON

This ensures roles are present in the token.

Step 5 — Retrieve and Encode Public Key​

  1. Navigate to: Realm Settings → Keys
  2. Copy the public key
  3. Encode it using Base64
Original:  MIIBIjANBgkqhkiG9w0BAQEFAAOCAQ8A...
Encoded:   TUlJQklqQU5CZ2txaGtpRzl3MEJBUUVG...

Step 6 — Update OIDC XML Configuration​

Locate spring-oidc-authenticator.xml and configure the endpoints:

<beans:property name="issuer" value="https://idp.example.com/realms/tex" />
<beans:property name="authorizationEndpoint" value="https://idp.example.com/auth" />
<beans:property name="tokenEndpoint" value="https://idp.example.com/token" />
<beans:property name="logoutEndpoint" value="https://idp.example.com/logout" />
<beans:property name="pkEncoded" value="BASE64_ENCODED_KEY" />

Configure the logout redirect parameter:

<beans:property name="serverLogoutParameter" value="logoutredirect" />

Note: The logout parameter name may vary across providers.

Step 7 — Preserve Existing TEX Configuration​

Do not modify:

  • Principal claim mappings
  • Session configuration
  • Embedded TEX settings

These are required for correct operation.

Step 8 — Deploy​

Deploy:

  • Updated WAR file
  • OIDC authenticator JAR (if provided separately)

Step 9 — Runtime Behaviour​

  1. User accesses the TEX URL
  2. OIDC filter is triggered
  3. User is redirected to the Identity Provider
  4. User authenticates
  5. Token is returned to TEX
  6. TEX validates the token
  7. Access is granted based on roles in the token

Step 10 — Validation​

Verify:

  • Login redirect works correctly
  • Token is issued successfully
  • Roles are present in the token
  • UI renders correctly for each role
  • Logout completes cleanly

Example Token​

{
  "preferred_username": "user1",
  "client role": ["PAYMENT_MANAGER", "SUPERVISOR"]
}

Key Considerations​

Role Attribute Naming​

The expected claim name is client role. This may differ across Identity Providers — ensure the mapper is configured to use the same name TEX expects.

Provider Differences​

  • Endpoint structures differ across providers
  • Token formats may vary
  • Logout behaviour differs (some providers require a specific redirect parameter)

Troubleshooting​

IssueCauseResolution
Roles missing from tokenRole mapper not configuredAdd role mapper in Identity Provider
Login redirect failsWrong endpoints configuredVerify all URLs in Step 2 and Step 6
Logout failsIncorrect logout parameterSet logoutredirect in Step 6
Token validation failsWrong or malformed public keyRe-encode key using Base64 (Step 5)