SSO Configuration

Previous Next

This guide explains how to configure Single Sign-On (SSO) providers for TGM Manager. The application supports OAuth2, OpenID Connect (OIDC), and SAML 2.0 protocols.

Table of Contents

  1. Overview
  2. Prerequisites
  3. Adding an OAuth2/OIDC Provider
  4. Google Workspace
  5. Microsoft Azure AD
  6. Okta
  7. Generic OIDC Provider
  8. Adding a SAML Provider
  9. Azure AD SAML
  10. Okta SAML
  11. Generic SAML Provider
  12. API Reference
  13. User Provisioning
  14. Troubleshooting

Overview

TGM Manager supports enterprise SSO allowing users to authenticate using their corporate identity provider. Supported protocols:

Protocol Use Case
OAuth2 Social logins, simple authorization
OIDC Enterprise identity (Google, Azure AD, Okta)
SAML 2.0 Enterprise federation, legacy systems

How SSO Login Works

1. User clicks "Sign in with [Provider]" on login page
2. User is redirected to the identity provider (IdP)
3. User authenticates at the IdP
4. IdP redirects back to TGM Manager with authentication token
5. TGM Manager validates the token and creates a session
6. User is logged in (new account created if JIT provisioning enabled)

Prerequisites

Before configuring SSO, ensure you have:

  • Admin access to TGM Manager
  • Admin access to your identity provider (Google Admin, Azure Portal, etc.)
  • The TGM Manager base URL (e.g., https://tgm.yourcompany.com)

Callback URLs

When configuring your IdP, you'll need these callback URLs:

Protocol Callback URL
OAuth2/OIDC https://your-domain.com/auth/sso/callback/{providerId}
SAML ACS https://your-domain.com/auth/sso/saml/acs
SAML Metadata https://your-domain.com/auth/sso/saml/metadata

Adding an OAuth2/OIDC Provider

Google Workspace

Step 1: Create OAuth2 Credentials in Google Cloud Console

  1. Go to Google Cloud Console
  2. Select or create a project
  3. Navigate to APIs & Services > Credentials
  4. Click Create Credentials > OAuth client ID
  5. Select Web application
  6. Add authorized redirect URI: https://your-domain.com/auth/sso/callback/{providerId}
  7. Copy the Client ID and Client Secret

Step 2: Configure in TGM Manager

# Login as admin
TOKEN=$(curl -s -X POST https://your-domain.com/auth/local \
  -H "Content-Type: application/json" \
  -d '{"identifier": "admin@yourcompany.com", "password": "your-password"}' \
  | jq -r '.jwt')

# Create Google OIDC provider
curl -X POST https://your-domain.com/api/admin/identity-providers \
  -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "google",
    "displayName": "Sign in with Google",
    "providerType": "OIDC",
    "presetProvider": "GOOGLE",
    "clientId": "YOUR_CLIENT_ID.apps.googleusercontent.com",
    "clientSecret": "YOUR_CLIENT_SECRET",
    "discoveryUri": "https://accounts.google.com/.well-known/openid-configuration",
    "scopes": "openid profile email",
    "enabled": true,
    "jitEnabled": true,
    "autoLinkByEmail": true
  }'

Microsoft Azure AD

Step 1: Register Application in Azure Portal

  1. Go to Azure Portal
  2. Navigate to Azure Active Directory > App registrations
  3. Click New registration
  4. Enter a name (e.g., "TGM Manager SSO")
  5. Select Accounts in this organizational directory only (single tenant) or Accounts in any organizational directory (multi-tenant)
  6. Add redirect URI: https://your-domain.com/auth/sso/callback/{providerId}
  7. Click Register
  8. Copy the Application (client) ID
  9. Go to Certificates & secrets > New client secret
  10. Copy the secret value immediately (it won't be shown again)

Step 2: Configure in TGM Manager

# Create Azure AD OIDC provider
curl -X POST https://your-domain.com/api/admin/identity-providers \
  -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "azure-ad",
    "displayName": "Sign in with Microsoft",
    "providerType": "OIDC",
    "presetProvider": "AZURE_AD",
    "clientId": "YOUR_APPLICATION_CLIENT_ID",
    "clientSecret": "YOUR_CLIENT_SECRET",
    "discoveryUri": "https://login.microsoftonline.com/YOUR_TENANT_ID/v2.0/.well-known/openid-configuration",
    "scopes": "openid profile email",
    "enabled": true,
    "jitEnabled": true,
    "autoLinkByEmail": true,
    "attributeMapping": {
      "email": "email",
      "firstName": "givenName",
      "lastName": "surname",
      "displayName": "displayName"
    }
  }'

