Skip to content

SSO Integration Guide: Managing Applications and Identity Providers

This guide provides comprehensive instructions for tenant administrators on managing SSO integrations, applications, APIs, and identity providers through the Auth service UI.

Table of Contents

Overview

The SSO Integration section enables you to:

  • Configure applications (clients) that use your tenant for authentication
  • Manage APIs (resource servers) and their access control
  • Set up identity providers for user authentication
  • Control fine-grained permissions and roles for apps and APIs
  • Manage multi-tenancy and namespace isolation

Security context: Proper SSO configuration is critical for security. Misconfigured clients can lead to token theft, unauthorized access, or data leakage.

SSO Integration Menu Options

App Dashboard

Location: SSO Integration > App Dashboard

Purpose: Central management console for all applications (OAuth 2.0/OIDC clients and SAML service providers) integrated with your tenant.

What you can do

  • View all applications: Table displays all configured clients with their names, client IDs, assigned roles/permissions, and type
  • Create new applications: Multiple creation options:
  • Simple setup wizards (recommended for common scenarios)
  • Full configuration (advanced use cases)
  • Import from JSON
  • Edit applications: Click settings icon to open full configuration dialog
  • Delete applications: Remove unused or decommissioned apps
  • Search and filter: Find apps by name, client ID, or type
  • Export configuration: Export app settings as JSON for backup or migration

Application Types

  • OIDC Web App: Server-side web applications (authorization code flow)
  • OIDC SPA: Single-page applications (PKCE flow)
  • OIDC Native: Mobile and desktop apps (PKCE flow)
  • OIDC M2M: Machine-to-machine (client credentials flow)
  • SAML: SAML 2.0 service providers

Creating a New Application

  1. Click ADD NEW dropdown
  2. Select application type:
  3. Simple Confidential: Quick setup for server-side web apps
  4. Simple Public: Quick setup for SPAs/mobile apps
  5. Advanced: Full configuration options
  6. Fill in required information (see Application Configuration Reference)
  7. Click Save

Security recommendations:

  • Use Simple Confidential for server-side apps (more secure than public clients)
  • Enable PKCE for all SPAs and mobile apps
  • Restrict redirect URIs to known, trusted endpoints
  • Use short-lived access tokens (300-900 seconds for most use cases)
  • Rotate client secrets regularly for confidential clients

Contacts

Location: SSO Integration > Contacts

Purpose: Manage contact persons and associate them with applications for support and operational communications.

What you can do

  • Create contacts: Add contact records with name, email, phone
  • Assign contacts to applications: Link contacts to one or more apps
  • Categorize contacts: Technical, security, billing, etc.
  • Update contact information: Keep records current
  • View contact assignments: See which apps each contact is responsible for

Use cases

  • Incident response: Quick access to responsible parties during outages
  • Security notifications: Contact technical leads about vulnerabilities
  • Change management: Notify owners before making breaking changes
  • Compliance: Document responsible parties for audit purposes

Best practice: Assign at least one technical contact to every production application.

App Roles

Location: SSO Integration > App Roles

Purpose: Define coarse-grained authorization roles for applications. Roles group related permissions together.

What you can do

  • Create roles: Define roles like "viewer", "editor", "admin"
  • Assign permissions: Group multiple permissions into a role
  • Assign to users: Grant roles to users (via Users and Groups section)
  • View role assignments: See which users have which roles
  • Delete unused roles: Clean up role definitions

Role vs. Permission

  • Permission: Fine-grained access right (e.g., "read:users", "write:documents")
  • Role: Collection of permissions (e.g., "admin" might include read:, write:, delete:*)

Example role structure:

viewer:
  - read:users
  - read:documents

editor:
  - read:users
  - read:documents
  - write:documents

admin:
  - read:*
  - write:*
  - delete:*
  - manage:users

Security recommendations:

  • Follow principle of least privilege
  • Create specific roles rather than overly broad ones
  • Review role assignments quarterly
  • Document what each role grants access to

App Permissions

Location: SSO Integration > App Permissions

Purpose: Define fine-grained permissions that can be requested by applications and assigned to users.

What you can do

  • Create permissions: Define granular access rights
  • Scope permissions to apps: Control which apps can request which permissions
  • Assign to roles: Build roles from individual permissions
  • Assign to users directly: Grant specific permissions outside of roles
  • Manage permission requests: Review and approve permission grant requests

