Skip to main content

Generic OIDC

Open ID Connect

This tutorial guides you through setting up Single Sign-On (SSO) for Timbr’s ontology-based semantic layer using any OpenID Connect (OIDC) compliant identity provider such as Auth0, AWS Cognito, OneLogin, Ping Identity, Authentik, Zitadel, or a custom OIDC server.

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. Step 1: Configure Your OIDC Provider
  4. Step 2: Collect Required Information
  5. Step 3: Configure Timbr Platform
  6. Step 4: Test the Connection
  7. Step 5: Configure Role Mapping (Optional)
  8. Provider-Specific Guides
  9. Troubleshooting

Introduction​

What is OIDC?​

OpenID Connect (OIDC) is a modern authentication protocol built on top of OAuth 2.0. It allows users to authenticate once with their identity provider and access multiple applications without re-entering credentials.

What You'll Achieve​

After completing this tutorial, users will be able to:

  • Log into Timbr Platform using their OIDC provider credentials
  • Automatically get assigned appropriate roles based on their groups
  • Log out from both Timbr and the OIDC provider (optional)

Time Required​

15-30 minutes depending on your OIDC provider's complexity.

Prerequisites​

Before starting, ensure you have:

  • Admin access to Timbr Platform server
  • Admin access to your OIDC provider (Auth0, Cognito, OneLogin, etc.)
  • HTTPS enabled on your Timbr Platform (required for production)
  • Timbr Platform URL (e.g., https://timbr.yourcompany.com)
  • Ability to set environment variables on the Timbr Platform server

Step 1: Configure Your OIDC Provider​

1.1 Create a New Application​

In your OIDC provider's admin console:

  1. Navigate to Applications or Clients section
  2. Click Create New Application (or similar)
  3. Choose Web Application as the application type
  4. Give it a name like "Timbr Platform"

1.2 Configure Application Settings​

Configure the following settings in your new application:

SettingValueNotes
Application TypeWeb Application / Confidential ClientNot a Single Page App or Native app
Grant TypesAuthorization CodeEnable this grant type
PKCEEnabled (S256 method)Recommended for security
Client AuthenticationEnabledGenerate a client secret

1.3 Set the Redirect URI​

This is critical - it must match exactly:

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

Examples:

  • Production: https://timbr.company.com/oauth-authorized/oidc
  • Custom port: https://timbr.company.com:8443/oauth-authorized/oidc
Important Notes:
  • Path must be exactly /oauth-authorized/oidc
  • No trailing slash
  • Match HTTP/HTTPS to your environment
  • Include port number if non-standard

1.4 Configure Logout URLs (Optional)​

If you want single logout (user logs out from both Timbr and OIDC provider):

Logout Redirect URI:

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

1.5 Configure Scopes​

Ensure these scopes are available:

  • openid (required)
  • email (required)
  • profile (required)
  • groups (optional - for role mapping)
  • roles (optional - for role mapping)

1.6 Save and Note Credentials​

After saving, note down:

  • Client ID (e.g., timbr-platform-abc123)
  • Client Secret (e.g., abc123def456...)
  • Issuer URL (e.g., https://auth.yourcompany.com)

Step 2: Collect Required Information​

2.1 Find Your OIDC Issuer URL​

The issuer URL is the base URL of your OIDC provider. Common formats:

ProviderIssuer URL FormatExample
Auth0https://{tenant}.auth0.comhttps://mycompany.auth0.com
AWS Cognitohttps://cognito-idp.{region}.amazonaws.com/{userPoolId}https://cognito-idp.us-east-1.amazonaws.com/us-east-1_ABC123
OneLoginhttps://{subdomain}.onelogin.com/oidc/2https://mycompany.onelogin.com/oidc/2
Ping Identityhttps://auth.pingone.com/{environmentId}/ashttps://auth.pingone.com/abc-123/as
Authentikhttps://{your-domain}/application/o/{slug}/https://auth.company.com/application/o/timbr/
CustomYour OIDC server URLhttps://sso.company.com

2.2 Verify Discovery Endpoint​

Test that your OIDC Discovery endpoint works:

# Replace with your issuer URL
curl https://your-issuer-url/.well-known/openid-configuration

You should see a JSON response with endpoints like:

  • authorization_endpoint
  • token_endpoint
  • userinfo_endpoint
  • jwks_uri

If this works, you can use auto-discovery (easiest)
Avoid fails, you'll need to manually configure endpoints (see Troubleshooting)

Step 3: Configure Timbr Platform​

3.1 Stop Timbr Platform​

# Stop the Timbr service
sudo systemctl stop timbr-platform

3.2 Set Environment Variables​

Add these variables to your Timbr Platform environment configuration:

Required Variables:

# Enable OIDC provider
OAUTH_PROVIDER=oidc

# Client credentials from Step 1
OAUTH_CLIENT_ID=your-client-id-here
OAUTH_SECRET=your-client-secret-here

# Issuer URL from Step 2
OAUTH_OIDC_ISSUER=https://your-issuer-url-here

Recommended Variables:

# Enable user auto-registration
AUTH_USER_REGISTRATION=true

# Default role for new users
AUTH_USER_REGISTRATION_ROLE=viewer

# Enable PKCE (recommended)
OAUTH_USE_PKCE=true

# Allow username/password login as backup
AUTH_WITH_USERPASS=true

Example Complete Configuration:

# OIDC Authentication
OAUTH_PROVIDER=oidc
OAUTH_CLIENT_ID=timbr-platform-abc123
OAUTH_SECRET=your-secret-here
OAUTH_OIDC_ISSUER=https://auth.yourcompany.com
AUTH_USER_REGISTRATION=true
AUTH_USER_REGISTRATION_ROLE=viewer
OAUTH_USE_PKCE=true
AUTH_WITH_USERPASS=true

3.3 Where to Add Environment Variables​

The location depends on your deployment:

Docker Compose: Add to your docker-compose.yml or .env file:

services:
  timbr-platform:
    environment:
      - OAUTH_PROVIDER=oidc
      - OAUTH_CLIENT_ID=your-client-id
      - OAUTH_SECRET=your-secret
      - OAUTH_OIDC_ISSUER=https://auth.yourcompany.com
      # ... other variables

Systemd Service: Add to /etc/systemd/system/timbr-platform.service:

[Service]
Environment="OAUTH_PROVIDER=oidc"
Environment="OAUTH_CLIENT_ID=your-client-id"
Environment="OAUTH_SECRET=your-secret"
Environment="OAUTH_OIDC_ISSUER=https://auth.yourcompany.com"
# ... other variables

Direct Environment: Add to your shell profile or startup script:

export OAUTH_PROVIDER=oidc
export OAUTH_CLIENT_ID=your-client-id
export OAUTH_SECRET=your-secret
export OAUTH_OIDC_ISSUER=https://auth.yourcompany.com
# ... other variables

3.4 Reload and Start Timbr Platform​

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

# If using Docker
docker-compose down
docker-compose up -d

3.5 Verify Startup​

Check logs to ensure OIDC configuration loaded successfully:

# Systemd
sudo journalctl -u timbr-platform -f

# Docker
docker-compose logs -f timbr-platform

Look for log messages like:

INFO - OIDC Discovery successful from https://auth.yourcompany.com/.well-known/openid-configuration

Step 4: Test the Connection​

4.1 Access the Login Page​

  1. Open your browser and navigate to your Timbr Platform URL
  2. You should see a login page with an "Login with OIDC" button

4.2 Test Login Flow​

  1. Click "Login with OIDC"
  2. You'll be redirected to your OIDC provider's login page
  3. Enter your credentials
  4. If prompted, approve the authorization request
  5. You'll be redirected back to Timbr Platform
  6. You should be logged in successfully

4.3 Verify User Creation​

After first login:

  1. Go to Security → List Users (if you have admin access)
  2. Verify your user was created with:
    • Correct email address
    • Correct first and last name
    • Default role (viewer)

4.4 Test Logout​

  1. Click your username → Logout
  2. You should be logged out and redirected to login page
  3. If single logout is enabled, you'll also be logged out from your OIDC provider

Step 5: Configure Role Mapping (Optional)​

Role mapping automatically assigns Timbr roles based on user groups from your OIDC provider.

5.1 Configure Groups in OIDC Provider​

First, ensure users have groups/roles assigned in your OIDC provider:

Example groups:

  • timbr-admins → Should map to Timbr admin role
  • timbr-editors → Should map to Timbr editor role
  • timbr-analysts → Should map to Timbr analyst role
  • timbr-users → Should map to Timbr viewer role

5.2 Find the Group Claim Path​

Inspect a token from your OIDC provider to find where groups are stored.

Common claim paths:

ProviderClaim PathExample
Auth0https://yournamespace/rolesCustom namespace required
AWS Cognitocognito:groupsStandard Cognito claim
OneLogingroupsStandard claim
Ping IdentitygroupsStandard claim
AuthentikgroupsStandard claim
CustomVariesCheck your token

5.3 Configure Role Mapping​

Add these environment variables:

# Enable role mapping
OAUTH_ROLE_MAPPING_ENABLED=true

# Map OIDC groups to Timbr roles (JSON format)
OAUTH_ROLE_MAPPING={"timbr-admins": "admin", "timbr-editors": "editor", "timbr-analysts": "analyst", "timbr-users": "viewer"}

# Default role if no group matches
OAUTH_ROLE_MAPPING_DEFAULT=viewer

# Strategy: highest, all, or first
OAUTH_ROLE_MAPPING_STRATEGY=highest

# Priority order for 'highest' strategy
OAUTH_ROLE_PRIORITY=admin,editor,analyst,viewer

# Claim path to find groups (comma-separated)
OAUTH_OIDC_ROLE_CLAIM_PATHS=groups

Provider-Specific Examples:

Auth0:

OAUTH_OIDC_ROLE_CLAIM_PATHS=https://mycompany.com/roles,groups
OAUTH_SCOPES=groups roles

AWS Cognito:

OAUTH_OIDC_ROLE_CLAIM_PATHS=cognito:groups

Nested Claims (Advanced):

# For complex token structures
OAUTH_OIDC_NESTED_ROLE_CLAIMS=resource_access.{client_id}.roles,realm_access.roles

5.4 Test Role Mapping​

  1. Restart Timbr Platform
  2. Log out and log back in
  3. Check your assigned roles:
    • Go to Security → List Users
    • Find your user
    • Verify the correct role was assigned based on your groups

Provider-Specific Guides​

🔷 Auth0​

Quick Setup:

OAUTH_PROVIDER=oidc
OAUTH_CLIENT_ID=your-auth0-client-id
OAUTH_SECRET=your-auth0-client-secret
OAUTH_OIDC_ISSUER=https://your-tenant.auth0.com
OAUTH_OIDC_ROLE_CLAIM_PATHS=https://your-namespace/roles,groups
AUTH_USER_REGISTRATION=true
OAUTH_USE_PKCE=true

Auth0-Specific Steps:

  1. Create a Regular Web Application in Auth0
  2. Set Allowed Callback URLs to your redirect URI
  3. Enable Authorization Code grant
  4. Create a Rule or Action to add roles to tokens:
// Auth0 Rule to add roles
function addRolesToTokens(user, context, callback) {
  const namespace = 'https://yourcompany.com/';
  context.idToken[namespace + 'roles'] = user.app_metadata.roles || [];
  context.accessToken[namespace + 'roles'] = user.app_metadata.roles || [];
  callback(null, user, context);
}
  1. Configure OAUTH_OIDC_ROLE_CLAIM_PATHS to match your namespace

🔶 AWS Cognito​

Quick Setup:

OAUTH_PROVIDER=oidc
OAUTH_CLIENT_ID=your-cognito-app-client-id
OAUTH_SECRET=your-cognito-app-client-secret
OAUTH_OIDC_ISSUER=https://cognito-idp.us-east-1.amazonaws.com/us-east-1_XXXXXXXXX
OAUTH_OIDC_ROLE_CLAIM_PATHS=cognito:groups
OAUTH_ROLE_MAPPING_ENABLED=true
OAUTH_ROLE_MAPPING={"timbr-admins": "admin", "timbr-users": "viewer"}
AUTH_USER_REGISTRATION=true
OAUTH_USE_PKCE=true

Cognito-Specific Steps:

  1. Create a User Pool in AWS Cognito (if not exists)
  2. Create an App Client with:
    • Generate client secret
    • Enable Authorization Code Grant
    • Enable PKCE
  3. Configure App client settings:
    • Callback URL: Your redirect URI
    • Sign out URL: Your logout URI
  4. Create Groups in your User Pool (e.g., timbr-admins, timbr-users)
  5. Assign users to groups
  6. Under App client settings → Hosted UI, configure scopes to include openid, email, profile

🔵 OneLogin​

Quick Setup:

OAUTH_PROVIDER=oidc
OAUTH_CLIENT_ID=your-onelogin-client-id
OAUTH_SECRET=your-onelogin-client-secret
OAUTH_OIDC_ISSUER=https://your-subdomain.onelogin.com/oidc/2
OAUTH_OIDC_ROLE_CLAIM_PATHS=groups
OAUTH_ROLE_MAPPING_ENABLED=true
OAUTH_ROLE_MAPPING={"Admin": "admin", "DataEngineer": "editor"}
AUTH_USER_REGISTRATION=true
OAUTH_USE_PKCE=true

OneLogin-Specific Steps:

  1. In OneLogin Admin, go to Applications → Add App
  2. Search for OpenID Connect (OIDC) and select it
  3. Configure:
    • Application Type: Web
    • Redirect URI: Your redirect URI
    • Login URL: Your Timbr URL
  4. Under SSO tab, configure:
    • Application Type: Web
    • Token Endpoint Auth Method: POST
  5. Under Parameters, add custom parameter for groups if needed
  6. Map OneLogin Roles to the groups claim

🟢 Ping Identity (PingOne)​

Quick Setup:

OAUTH_PROVIDER=oidc
OAUTH_CLIENT_ID=your-ping-client-id
OAUTH_SECRET=your-ping-client-secret
OAUTH_OIDC_ISSUER=https://auth.pingone.com/your-environment-id/as
OAUTH_OIDC_AUTH_METHOD=client_secret_basic
OAUTH_OIDC_ROLE_CLAIM_PATHS=groups
AUTH_USER_REGISTRATION=true
OAUTH_USE_PKCE=true

Ping-Specific Steps:

  1. In PingOne Admin Console, create a Web App application
  2. Enable Authorization Code grant type
  3. Enable PKCE
  4. Set Redirect URIs to your redirect URI
  5. Configure Token Endpoint Authentication Method to Client Secret Basic
  6. Create Groups and assign users
  7. Ensure groups are included in tokens

🟣 Authentik​

Quick Setup:

OAUTH_PROVIDER=oidc
OAUTH_CLIENT_ID=your-authentik-client-id
OAUTH_SECRET=your-authentik-client-secret
OAUTH_OIDC_ISSUER=https://authentik.yourcompany.com/application/o/timbr-platform/
OAUTH_OIDC_ROLE_CLAIM_PATHS=groups
AUTH_USER_REGISTRATION=true
OAUTH_USE_PKCE=true

Authentik-Specific Steps:

  1. Create an OAuth2/OpenID Provider in Authentik
  2. Create an Application linked to the provider
  3. Set Redirect URIs to your redirect URI
  4. Configure Client Type as Confidential
  5. Enable Authorization Code flow
  6. Under Advanced protocol settings, ensure groups are in scope
  7. Assign users to Groups in Authentik

🔴 Zitadel​

Quick Setup:

OAUTH_PROVIDER=oidc
OAUTH_CLIENT_ID=your-zitadel-client-id
OAUTH_SECRET=your-zitadel-client-secret
OAUTH_OIDC_ISSUER=https://your-instance.zitadel.cloud
OAUTH_OIDC_ROLE_CLAIM_PATHS=urn:zitadel:iam:org:project:roles
AUTH_USER_REGISTRATION=true
OAUTH_USE_PKCE=true

Zitadel-Specific Steps:

  1. Create a Project in Zitadel
  2. Create a Web Application in the project
  3. Set Redirect URIs to your redirect URI
  4. Configure Authentication Method as Code
  5. Enable PKCE
  6. Create Project Roles
  7. Assign roles to users

Troubleshooting​

Issue: "redirect_uri_mismatch" Error​

Problem: The redirect URI in your OIDC provider doesn't match what Timbr sends.

Solution:

  1. Check the exact URI Timbr is using in browser network tab or logs
  2. Ensure redirect URI in OIDC provider matches exactly:
    • Correct scheme (http vs https)
    • Correct domain
    • Correct port (if non-standard)
    • Correct path (/oauth-authorized/oidc)
    • No trailing slash
# For development on HTTP
OAUTH_DEFAULT_SCHEME=http

Issue: Discovery Endpoint Not Found​

Problem: Error message about discovery failing.

Solution: Manually configure endpoints:

# Verify the discovery URL first
curl https://your-issuer/.well-known/openid-configuration

# If it fails, set endpoints manually
OAUTH_OIDC_AUTHORIZATION_ENDPOINT=https://auth.example.com/authorize
OAUTH_OIDC_TOKEN_ENDPOINT=https://auth.example.com/oauth/token
OAUTH_OIDC_USERINFO_ENDPOINT=https://auth.example.com/userinfo
OAUTH_OIDC_JWKS_URI=https://auth.example.com/.well-known/jwks.json

Issue: Roles Not Being Assigned​

Problem: Users login successfully but don't get the correct roles.

Solution:

  1. Verify groups are in the token:
# Decode your ID token at https://jwt.io
# Look for groups/roles claims
  1. Check claim path configuration:
# Try different claim paths
OAUTH_OIDC_ROLE_CLAIM_PATHS=groups,roles,custom_roles

# For nested claims
OAUTH_OIDC_NESTED_ROLE_CLAIMS=resource_access.timbr-platform.roles
  1. Enable debug logging:
# Add to logs to see extracted roles
# Check Timbr logs for messages like:
# "Found roles in claim 'groups': ['admin', 'users']"
  1. Verify role mapping:
# Ensure OIDC group names match exactly
OAUTH_ROLE_MAPPING={"IdP-Admins": "admin"}
# If group is "IdP-Admins" in token, it should map to "admin" in Timbr

Issue: "client_secret_basic" Required​

Problem: Token endpoint returns authentication error.

Solution:

# Try different authentication method
OAUTH_OIDC_AUTH_METHOD=client_secret_basic

# Or try
OAUTH_OIDC_AUTH_METHOD=client_secret_post

Issue: PKCE Not Supported Error​

Problem: Old OIDC provider doesn't support PKCE.

Solution:

# Disable PKCE
OAUTH_USE_PKCE=false

Issue: User Not Created​

Problem: Login succeeds but user doesn't appear in Timbr.

Solution:

# Enable user registration
AUTH_USER_REGISTRATION=true
AUTH_USER_REGISTRATION_ROLE=viewer

Issue: SSL Certificate Verification Failed​

Problem: OIDC discovery fails due to SSL errors.

Solution: Fix your SSL certificate

Advanced Configuration​

Single Logout​

Enable front-channel single logout:

OAUTH_FRONT_CHANNEL_SINGLE_LOGOUT=true

This will log users out from both Timbr and the OIDC provider when they click logout.

Custom Scopes​

Request additional scopes:

OAUTH_SCOPES=groups roles custom_scope

Client Authentication Method​

Change how client authenticates:

# Use HTTP Basic Authentication
OAUTH_OIDC_AUTH_METHOD=client_secret_basic

# Use POST parameters (default)
OAUTH_OIDC_AUTH_METHOD=client_secret_post

JWT Signature Verification​

Control token verification:

# Enable verification (recommended)
OAUTH_OIDC_VERIFY_SIGNATURE=true

# Custom JWKS URI
OAUTH_OIDC_JWKS_URI=https://custom.example.com/jwks

Security Best Practices​

Recommendations​

  • Always use HTTPS in production
  • Enable PKCE (OAUTH_USE_PKCE=true)
  • Enable JWT verification (OAUTH_OIDC_VERIFY_SIGNATURE=true)
  • Store client secrets securely (environment variables, secrets manager)
  • Use strong, randomly generated client secrets
  • Rotate client secrets periodically
  • Limit scopes to only what's needed
  • Review role mappings regularly
  • Enable audit logging

Avoid the following​

  • Avoid use HTTP in production
  • Avoid commit secrets to version control
  • Avoid share client secrets
  • Avoid disable PKCE unless provider doesn't support it
  • Avoid disable JWT verification
  • Avoid use overly permissive role mappings
  • Avoid expose client credentials in logs

Next Steps​

After successfully connecting to your OIDC provider:

  1. Test with multiple users to ensure role mapping works correctly
  2. Configure additional roles based on your organization's needs
  3. Set up groups in your OIDC provider for better access control
  4. Document your setup for your team
  5. Plan for certificate rotation and secret rotation
  6. Enable audit logging for security compliance
  7. Train users on the new login process

Getting Help​

If you encounter issues:

  1. Check logs for detailed error messages
  2. Test with curl to verify OIDC endpoints are accessible
  3. Use jwt.io to decode tokens and inspect claims
  4. Contact your OIDC provider support for provider-specific issues
  5. Reach out to Timbr support for Timbr-specific issues

Congratulations! 🎉 You've successfully configured Timbr Platform to use OIDC for Single Sign-On.

Last updated: January 2026