Configuring authentication (Version 5.0.0 and later)

Edit online

Learn how to configure OAuth2/OIDC authentication in Transformation Advisor for non-OpenShift Container Platform installations. Transformation Advisor supports automatic OAuth endpoint discovery using OIDC standards, which simplifies the configuration process.

Before you begin

To configure authentication, you need an OAuth2/OIDC server available.

About this task

Transformation Advisor supports two methods for configuring OAuth authentication:

  • OAuth auto-discovery (recommended): Automatically discovers and configures OAuth endpoints from your OIDC provider's discovery document. Use this method if your provider is OIDC-compliant (for example, Keycloak, Azure AD, Okta, or Auth0).
    Note: This feature is available in Transformation Advisor version 5.0.0 and later.
  • Manual configuration: Manually specify all OAuth endpoints. Use this method if your OAuth provider does not support OIDC discovery.

Procedure

OAuth auto-discovery (recommended)
  1. Stop Transformation Advisor.
    1. Navigate to the installation location and run the launch script: 
      ./launch.sh
    2. Choose Stop Transformation Advisor from the menu.
      The application stops and all services are shut down.
  2. Configure the OIDC issuer.
    1. Navigate to the scripts directory and open the security configuration file: 
      cd scripts
vi .security_config
    2. Add the following required variables to .security_config: 
      ## AUTH FLAG
APPMOD_AUTH_ENABLED=true

## OAUTH CONFIGURATION
# OIDC Issuer URL (enables auto-discovery)
TA_AUTH_OIDC_ISSUER=https://your-idp.example.com

# OAuth Client Credentials
TA_AUTH_OIDC_CLIENT_ID=your-client-id
TA_AUTH_OIDC_CLIENT_SECRET=your-client-secret
      Note: The OAuth callback URI and scope are automatically configured. The default scope is openid.
  3. Start Transformation Advisor.
    1. Run the launch script: 
      ./launch.sh
    2. Choose Start Transformation Advisor from the menu.
      The application starts with authentication enabled using your OIDC provider configuration.
  4. Optional: Verify the configuration.

    After startup, verify that all OAuth endpoints were auto-populated from the OIDC discovery document:

    # Check the configuration file
cd scripts
cat .security_config | grep TA_AUTH

# Or check environment variables (after containers are running)
env | grep TA_AUTH
    All OAuth variables are automatically configured, including endpoints discovered from your OIDC provider.
Manual configuration (alternative)

Use this method if your OAuth provider does not support OIDC discovery, or if you prefer to specify endpoints manually.

  1. Stop Transformation Advisor.
    1. Navigate to the installation location and run the launch script: 
      ./launch.sh
    2. Choose Stop Transformation Advisor from the menu.
      The application stops and all services are shut down.
  2. Create the manual security configuration.
    1. Navigate to the scripts directory and open the security configuration file: 
      cd scripts