Replace YOUR_TENANT_ID with your Azure AD tenant ID.

Okta

Step 1: Create OIDC Application in Okta

  1. Log in to your Okta Admin Console
  2. Go to Applications > Create App Integration
  3. Select OIDC - OpenID Connect and Web Application
  4. Configure:
  5. Sign-in redirect URI: https://your-domain.com/auth/sso/callback/{providerId}
  6. Sign-out redirect URI: https://your-domain.com
  7. Copy the Client ID and Client Secret
  8. Note your Okta domain (e.g., dev-123456.okta.com)

Step 2: Configure in TGM Manager

curl -X POST https://your-domain.com/api/admin/identity-providers \
  -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "okta",
    "displayName": "Sign in with Okta",
    "providerType": "OIDC",
    "presetProvider": "OKTA",
    "clientId": "YOUR_CLIENT_ID",
    "clientSecret": "YOUR_CLIENT_SECRET",
    "discoveryUri": "https://YOUR_OKTA_DOMAIN/.well-known/openid-configuration",
    "scopes": "openid profile email",
    "enabled": true,
    "jitEnabled": true
  }'

Generic OIDC Provider

For any OIDC-compliant provider:

curl -X POST https://your-domain.com/api/admin/identity-providers \
  -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "custom-oidc",
    "displayName": "Corporate SSO",
    "providerType": "OIDC",
    "clientId": "YOUR_CLIENT_ID",
    "clientSecret": "YOUR_CLIENT_SECRET",
    "discoveryUri": "https://idp.yourcompany.com/.well-known/openid-configuration",
    "scopes": "openid profile email",
    "enabled": true,
    "jitEnabled": true,
    "attributeMapping": {
      "email": "email",
      "firstName": "given_name",
      "lastName": "family_name",
      "displayName": "name"
    }
  }'

If your provider doesn't support OIDC Discovery, manually specify endpoints:

curl -X POST https://your-domain.com/api/admin/identity-providers \
  -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "custom-oauth",
    "displayName": "Corporate SSO",
    "providerType": "OAUTH2",
    "clientId": "YOUR_CLIENT_ID",
    "clientSecret": "YOUR_CLIENT_SECRET",
    "authorizationUri": "https://idp.yourcompany.com/oauth/authorize",
    "tokenUri": "https://idp.yourcompany.com/oauth/token",
    "userInfoUri": "https://idp.yourcompany.com/oauth/userinfo",
    "scopes": "openid profile email",
    "enabled": true,
    "jitEnabled": true
  }'

Adding a SAML Provider

Get TGM Manager SP Metadata

First, download the Service Provider (SP) metadata to configure your IdP:

curl https://your-domain.com/auth/sso/saml/metadata > tgm-sp-metadata.xml

Or access it directly in your browser: https://your-domain.com/auth/sso/saml/metadata

SP Metadata contains: - Entity ID: tgm-manager - ACS URL: https://your-domain.com/auth/sso/saml/acs - Supported NameID formats

Azure AD SAML

Step 1: Create Enterprise Application in Azure

  1. Go to Azure Portal
  2. Navigate to Azure Active Directory > Enterprise applications
  3. Click New application > Create your own application
  4. Name it (e.g., "TGM Manager SAML")
  5. Select Integrate any other application you don't find in the gallery (Non-gallery)
  6. Click Create

Step 2: Configure SAML

  1. Go to Single sign-on > Select SAML
  2. In Basic SAML Configuration:
  3. Identifier (Entity ID): tgm-manager
  4. Reply URL (ACS URL): https://your-domain.com/auth/sso/saml/acs
  5. In Attributes & Claims, configure:
  6. emailaddress → user.mail
  7. givenname → user.givenname
  8. surname → user.surname
  9. name → user.displayname
  10. Download Certificate (Base64) from the SAML Signing Certificate section
  11. Copy the Login URL and Azure AD Identifier from Set up section

Step 3: Configure in TGM Manager

