Skip to main content

IBM Verify using OIDC

IBM logo

This tutorial provides step-by-step instructions for configuring Single Sign-On (SSO) between IBM Security Verify and Timbr’s ontology-based semantic layer using the OpenID Connect (OIDC) protocol.

Timbr operates as a virtual knowledge graph over existing data sources, enabling the semantic layer to securely expose business entities, relationships, and logic across identity systems, BI tools, and AI applications.

Table of Contents​

  1. Introduction
  2. Prerequisites
  3. Part 1: Configure IBM Security Verify
  4. Part 2: Configure Timbr Platform
  5. Part 3: Test the Connection
  6. Part 4: Configure Role Mapping
  7. Advanced Configuration
  8. Troubleshooting

Introduction​

About IBM Security Verify​

IBM Security Verify is IBM's cloud-native Identity-as-a-Service (IDaaS) platform that provides:

  • Single Sign-On (SSO) across applications
  • Multi-factor authentication (MFA)
  • Adaptive access policies
  • User lifecycle management
  • OIDC/OAuth 2.0 and SAML support

What You'll Achieve​

After completing this tutorial:

  • Users can log into Timbr Platform using their IBM Verify credentials
  • User accounts are automatically created on first login
  • Roles are automatically assigned based on IBM Verify groups
  • Single logout works across both platforms (optional)

Time Required​

30-45 minutes for complete setup including role mapping.

Prerequisites​

IBM Security Verify Requirements​

  • IBM Security Verify tenant (SaaS or on-premises)
  • Administrator access to IBM Verify Admin Console
  • License that supports OIDC applications