vi .security_config
    2. Copy the environment variables from the .security_config_sample file.
      Note: Do not include comments (any string after #) when copying the environment variables.
    3. Replace the sample values with the actual values from your OAuth provider. See the Configuration reference for details on each variable.
  3. Start Transformation Advisor.
    1. Run the launch script: 
      ./launch.sh
    2. Choose Start Transformation Advisor from the menu.
      The application starts with authentication enabled using your manual OAuth configuration.
  4. Optional: Verify the configuration. 
    # Check the configuration file
cd scripts
cat .security_config | grep TA_AUTH

# Or check environment variables (after containers are running)
env | grep TA_AUTH
    All OAuth variables are present in the configuration.

Configuration reference

Required variables

Variable Description Example
APPMOD_AUTH_ENABLED Master switch to enable authentication. true
TA_AUTH_OIDC_CLIENT_ID OAuth client ID from your identity provider. my-app-client
TA_AUTH_OIDC_CLIENT_SECRET OAuth client secret from your identity provider. abc123...

Auto-discovery variables

Variable Description Example
TA_AUTH_OIDC_ISSUER OIDC issuer URL. Setting this variable enables auto-discovery of all OAuth endpoints. https://your-idp.example.com

Manual configuration variables

Variable Description Example
TA_AUTH_IDENTITY_REQUEST_ENDPOINT Base URL for the authorization endpoint. <authorization-endpoint-base-url>
TA_AUTH_IDENTITY_REQUEST_ENDPOINT_PATH Path for the authorization endpoint. <authorization-endpoint-path>
TA_AUTH_IDENTITY_REQUEST_ENDPOINT_SCOPE OAuth scopes to request. <requested-scopes>
TA_AUTH_TOKEN_REQUEST_ENDPOINT Base URL for the token endpoint. <token-endpoint-base-url>
TA_AUTH_TOKEN_REQUEST_ENDPOINT_PATH Path for the token endpoint. <token-endpoint-path>
TA_AUTH_TOKEN_VERIFICATION_ENDPOINT Base URL for the userinfo endpoint. <userinfo-endpoint-base-url>
TA_AUTH_TOKEN_VERIFICATION_ENDPOINT_PATH Path for the userinfo endpoint. <userinfo-endpoint-path>
TA_AUTH_TOKEN_REVOCATION_ENDPOINT Base URL for the token revocation endpoint. <revocation-endpoint-base-url>
TA_AUTH_TOKEN_REVOCATION_ENDPOINT_PATH Path for the token revocation endpoint. <revocation-endpoint-path>
TA_AUTH_END_SESSION_ENDPOINT Base URL for the end session (logout) endpoint. <end-session-endpoint-base-url>
TA_AUTH_END_SESSION_ENDPOINT_PATH Path for the end session (logout) endpoint. <end-session-endpoint-path>

Optional variables

Variable Description Default
TA_AUTH_CALLBACK_STATE_PREFIX_PADDING State parameter padding. Leave empty unless required by your OAuth provider. (empty)
TA_AES_IV AES initialization vector for encryption. Leave empty — auto-generated from TA_API_KEY. (empty)
TA_AES_KEY AES encryption key. Leave empty — auto-generated from TA_API_KEY. (empty)

Sample configurations

OIDC provider with auto-discovery

## HTTPS
TA_AUTH_ENABLE_TLS=true
TA_LOCAL_INTERNAL_SERVER_PORT=9443
TA_LOCAL_INTERNAL_UI_PORT=3443
TA_LOCAL_INTERNAL_DB_PORT=6984

## AUTH FLAG
APPMOD_AUTH_ENABLED=true

## OAUTH CONFIGURATION
TA_AUTH_OIDC_ISSUER=https://your-idp.example.com/realms/myrealm
TA_AUTH_OIDC_CLIENT_ID=your-client-id
TA_AUTH_OIDC_CLIENT_SECRET=your-client-secret

Box.com (manual configuration)

For providers without OIDC discovery support:

## HTTP
TA_AUTH_ENABLE_TLS=false
TA_LOCAL_INTERNAL_SERVER_PORT=9080
TA_LOCAL_INTERNAL_UI_PORT=3000
TA_LOCAL_INTERNAL_DB_PORT=5984

## AUTH FLAG
APPMOD_AUTH_ENABLED=true

## OAUTH CONFIGURATION
TA_AUTH_OIDC_CLIENT_ID=lanjmi4l41orezoiz5ektitgnfvtoi4n
TA_AUTH_OIDC_CLIENT_SECRET=1N1CRuTdxlOM5c5XvH3PT3Ijv5Eeaf9r

TA_AUTH_IDENTITY_REQUEST_ENDPOINT=https://account.box.com
TA_AUTH_IDENTITY_REQUEST_ENDPOINT_PATH=/api/oauth2/authorize
TA_AUTH_IDENTITY_REQUEST_ENDPOINT_SCOPE=root_readonly
TA_AUTH_CALLBACK_STATE_PREFIX_PADDING=

TA_AUTH_TOKEN_REQUEST_ENDPOINT=https://api.box.com
TA_AUTH_TOKEN_REQUEST_ENDPOINT_PATH=/oauth2/token

TA_AUTH_TOKEN_VERIFICATION_ENDPOINT=https://api.box.com
TA_AUTH_TOKEN_VERIFICATION_ENDPOINT_PATH=/2.0/users/me

TA_AUTH_TOKEN_REVOCATION_ENDPOINT=https://api.box.com
TA_AUTH_TOKEN_REVOCATION_ENDPOINT_PATH=/oauth2/revoke

TA_AUTH_END_SESSION_ENDPOINT=https://api.box.com
TA_AUTH_END_SESSION_ENDPOINT_PATH=/oauth2/revoke

TA_AES_IV=
TA_AES_KEY=

What to do next

Configuring the OAuth client in your identity provider

When setting up your OAuth client in your identity provider (IdP), configure the redirect URIs that Transformation Advisor will use.

Required redirect URI

For HTTP (development):

http://localhost:<port>/auth/callback

For HTTPS (production):

https://<hostname>:<port>/auth/callback

Replace <hostname> with your actual hostname or IP address, and <port> with your configured port (default: 3443 for HTTPS, 3000 for HTTP).

Required post-logout redirect URI

For HTTP (development):

http://localhost:<port>/revoked

For HTTPS (production):

https://<hostname>:<port>/revoked

Port specification best practice

When using default ports (443 for HTTPS, 80 for HTTP), register both variants in your IdP to avoid URL normalization issues. Some providers, such as Keycloak, require exact string matching of redirect URIs and may treat URLs with and without the default port as different strings.

For example, register both:

https://<hostname>/auth/callback
https://<hostname>:443/auth/callback

In your IdP's OAuth client configuration, add these URIs to the following fields:

  • Valid redirect URIs (or Authorized redirect URIs): Add the /auth/callback URI.
  • Valid post-logout redirect URIs (or Post logout redirect URIs): Add the /revoked URI.

Common Issues

  • Problem: "400 Bad Request" or "Invalid redirect URI" during login or logout.
  • Cause: The redirect URI sent by the application does not exactly match what is registered in the IdP. Ensure both URI variants (with and without the default port) are registered.

Configuring MFA

To configure Multi-Factor Authentication (MFA), verify that MFA is enabled in your identity provider (IdP). This setting must be configured at the IdP level because OAuth depends on the provider to enforce multi-factor authentication during the login flow.