# Read the certificate file content
CERT=$(cat azure-certificate.cer)

curl -X POST https://your-domain.com/api/admin/identity-providers \
  -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "azure-saml",
    "displayName": "Sign in with Microsoft (SAML)",
    "providerType": "SAML",
    "entityId": "https://sts.windows.net/YOUR_TENANT_ID/",
    "ssoUrl": "https://login.microsoftonline.com/YOUR_TENANT_ID/saml2",
    "sloUrl": "https://login.microsoftonline.com/YOUR_TENANT_ID/saml2",
    "idpCertificate": "-----BEGIN CERTIFICATE-----\nMIIC8D...YOUR_CERT...ABC123\n-----END CERTIFICATE-----",
    "nameIdFormat": "urn:oasis:names:tc:SAML:1.1:nameid-format:emailAddress",
    "wantAssertionsSigned": true,
    "enabled": true,
    "jitEnabled": true,
    "attributeMapping": {
      "email": "http://schemas.xmlsoap.org/ws/2005/05/identity/claims/emailaddress",
      "firstName": "http://schemas.xmlsoap.org/ws/2005/05/identity/claims/givenname",
      "lastName": "http://schemas.xmlsoap.org/ws/2005/05/identity/claims/surname",
      "displayName": "http://schemas.xmlsoap.org/ws/2005/05/identity/claims/name"
    }
  }'

Okta SAML

Step 1: Create SAML Application in Okta

  1. Log in to Okta Admin Console
  2. Go to Applications > Create App Integration
  3. Select SAML 2.0
  4. Configure:
  5. Single sign-on URL: https://your-domain.com/auth/sso/saml/acs
  6. Audience URI (SP Entity ID): tgm-manager
  7. Name ID format: EmailAddress
  8. Configure attribute statements:
  9. email → user.email
  10. firstName → user.firstName
  11. lastName → user.lastName
  12. Complete the wizard and copy:
  13. Identity Provider Single Sign-On URL
  14. Identity Provider Issuer
  15. X.509 Certificate

Step 2: Configure in TGM Manager

curl -X POST https://your-domain.com/api/admin/identity-providers \
  -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "okta-saml",
    "displayName": "Sign in with Okta (SAML)",
    "providerType": "SAML",
    "entityId": "http://www.okta.com/YOUR_ENTITY_ID",
    "ssoUrl": "https://YOUR_OKTA_DOMAIN/app/YOUR_APP_ID/sso/saml",
    "idpCertificate": "-----BEGIN CERTIFICATE-----\n...YOUR_CERTIFICATE...\n-----END CERTIFICATE-----",
    "nameIdFormat": "urn:oasis:names:tc:SAML:1.1:nameid-format:emailAddress",
    "wantAssertionsSigned": true,
    "enabled": true,
    "jitEnabled": true,
    "attributeMapping": {
      "email": "email",
      "firstName": "firstName",
      "lastName": "lastName"
    }
  }'

Generic SAML Provider

For any SAML 2.0 compliant IdP:

  1. Import SP Metadata into your IdP from https://your-domain.com/auth/sso/saml/metadata

  2. Export IdP Metadata or note down:

  3. IdP Entity ID
  4. SSO URL (Single Sign-On Service URL)
  5. SLO URL (Single Logout Service URL) - optional

  6. X.509 Certificate

  7. Configure in TGM Manager:

curl -X POST https://your-domain.com/api/admin/identity-providers \
  -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "corporate-saml",
    "displayName": "Corporate Login",
    "providerType": "SAML",
    "entityId": "https://idp.yourcompany.com/saml/metadata",
    "ssoUrl": "https://idp.yourcompany.com/saml/sso",
    "sloUrl": "https://idp.yourcompany.com/saml/slo",
    "idpCertificate": "-----BEGIN CERTIFICATE-----\n...CERTIFICATE_CONTENT...\n-----END CERTIFICATE-----",
    "signingAlgorithm": "RSA_SHA256",
    "nameIdFormat": "urn:oasis:names:tc:SAML:1.1:nameid-format:emailAddress",
    "wantAssertionsSigned": true,
    "wantAuthnRequestsSigned": true,
    "enabled": true,
    "jitEnabled": true,
    "autoLinkByEmail": true,
    "attributeMapping": {
      "email": "email",
      "firstName": "givenName",
      "lastName": "sn",
      "displayName": "cn"
    }
  }'