Timbr Platform Requirements​

  • Admin access to Timbr Platform server
  • HTTPS enabled on Timbr Platform (required for production)
  • Timbr Platform URL (e.g., https://timbr.yourcompany.com)
  • Ability to set environment variables

Information to Gather​

Before starting, collect:

ItemExampleWhere to Find
Timbr Platform URLhttps://timbr.company.comYour deployment
IBM Verify Tenant URLhttps://company.verify.ibm.comIBM Verify Admin Console

Part 1: Configure IBM Security Verify​

Step 1.1: Access IBM Verify Admin Console​

  1. Open your browser and navigate to your IBM Security Verify Admin Console
  2. URL format: https://<your-tenant>.verify.ibm.com/ui/admin
  3. Log in with your administrator credentials

Step 1.2: Create a New Application​

  1. In the Admin Console, navigate to Applications in the left menu
  2. Click Add application button
  3. Select Custom Application
  4. Click Add application to continue

Step 1.3: Configure Application Basics​

  1. General Settings:

    FieldValue
    Application nameTimbr Platform
    DescriptionTimbr Platform SSO Integration
    Company nameYour company name

IBM Configure Application Basics

Step 1.4: Configure Sign-On Settings​

  1. Navigate to the Sign-on tab

  2. Configure the following:

    FieldValue
    Sign-on methodOpen ID Connect 1.0
    Application URLhttps://your-timbr-domain.com
    Grant typesAuthorization code
    Send all known user attributesEnabled (optional)

IBM Configure Sign-On Settings

Step 1.5: Configure Redirect URIs​

  1. Still in the Sign-on tab, find Redirect URIs section

  2. Click Add URI

  3. Enter your Timbr redirect URI:

    https://your-timbr-domain.com/oauth-authorized/oidc

    Examples:

    • Production: https://timbr.company.com/oauth-authorized/oidc
    • Development: http://localhost:8088/oauth-authorized/oidc

  4. If using single logout, also add Sign-out redirect URIs:

    https://your-timbr-domain.com/login/

  5. Click Save

Step 1.6: Configure Client Authentication​

  1. In the Sign-on tab, find Client authentication section

  2. Enable Require PKCE verification

  3. Set Token endpoint authentication method:

    • Recommended: Client secret post
    • Alternative: Client secret basic

  4. Note this choice - you'll need it for Timbr configuration

  5. Click Save

IBM Configure Client Authentication

Step 1.7: Collect Client Credentials​

  1. In the Sign-on tab, locate the Client ID and Client secret

  2. Copy and securely store both values:

    CredentialExample Value
    Client IDa1b2c3d4-e5f6-7890-abcd-ef1234567890
    Client secretaBcDeFgHiJkLmNoPqRsTuVwXyZ123456
Important:

Store the client secret securely. You won't be able to view it again after leaving this page.

Step 1.8: Find Your Tenant's OIDC Endpoints​

  1. Your IBM Verify OIDC Discovery URL follows this pattern:

    https://<your-tenant>.verify.ibm.com/v1.0/endpoint/default/.well-known/openid-configuration

  2. Test this URL in your browser to verify it returns the OIDC configuration

  3. Note the Issuer URL from the discovery document:

    https://<your-tenant>.verify.ibm.com/v1.0/endpoint/default

To include user groups in the tokens for role mapping:

  1. Navigate to Sign-on → Attribute mappings

  2. Under Attribute name

  3. Add the following:

    FieldValue
    Attribute namegroups
    Attribute sourcegroupIds or groups (depending on your setup)

  4. Click Save

IBM Configure Token Claims

Step 1.11: Configure Entitlements (User Assignment)​

  1. Navigate to the Entitlements tab

  2. Choose how users can access this application:

    Option A: All users (simplest)

    • Select Automatic access for all users

    Option B: Specific users/groups

    • Select Select users and groups
    • Click Add and select the users or groups that should have access

  3. Click Save

Step 1.12: Verify Application Status​

  1. Ensure the application status is Enabled
  2. If disabled, toggle it to Enabled
  3. Click Save to apply all changes

Part 2: Configure Timbr Platform​

Step 2.1: Stop Timbr Platform​

# If using systemd
sudo systemctl stop timbr-platform

# If using Docker
docker-compose down

Step 2.2: Set Required Environment Variables​

Add the following environment variables to your Timbr Platform configuration:

# Enable Generic OIDC Provider
OAUTH_PROVIDER=oidc

# IBM Verify Client Credentials (from Step 1.8)
OAUTH_CLIENT_ID=a1b2c3d4-e5f6-7890-abcd-ef1234567890
OAUTH_SECRET=aBcDeFgHiJkLmNoPqRsTuVwXyZ123456

# IBM Verify Issuer URL (from Step 1.9)
OAUTH_OIDC_ISSUER=https://your-tenant.verify.ibm.com/v1.0/endpoint/default

# Enable user auto-registration
AUTH_USER_REGISTRATION=true
AUTH_USER_REGISTRATION_ROLE=editor

# Enable PKCE (must match IBM Verify configuration)
OAUTH_USE_PKCE=true

# Match the token endpoint auth method from Step 1.6
OAUTH_OIDC_AUTH_METHOD=client_secret_post

Step 2.3: Optional Environment Variables​

# Allow username/password login as backup
AUTH_WITH_USERPASS=true

# Enable single logout
OAUTH_FRONT_CHANNEL_SINGLE_LOGOUT=true

# Enable JWT signature verification
OAUTH_OIDC_VERIFY_SIGNATURE=true

# HTTPS scheme (use 'http' only for development)
OAUTH_DEFAULT_SCHEME=https

Step 2.4: Complete Configuration Example​

Here's a complete configuration for IBM Verify:

# ============================================
# Timbr Platform - IBM Security Verify OIDC
# ============================================

# Provider Configuration
OAUTH_PROVIDER=oidc

# IBM Verify Credentials
OAUTH_CLIENT_ID=a1b2c3d4-e5f6-7890-abcd-ef1234567890
OAUTH_SECRET=aBcDeFgHiJkLmNoPqRsTuVwXyZ123456

# IBM Verify OIDC Issuer
OAUTH_OIDC_ISSUER=https://company.verify.ibm.com/v1.0/endpoint/default

# Security Settings
OAUTH_USE_PKCE=true
OAUTH_OIDC_AUTH_METHOD=client_secret_post
OAUTH_OIDC_VERIFY_SIGNATURE=true
OAUTH_DEFAULT_SCHEME=https

# User Registration
AUTH_USER_REGISTRATION=true
AUTH_USER_REGISTRATION_ROLE=editor
AUTH_WITH_USERPASS=true

# Single Logout (optional)
OAUTH_FRONT_CHANNEL_SINGLE_LOGOUT=true

Step 2.5: Configure Environment Variables Location​

Docker Compose (docker-compose.yml):

services:
  timbr-platform:
    environment:
      - OAUTH_PROVIDER=oidc
      - OAUTH_CLIENT_ID=a1b2c3d4-e5f6-7890-abcd-ef1234567890
      - OAUTH_SECRET=${IBM_VERIFY_CLIENT_SECRET}
      - OAUTH_OIDC_ISSUER=https://company.verify.ibm.com/v1.0/endpoint/default
      - AUTH_USER_REGISTRATION=true
      - AUTH_USER_REGISTRATION_ROLE=editor
      - OAUTH_USE_PKCE=true
      - OAUTH_OIDC_AUTH_METHOD=client_secret_post

Systemd Service (/etc/systemd/system/timbr-platform.service):

[Service]
Environment="OAUTH_PROVIDER=oidc"
Environment="OAUTH_CLIENT_ID=a1b2c3d4-e5f6-7890-abcd-ef1234567890"
Environment="OAUTH_SECRET=aBcDeFgHiJkLmNoPqRsTuVwXyZ123456"
Environment="OAUTH_OIDC_ISSUER=https://company.verify.ibm.com/v1.0/endpoint/default"
Environment="AUTH_USER_REGISTRATION=true"
Environment="AUTH_USER_REGISTRATION_ROLE=editor"
Environment="OAUTH_USE_PKCE=true"
Environment="OAUTH_OIDC_AUTH_METHOD=client_secret_post"

Step 2.6: Start Timbr Platform​

# If using systemd
sudo systemctl daemon-reload
sudo systemctl start timbr-platform

# If using Docker
docker-compose up -d

Step 2.7: Verify Configuration Loaded​

Check the logs to confirm OIDC configuration was loaded:

# Systemd
sudo journalctl -u timbr-platform -f | grep -i oidc

# Docker
docker-compose logs -f timbr-platform | grep -i oidc

Look for messages like:

INFO - OIDC Discovery successful from https://company.verify.ibm.com/v1.0/endpoint/default/.well-known/openid-configuration

Part 3: Test the Connection​

Step 3.1: Access Timbr Login Page​

  1. Open your browser
  2. Navigate to your Timbr Platform URL (e.g., https://timbr.company.com)
  3. You should see the login page with a "Login with OIDC" button

Step 3.2: Initiate OIDC Login​

  1. Click "Login with OIDC"
  2. You will be redirected to IBM Security Verify login page

Step 3.3: Authenticate with IBM Verify​

  1. Enter your IBM Verify username (usually email)
  2. Enter your password
  3. Complete any MFA challenges if configured
  4. Click Sign In

Step 3.4: Authorize Application (First Time Only)​

If this is your first login:

  1. IBM Verify may show a consent screen
  2. Review the requested permissions
  3. Click Allow or Authorize

Step 3.5: Verify Successful Login​

  1. You should be redirected back to Timbr Platform
  2. You should now be logged in
  3. Your username should appear in the top-right corner

Step 3.6: Verify User Creation​

  1. If you have admin access, go to Manage → Access Manager
  2. Find your user account
  3. Verify:
    • Correct email address
    • Correct first and last name
    • Role is viewer (default)

Step 3.7: Test Logout​

  1. Click your username → Logout
  2. You should be logged out of Timbr
  3. If single logout is enabled, you'll also be logged out of IBM Verify

Part 4: Configure Role Mapping​

Role mapping automatically assigns Timbr roles based on IBM Verify groups.

Step 4.1: Create Groups in IBM Verify​

  1. In IBM Verify Admin Console, go to Directory → Groups

  2. Click Add group

  3. Create groups that will map to Timbr roles:

    IBM Verify GroupDescription
    timbr-adminsUsers with admin access
    timbr-editorsUsers who can edit content
    timbr-analystsUsers who can run analytics
    timbr-viewersRead-only users

  4. Click Save for each group

Step 4.2: Assign Users to Groups​

  1. Go to Directory → Users
  2. Select a user
  3. Go to the Groups tab
  4. Click Add to group
  5. Select the appropriate Timbr group(s)
  6. Click Add

Step 4.3: Verify Groups in Tokens​

Ensure the application is configured to include groups in tokens:

  1. Go to Applications → Timbr Platform
  2. Navigate to Sign-on → Token settings
  3. Verify the groups claim is added (from Step 1.10)

Step 4.4: Configure Role Mapping in Timbr​

Add these environment variables:

# Enable role mapping
OAUTH_ROLE_MAPPING_ENABLED=true

# Map IBM Verify groups to Timbr roles
OAUTH_ROLE_MAPPING={"timbr-admins": "admin", "timbr-editors": "editor", "timbr-analysts": "analyst", "timbr-viewers": "viewer"}

# Default role if no group matches
OAUTH_ROLE_MAPPING_DEFAULT=viewer

# Strategy: assign highest priority role when multiple match
OAUTH_ROLE_MAPPING_STRATEGY=highest

# Role priority (highest first)
OAUTH_ROLE_PRIORITY=admin,editor,analyst,viewer

# Claim path where groups are found
OAUTH_OIDC_ROLE_CLAIM_PATHS=groups,groupIds

Step 4.5: Alternative: Using IBM Verify Group IDs​

If IBM Verify returns group IDs instead of names:

  1. Find the group IDs in IBM Verify Admin Console:

    • Go to Directory → Groups
    • Select a group
    • Copy the Group ID from the URL or details

  2. Update the role mapping to use IDs:

OAUTH_ROLE_MAPPING={"00000000-0000-0000-0000-000000000001": "admin", "00000000-0000-0000-0000-000000000002": "editor", "00000000-0000-0000-0000-000000000003": "analyst", "00000000-0000-0000-0000-000000000004": "viewer"}

Step 4.6: Test Role Mapping​

  1. Restart Timbr Platform to apply changes
  2. Log out and log back in
  3. Check your assigned role:
    • Go to Manage → Access Manager
    • Find your user
    • Verify the correct role was assigned

Advanced Configuration​

Custom OIDC Endpoints​

If auto-discovery fails or you need custom endpoints:

# IBM Verify standard endpoint patterns
OAUTH_OIDC_AUTHORIZATION_ENDPOINT=https://your-tenant.verify.ibm.com/v1.0/endpoint/default/authorize
OAUTH_OIDC_TOKEN_ENDPOINT=https://your-tenant.verify.ibm.com/v1.0/endpoint/default/token
OAUTH_OIDC_USERINFO_ENDPOINT=https://your-tenant.verify.ibm.com/v1.0/endpoint/default/userinfo
OAUTH_OIDC_JWKS_URI=https://your-tenant.verify.ibm.com/v1.0/endpoint/default/jwks
OAUTH_OIDC_END_SESSION_ENDPOINT=https://your-tenant.verify.ibm.com/v1.0/endpoint/default/logout

IBM Verify On-Premises​

For IBM Verify Access (on-premises):

# On-premises endpoints may differ
OAUTH_OIDC_ISSUER=https://isva.company.com/mga/sps/oauth/oauth20

# You may need to set custom discovery URL
OAUTH_OIDC_DISCOVERY_URL=https://isva.company.com/mga/sps/oauth/oauth20/.well-known/openid-configuration

Additional Scopes​

Request additional information from IBM Verify:

# Default scopes: openid email profile
# Add additional scopes as needed
OAUTH_SCOPES=groups

Troubleshooting​

Issue: "redirect_uri_mismatch" Error​

Cause: The redirect URI configured in IBM Verify doesn't match what Timbr sends.

Solution:

  1. In IBM Verify Admin Console, go to your application
  2. Check Sign-on → Redirect URIs
  3. Ensure URI matches exactly:
    • Correct scheme (https)
    • Correct domain
    • Path is /oauth-authorized/oidc
    • No trailing slash
# If using HTTP for development
OAUTH_DEFAULT_SCHEME=http

Issue: "invalid_client" Error​

Cause: Client credentials are incorrect or client secret authentication method mismatch.

Solution:

  1. Verify OAUTH_CLIENT_ID is correct
  2. Verify OAUTH_SECRET is correct (regenerate if needed)
  3. Match the authentication method:
# If IBM Verify uses Basic authentication
OAUTH_OIDC_AUTH_METHOD=client_secret_basic

# If IBM Verify uses POST (default)
OAUTH_OIDC_AUTH_METHOD=client_secret_post

Issue: Discovery Failed​

Cause: Cannot reach IBM Verify discovery endpoint.

Solution:

  1. Test discovery URL manually:

    curl https://your-tenant.verify.ibm.com/v1.0/endpoint/default/.well-known/openid-configuration

  2. If it fails, check:

    • Network connectivity
    • Firewall rules
    • DNS resolution

  3. If discovery is at a different path, set custom URL:

    OAUTH_OIDC_DISCOVERY_URL=https://your-tenant.verify.ibm.com/custom/path/.well-known/openid-configuration

Issue: User Not Created​

Cause: User registration is disabled.

Solution:

AUTH_USER_REGISTRATION=true
AUTH_USER_REGISTRATION_ROLE=editor

Issue: PKCE Error​

Cause: PKCE configuration mismatch between IBM Verify and Timbr.

Solution:

  1. Check IBM Verify PKCE settings:

    • Go to application Sign-on tab
    • Note if PKCE is required

  2. Match in Timbr:

    # If PKCE is enabled in IBM Verify
    OAUTH_USE_PKCE=true

    # If PKCE is not supported
    OAUTH_USE_PKCE=false

Issue: SSL Certificate Error​

Cause: Self-signed or untrusted SSL certificate on IBM Verify.

Solution (Production):

  • Use a valid, trusted SSL certificate

Security Best Practices​

# Always use HTTPS in production
OAUTH_DEFAULT_SCHEME=https

# Enable PKCE for enhanced security
OAUTH_USE_PKCE=true

# Verify token signatures
OAUTH_OIDC_VERIFY_SIGNATURE=true

# Enable single logout for security
OAUTH_FRONT_CHANNEL_SINGLE_LOGOUT=true

IBM Verify Best Practices​

  1. Enable MFA in IBM Verify for all users
  2. Configure adaptive access policies for risk-based authentication
  3. Set session timeouts appropriately
  4. Enable audit logging in IBM Verify
  5. Restrict application access to authorized users/groups only
  6. Rotate client secrets periodically

Avoid These​

  • Using HTTP in production
  • Disabling PKCE without a valid reason
  • Disabling token signature verification
  • Storing client secrets in version control
  • Overly permissive application access

Quick Reference​

IBM Verify URLs​

ResourceURL Pattern
Admin Consolehttps://<tenant>.verify.ibm.com/ui/admin
Discoveryhttps://<tenant>.verify.ibm.com/v1.0/endpoint/default/.well-known/openid-configuration
Authorizationhttps://<tenant>.verify.ibm.com/v1.0/endpoint/default/authorize
Tokenhttps://<tenant>.verify.ibm.com/v1.0/endpoint/default/token
UserInfohttps://<tenant>.verify.ibm.com/v1.0/endpoint/default/userinfo
JWKShttps://<tenant>.verify.ibm.com/v1.0/endpoint/default/jwks
Logouthttps://<tenant>.verify.ibm.com/v1.0/endpoint/default/logout

Environment Variables Summary​

VariableRequiredDefaultDescription
OAUTH_PROVIDERYes-Set to oidc
OAUTH_CLIENT_IDYes-IBM Verify Client ID
OAUTH_SECRETYes-IBM Verify Client Secret
OAUTH_OIDC_ISSUERYes-IBM Verify Issuer URL
AUTH_USER_REGISTRATIONNotrueEnable auto user creation
AUTH_USER_REGISTRATION_ROLENoviewerDefault role for new users
OAUTH_USE_PKCENotrueEnable PKCE
OAUTH_OIDC_AUTH_METHODNoclient_secret_postToken auth method
OAUTH_ROLE_MAPPING_ENABLEDNofalseEnable group-to-role mapping
OAUTH_ROLE_MAPPINGNo{}JSON group-to-role mapping
OAUTH_OIDC_ROLE_CLAIM_PATHSNogroups,rolesToken claim paths for groups

Additional Resources​

Congratulations! 🎉 You have successfully configured Timbr Platform to use IBM Security Verify for Single Sign-On.

Last updated: January 2026