Permission Naming Convention

Use a consistent naming scheme:

  • Format: <action>:<resource>
  • Examples:
  • read:users
  • write:documents
  • delete:records
  • admin:tenant

OAuth 2.0 Scopes

Permissions in the Auth system map to OAuth 2.0 scopes. When a client requests scopes, the Auth service checks if the user has the corresponding permissions.

Security recommendations:

  • Use descriptive, clear permission names
  • Avoid overly broad permissions (e.g., admin:*)
  • Require explicit consent for sensitive permissions
  • Audit permission grants regularly

API Dashboard

Location: SSO Integration > API Dashboard

Purpose: Manage resource servers (APIs) that applications can access on behalf of users.

What you can do

  • Create APIs: Register new resource servers
  • Configure access tokens: Set token lifetime and claims
  • Assign clients: Control which apps can access the API
  • Define API-specific roles and permissions: Create RBAC for each API
  • Add custom claims: Include additional data in access tokens
  • Export configuration: Backup or migrate API settings

Creating a New API

  1. Click ADD NEW
  2. Enter API details:
  3. Name: Human-readable name (e.g., "User Management API")
  4. Identifier: Unique URI (e.g., "https://api.example.com/users")
    • Important: This becomes the aud (audience) claim in tokens
  5. Access Token Duration: Token lifetime in seconds (default: 86400 = 24 hours)
  6. Assign client applications that should have access
  7. Configure custom claims (optional, super admin only)
  8. Create API-specific roles and permissions (see tabs)
  9. Click Save

Security recommendations:

  • Use HTTPS URIs for identifiers
  • Set token lifetime based on API sensitivity (shorter for high-risk APIs)
  • Implement token validation in your API (verify signature, audience, expiration)
  • Use API-specific permissions rather than reusing app permissions

API Roles

Location: SSO Integration > API Roles

Purpose: Define authorization roles specific to individual APIs (separate from app-level roles).

What you can do

  • Create API-specific roles: Define roles scoped to one API
  • Assign permissions: Group API permissions into roles
  • Assign to users: Grant API roles to users
  • Separate concerns: Use different role sets for different APIs

API Roles vs. App Roles

  • App Roles: Global within the tenant, apply across multiple apps
  • API Roles: Scoped to a specific API resource server

Use case: A user might be an "admin" in the "User Management API" but only a "viewer" in the "Billing API".

Best practice: Create API-specific roles when different APIs have distinct authorization models.

API Permissions

Location: SSO Integration > API Permissions

Purpose: Define fine-grained permissions specific to individual APIs.

What you can do

  • Create API-specific permissions: Define granular access rights for each API
  • Scope to API: Permissions are bound to specific resource servers
  • Assign to API roles: Build API-specific roles from permissions
  • Control access tokens: Permissions appear as scopes in API access tokens

Permission Lifecycle

  1. Define API permissions (e.g., read:orders, write:orders)
  2. Group into API roles (e.g., "order-manager" = read + write)
  3. Assign roles to users
  4. Request permissions when client obtains access token
  5. Validate permissions in API when processing requests

Security recommendations:

  • Create separate permission sets for each API
  • Use API identifiers in permission names to avoid collisions
  • Require explicit user consent for sensitive API access
  • Log all permission grants and accesses

Providers

Location: SSO Integration > Providers

Purpose: Configure identity providers (IdPs) that users can authenticate with (Google, Azure AD, SAML, etc.).

What you can do

  • Add identity providers: Configure social, enterprise, or custom IdPs
  • Simple setup: Quick configuration for Google and Azure
  • Advanced setup: Full control for SAML, OIDC, OAuth2
  • Import/Export: Migrate IdP configurations
  • Clone providers: Duplicate and modify existing configurations
  • Test connections: Verify IdP integration before enabling
  • Enable/disable: Toggle IdP availability
  • Set MFA requirements: Enforce multi-factor authentication
  • Configure claims mapping: Map IdP attributes to user profiles

Supported Provider Types

  • OAuth 2.0: Generic OAuth2 providers
  • OIDC: OpenID Connect providers
  • SAML 2.0: Enterprise SAML identity providers
  • Google: Google Workspace / Gmail
  • Azure AD: Microsoft Azure Active Directory
  • LDAP: Lightweight Directory Access Protocol
  • Local: Username/password (managed by Auth service)