API Reference

Public Endpoints (No Authentication)

Method Endpoint Description
GET /auth/sso/providers List available SSO providers
POST /auth/sso/authorize Initiate SSO login flow
GET /auth/sso/callback/{providerId} OAuth2/OIDC callback
POST /auth/sso/saml/acs SAML Assertion Consumer Service
GET /auth/sso/saml/metadata Get SP metadata XML

Admin Endpoints (Requires Admin Role)

Method Endpoint Description
GET /api/admin/identity-providers List all providers
GET /api/admin/identity-providers/{id} Get provider details
POST /api/admin/identity-providers Create provider
PUT /api/admin/identity-providers/{id} Update provider
DELETE /api/admin/identity-providers/{id} Delete provider
POST /api/admin/identity-providers/{id}/test Test connection
POST /api/admin/identity-providers/discover OIDC discovery
GET /api/admin/identity-providers/presets Get preset templates

Authenticated User Endpoints

Method Endpoint Description
GET /auth/sso/linked-accounts List linked SSO accounts
POST /auth/sso/link Link SSO account
DELETE /auth/sso/link/{providerId} Unlink SSO account

User Provisioning

Just-In-Time (JIT) Provisioning

When jitEnabled: true, new users are automatically created on first SSO login:

{
  "jitEnabled": true,
  "jitDefaultRoleId": 2,
  "jitDefaultProfileId": 1,
  "autoLinkByEmail": true
}
  • jitEnabled: Create new users automatically
  • jitDefaultRoleId: Role to assign to new users
  • jitDefaultProfileId: Profile to assign to new users
  • autoLinkByEmail: Link existing users by matching email

Attribute Mapping

Map IdP attributes to TGM user fields:

{
  "attributeMapping": {
    "email": "email",
    "firstName": "given_name",
    "lastName": "family_name",
    "displayName": "name",
    "phoneNumber": "phone"
  }
}

Common attribute names by provider:

Field Google Azure AD Okta SAML (typical)
Email email email email emailaddress
First Name given_name givenName firstName givenName
Last Name family_name surname lastName sn
Display Name name displayName displayName cn

Troubleshooting

Common Issues

"Invalid redirect URI" error

Cause: The redirect URI in your IdP doesn't match exactly.

Solution: Ensure the redirect URI matches exactly, including: - Protocol (https vs http) - Domain - Port (if non-standard) - Path

"Invalid state" error

Cause: The OAuth2 state parameter expired or was tampered with.

Solution: - Ensure user completes login within 10 minutes - Check for browser extensions blocking cookies

SAML "Invalid signature" error

Cause: Certificate mismatch between IdP and TGM Manager.

Solution: - Re-download the certificate from your IdP - Ensure the certificate is in PEM format - Check for line breaks in the certificate

User not created after SSO login

Cause: JIT provisioning disabled or email mismatch.

Solution: - Enable jitEnabled: true - Check attribute mapping for email - Enable autoLinkByEmail to link existing accounts

Testing Connection

Test if your provider is configured correctly:

curl -X POST https://your-domain.com/api/admin/identity-providers/1/test \
  -H "Authorization: Bearer $TOKEN"

Response: 

{
  "status": "success",
  "message": "Successfully connected to OIDC provider",
  "issuer": "https://accounts.google.com",
  "testedAt": "2026-01-25T12:00:00"
}

Viewing Audit Logs

SSO events are logged for security auditing. Check application logs for: - SSO_LOGIN_SUCCESS - Successful logins - SSO_LOGIN_FAILED - Failed login attempts - USER_PROVISIONED - New users created via JIT - ACCOUNT_LINKED - SSO accounts linked to existing users

Security Best Practices

  1. Always use HTTPS for all SSO endpoints
  2. Rotate client secrets periodically
  3. Enable assertion signing for SAML (wantAssertionsSigned: true)
  4. Restrict allowed domains if needed (allowedDomains: "yourcompany.com")
  5. Monitor audit logs for suspicious activity
  6. Test thoroughly before enabling for all users

Support

For issues or questions: - Check the troubleshooting section above - Review application logs for detailed error messages - Contact your identity provider's support for IdP-specific issues

ERP Integration Sandbox Environments