Adding a New Provider

Simple Setup (Google):

  1. Click ADD NEW > Simple Google
  2. Enter:
  3. Display Name: Shown to users (e.g., "Sign in with Google")
  4. Client ID: From Google Cloud Console
  5. Client Secret: From Google Cloud Console
  6. Configure:
  7. Enabled: Toggle to activate
  8. MFA Type: Optional (TOTP, Passkey)
  9. Is Trusted: Mark as verified IdP (affects MFA requirements)
  10. Click Save

Advanced Setup (Generic OIDC):

  1. Click ADD NEW > Other
  2. Select Type: "oidc"
  3. Configure:
  4. Display Name: User-facing name
  5. Identifier: Unique name for routing
  6. Issuer URL: IdP's OpenID configuration endpoint
  7. Client ID & Secret: From IdP
  8. Scopes: openid, profile, email (minimum)
  9. Claims Mapping: Map IdP claims to user attributes
  10. Test connection
  11. Click Save

SAML Configuration:

  1. Click ADD NEW > SAML
  2. Configure:
  3. Display Name: User-facing name
  4. Entity ID: IdP's entity identifier
  5. SSO URL: IdP's single sign-on endpoint
  6. Certificate: IdP's X.509 signing certificate
  7. Attribute Mapping: Map SAML assertions to user attributes
  8. Download Auth service metadata XML
  9. Upload metadata to your IdP
  10. Test SAML flow
  11. Click Save

Provider Security Settings

  • Is Trusted: Marks provider as verified/enterprise-grade
  • Affects: MFA requirements, admin access, trust boundaries
  • Recommendation: Only enable for organizationally-controlled IdPs
  • MFA Type: Enforce MFA at provider level
  • TOTP: Time-based one-time passwords
  • Passkey: WebAuthn/FIDO2 (phishing-resistant)
  • AAL Override: Override Authenticator Assurance Level
  • Super admin only: Requires elevated privilege
  • Claims Scripting: Custom JavaScript for claims transformation
  • Super admin only: Powerful but risky feature

Security recommendations:

  • Use trusted IdPs for admin accounts (marked as "Is Trusted")
  • Enable MFA for all production providers
  • Validate IdP certificates (for SAML) to prevent MITM attacks
  • Restrict callback URLs to prevent token theft
  • Use separate providers for different security levels (e.g., employee vs. customer IdPs)
  • Test thoroughly in non-production environment before enabling
  • Monitor authentication logs for unusual patterns
  • Rotate IdP credentials regularly (client secrets, certificates)

Issuers

Location: SSO Integration > Issuers

Purpose: Manage OAuth 2.0/OIDC issuer configurations that determine how tokens are generated and validated.

What you can do

  • View issuers: See configured token issuers
  • Create issuers: Define new token issuing authorities (super admin)
  • Configure token settings: Adjust token algorithms, lifetimes, claims
  • Manage issuer keys: Rotate signing keys (JWKS)
  • Set token policies: Control refresh tokens, consent requirements

Issuer Configuration

An issuer defines:

  • Issuer URL: The iss claim in tokens (e.g., https://auth.example.com)
  • Signing Algorithm: RSA256, ES256, etc.
  • Key Rotation Policy: How often signing keys change
  • Token Defaults: Default lifetimes, audiences, claims

Use case: Multi-tenant deployments may use different issuers for different tenant classes (e.g., free vs. enterprise).

Security note: Issuer configuration typically requires super admin privileges. Misconfigurations can invalidate all tokens.

Namespaces

Location: SSO Integration > Namespaces

Purpose: Logical isolation boundaries for organizing resources in multi-tenant or multi-environment setups.

What you can do

  • Create namespaces: Define logical boundaries (e.g., "prod", "dev", "customer-A")
  • Assign resources: Associate apps, APIs, users, groups with namespaces
  • Enforce boundaries: Prevent cross-namespace access
  • Manage quotas: Set resource limits per namespace
  • View namespace usage: Monitor resource consumption

Use Cases

  1. Environment separation: Isolate dev, staging, production
  2. Customer segmentation: Separate data for different customers in multi-tenant SaaS
  3. Business unit isolation: Different departments with independent resources
  4. Compliance boundaries: Separate regions/jurisdictions (GDPR, HIPAA)

Example namespace structure:

root
├── production
│   ├── apps: [web-app, mobile-app, admin-portal]
│   └── apis: [user-api, order-api, payment-api]
├── staging
│   ├── apps: [web-app-staging, mobile-app-staging]
│   └── apis: [user-api-staging]
└── development
    └── apps: [web-app-dev]

Security recommendations:

  • Use namespaces to enforce least privilege
  • Separate production from non-production namespaces
  • Apply different security policies per namespace (e.g., stricter token lifetimes in prod)
  • Audit cross-namespace access attempts

Application (Client) Configuration Reference

When creating or editing an application via App Dashboard, you'll encounter a multi-section configuration dialog. This section details each part.

Settings Section

Purpose: Core application configuration including client type, authentication flows, and token settings.

Basic Settings

  • Display Name*
  • User-facing name shown during authentication
  • Example: "My Company Web App"
  • Name
  • Internal identifier (read-only after creation)

  • Auto-generated from display name

  • Client ID

  • Unique identifier for OAuth 2.0/OIDC flows

  • Read-only (auto-generated)

  • Client Secret (Confidential clients only)

  • Secret key for authenticating the client to the Auth service
  • Critical security: Treat like a password, never expose in client-side code

  • Rotate regularly (recommendation: every 90-180 days)

  • Type*

  • oidc: OpenID Connect (most common)
  • saml: SAML 2.0 service provider

  • Selection affects available configuration options

  • Application Type*

  • web: Server-side web application (authorization code flow)
    • Uses client secret
    • Most secure for traditional web apps
  • spa: Single-page application
    • No client secret (public client)
    • Requires PKCE
  • native: Mobile or desktop application
    • No client secret
    • Requires PKCE
  • m2m: Machine-to-machine (service account)
    • Uses client credentials flow
    • No user interaction

Authentication Flow Settings

  • Grant Types
  • authorization_code: Standard OAuth 2.0 flow (recommended)
  • implicit: Legacy, not recommended (security risk)
  • client_credentials: For M2M applications
  • refresh_token: Enable refresh token issuance

  • password: Resource Owner Password Credentials (avoid if possible)

  • Response Types

  • code: Authorization code (most secure)
  • token: Implicit flow (deprecated, security risk)
  • id_token: OpenID Connect ID token
  • code id_token: Hybrid flow

Security recommendation: Use authorization_code grant type with PKCE for all client types except M2M.

Redirect URIs

  • Purpose: Whitelist of allowed callback URLs after authentication
  • Format: Exact match (no wildcards in production)
  • Examples:
  • https://myapp.example.com/callback
  • http://localhost:3000/callback (dev only)
  • com.myapp.mobile://callback (mobile deep link)

Security requirements:

  • Use HTTPS in production (not HTTP)
  • No wildcards (exact match only)
  • No open redirects (restrict to known endpoints)
  • Validate strictly: Auth service rejects tokens sent to non-whitelisted URIs

Logout URIs

  • Post Logout Redirect URIs: Where to send users after logout
  • Same security requirements as redirect URIs

Token Configuration

  • Access Token Lifetime (seconds)
  • Default: 900 (15 minutes)
  • Range: 120 - 86400 (2 minutes to 24 hours)

  • Recommendation: 300-900 seconds for most apps

  • Refresh Token Lifetime (minutes)

  • Default: 20,160 (14 days)

  • Recommendation: 7-30 days depending on security requirements

  • ID Token Lifetime (seconds)

  • Default: 3600 (1 hour)

  • ID tokens are short-lived by design

  • Absolute Session Lifetime (seconds)

  • Maximum session duration regardless of activity

  • Overrides refresh token behavior

  • Inactivity Session Lifetime (seconds)

  • Idle timeout
  • Minimum: 120 seconds

PKCE Settings (Public Clients)

  • PKCE Required
  • Always enable for SPAs and mobile apps
  • Prevents authorization code interception attacks
  • Standard: S256 (SHA-256 challenge method)
  • Require Consent
  • Force user to approve permission grants

  • Recommendation: Enable for third-party apps, optional for first-party apps

  • Show Consent on: First use, every time, or custom rules

Additional Settings

  • Enable Client Authentication

  • Require client secret for token requests (confidential clients only)

  • Enable Audience Restrictions

  • Limit which APIs this client can access

  • Backchannel Logout

  • Support OpenID Connect Back-Channel Logout specification

Metadata Section

Purpose: Additional client information for documentation and management.

  • Description: Detailed description of the application's purpose
  • Client Type: Categorization (internal, external, partner)
  • Owner Email: Contact for the application owner
  • License Assignment: Link to license records (super admin only)
  • Tenant Assignment: Associate with specific tenant (multi-tenant setups)

Default User Groups

Purpose: Automatically assign users to groups upon first authentication via this application.

Configuration

  • Auto-Assign Groups: List of groups to add users to
  • Use Case: Onboard new users automatically with baseline permissions

Example: New users signing in to "Employee Portal" are automatically added to "employees" group, which grants basic access rights.

Security note: Use carefully to avoid inadvertently granting excessive permissions.

Custom Integrations

Purpose: Configure application-specific integrations and extensions.

Available integrations (varies by application type):

  • Webhooks: Subscribe to authentication events
  • Custom Claims: Add application-specific data to tokens
  • Post-Authentication Scripts: Execute custom logic after user signs in
  • Metadata Endpoints: Expose application-specific metadata

Security warning: Custom integrations require careful validation to avoid introducing vulnerabilities.

Certificates

Purpose: Manage X.509 certificates for SAML and mutual TLS authentication.

SAML Certificates

  • Service Provider Certificate: Used to sign SAML requests/responses
  • Upload: PEM or DER format
  • Lifecycle:
  • Upload new certificate before expiration
  • Test with new certificate
  • Activate new certificate
  • Remove old certificate

OAuth 2.0 Certificates (mTLS)

  • Client Certificate: For mutual TLS client authentication
  • Use case: High-security M2M applications

Security best practices:

  • Monitor certificate expiration (check Expiring Items dashboard)
  • Use strong key sizes (minimum 2048-bit RSA)
  • Rotate certificates annually or per compliance requirements
  • Store private keys securely (HSM recommended for production)

Groups

Purpose: Assign user groups that have access to this application.

Configuration

  • Assigned Groups: Groups whose members can access the app
  • Default Access: Whether all tenant users can access (public app) or only specified groups (private app)

Use cases:

  • Private app: Limit "Admin Portal" to "admins" and "operators" groups
  • Public app: "Employee Self-Service" available to all "employees" group

Security recommendation: Use group-based access control for all production applications; avoid "all users" access.

Contacts (Application-Specific)

Purpose: Assign contacts responsible for this specific application.

  • Technical Contact: Person who maintains the application
  • Security Contact: Person to notify about security issues
  • Business Owner: Person responsible for business decisions

Best practice: Ensure every production application has at least a technical and security contact.

Allowed Origins (Application-Specific)

Purpose: Configure CORS allowed origins for this application.

Note: Typically managed at the tenant level (see Tenant Settings guide). Application-specific origins are less common.

Use case: Application needs unique CORS configuration separate from tenant defaults.

Script

Purpose: Custom claims mapping and transformation using JavaScript.

Availability: System admin or users with ADMIN_SCOPE.UPDATE_CLIENTS only.

Claims Scripting

  • Custom Claims: Add computed or mapped claims to tokens
  • Conditional Logic: Include claims based on user properties or context
  • External Data: Fetch additional data from external sources (with caution)

Example use cases:

  • Add department information to tokens based on user email domain
  • Include customer ID from external CRM system
  • Add feature flags based on user subscription tier

Security warnings:

  • High risk: Scripting can introduce vulnerabilities or performance issues
  • Validate inputs: Never trust data from external sources
  • Limit complexity: Keep scripts simple and fast
  • Test thoroughly: Broken scripts can break authentication
  • Audit changes: Log all script modifications
  • Restrict access: Only grant scripting privilege to trusted admins

Identity Provider Configuration

(This section would cover the detailed IdP configuration dialog with all provider types, claims mapping, MFA settings, etc. - expanding on the Providers section above)

Note: Due to the complexity and variety of IdP configurations, refer to provider-specific documentation:

  • Google: See "Configuring Google OAuth" guide
  • Azure AD: See "Configuring Azure AD OIDC" guide
  • SAML: See "SAML Integration Guide"
  • Custom OIDC: See "Generic OIDC Provider Setup"

Security Best Practices

Application Security

  1. Use the principle of least privilege
  2. Grant only required permissions
  3. Use fine-grained permissions over broad roles

  4. Regularly review and revoke unnecessary access

  5. Implement defense in depth

  6. Use PKCE for all public clients (SPAs, mobile)
  7. Enable client authentication for confidential clients
  8. Rotate secrets regularly
  9. Implement token validation in your applications

  10. Use short-lived access tokens

  11. Secure redirect URIs

  12. Use exact match (no wildcards)
  13. HTTPS only in production
  14. Validate on both client and server side

  15. Avoid open redirect vulnerabilities

  16. Protect client secrets

  17. Never commit to source control
  18. Store in secure vaults (e.g., AWS Secrets Manager, Azure Key Vault)
  19. Rotate every 90-180 days

  20. Monitor for exposure (secret scanning tools)

  21. Monitor and audit

  22. Review audit logs regularly
  23. Set up alerts for suspicious authentication patterns
  24. Track token issuance and validation
  25. Monitor for unusual permission grants

Identity Provider Security

  1. Vet providers carefully
  2. Only mark truly trustworthy IdPs as "Is Trusted"
  3. Prefer enterprise IdPs over social for sensitive applications
  4. Validate IdP certificates (SAML)

  5. Test thoroughly before production

  6. Enforce MFA

  7. Enable MFA requirements at provider level
  8. Use phishing-resistant MFA (WebAuthn/FIDO2) where possible

  9. Require MFA for admin accounts

  10. Secure claims mapping

  11. Validate all IdP claims
  12. Don't trust user-modifiable attributes for authorization decisions
  13. Use immutable identifiers (subject/nameID, not email)

  14. Test claims mapping with various user scenarios

  15. Manage IdP certificates

  16. Monitor expiration
  17. Rotate before expiration
  18. Validate certificate chains
  19. Use strong signing algorithms (RSA-2048 minimum, prefer RSA-4096 or ECC)

API Security

  1. Validate tokens
  2. Verify signature (use JWKS from issuer)
  3. Check audience (aud claim matches your API identifier)
  4. Verify expiration (exp claim)

  5. Validate issuer (iss claim)

  6. Implement scope-based authorization

  7. Check required scopes in API endpoints
  8. Use least privilege (narrow scopes)
  9. Separate read and write scopes

  10. Document scope requirements

  11. Use separate permission models

  12. Create API-specific permissions
  13. Don't reuse app permissions for APIs

  14. Use namespaced permissions (e.g., api:users:read)

  15. Set appropriate token lifetimes

  16. Shorter for sensitive APIs (300-900 seconds)
  17. Longer for low-sensitivity APIs (3600-7200 seconds)
  18. Balance security with user experience

Operational Security

  1. Follow change management
  2. Test configuration changes in non-production first
  3. Document all production changes
  4. Have rollback plans

  5. Notify affected parties before breaking changes

  6. Maintain contact information

  7. Keep contacts current
  8. Assign contacts to all applications
  9. Document escalation procedures

  10. Test communication channels

  11. Regularly review configuration

  12. Quarterly access reviews
  13. Remove unused applications, APIs, providers
  14. Update outdated configurations

  15. Refresh certificates before expiration

  16. Backup and disaster recovery

  17. Export critical configurations regularly
  18. Store backups securely
  19. Test restoration procedures
  20. Document recovery steps

Additional Resources

  • Tenant Administrator Guide: packages/auth/docs/guides/tenant-admin-guide.md
  • Super Admin Access Reference: packages/auth/docs/authorization/super-admin-access.md
  • Admin Roles Overview: packages/auth/docs/authorization/admin-roles.md
  • Auth API Documentation: Available via Help > Auth API Documentation in the UI

Getting Help

For assistance with SSO integration:

  1. Check audit logs for error details
  2. Test in non-production before deploying to production
  3. Review provider-specific documentation for IdP configuration
  4. Contact your super administrator for elevated privilege requests
  5. Consult API documentation for advanced scenarios

Document version: 1.0
Last updated: 2025-12-12
Target audience: Tenant Administrators