Skip to content

Tenant Administrator Guide: Managing Tenant Settings

This guide provides comprehensive instructions for tenant administrators on managing tenant settings through the Auth service UI.

Table of Contents

Overview

As a tenant administrator, you have comprehensive control over your tenant's authentication and authorization settings, branding, and user experience. This guide covers all configuration options available through the Auth UI.

Note: Some features may be restricted to super administrators only, or may require elevated admin scopes. These restrictions are noted throughout this guide.

Accessing Tenant Settings

  1. Log in to the Auth UI
  2. Select your tenant from the tenant dropdown in the top navigation
  3. Navigate to the Tenant section in the left navigation menu
  4. Select the desired option from the submenu

The Tenant menu includes:

  • Dashboard
  • Expiring Items
  • Settings
  • System Notifications
  • Login Metrics
  • Usage Report

Tenant Menu Options

Dashboard

Location: Tenant > Dashboard

Purpose: Provides an overview of your tenant's current status and key metrics.

What you can do:

  • View tenant summary information
  • Monitor key statistics
  • Access quick links to common tasks

Expiring Items

Location: Tenant > Expiring Items

Purpose: Monitor items that are approaching expiration to ensure continuity of service.

What you can monitor:

  • Expiring certificates (SAML, X.509)
  • Expiring access grants
  • Other time-sensitive configurations

Best practice: Review this page regularly to avoid service disruptions from expired credentials.

Settings (Edit Tenant Dialog)

Location: Tenant > Settings

Purpose: Comprehensive tenant configuration via a multi-tab dialog.

Click the Edit button on the Tenant Details page to open the tenant settings dialog, which contains 11 configuration tabs (detailed below).

System Notifications

Location: Tenant > System Notifications

Purpose: Manage tenant-wide system notifications displayed to users.

What you can do:

  • Create system-wide notifications
  • Schedule notification display periods
  • Configure notification visibility

Security note: Creating global (cross-tenant) notifications requires super admin privileges.

Login Metrics

Location: Tenant > Login Metrics

Purpose: View real-time and historical login metrics powered by Grafana.

What you can see:

  • Login success/failure rates
  • Authentication method usage
  • Geographic distribution of logins
  • Time-series charts and trends

Use case: Monitor for unusual authentication patterns that may indicate security issues.

Usage Report

Location: Tenant > Usage Report

Purpose: View detailed usage statistics for your tenant's SSO integrations.

What you can see:

  • Active users per application
  • Authentication volume by client
  • Identity provider usage
  • Session statistics

Use case: Optimize your SSO configuration based on actual usage patterns.

Edit Tenant Dialog - Tab Reference

Access the Edit Tenant dialog by navigating to Tenant > Settings and clicking the Edit button.

Settings Tab

Purpose: Configure core tenant properties and session management.

Basic Information

  • Display Name* (required)
  • The human-readable name shown to users
  • Must contain at least one alphabetic character

  • Used in UI displays and user-facing communications

  • Name

  • The tenant's unique identifier (tenantId)
  • Read-only after creation

  • Maximum 50 characters

  • ID

  • Internal numeric identifier

  • Read-only (automatically assigned)

  • Description* (required)

  • Detailed description of the tenant's purpose
  • Maximum 1024 characters

  • Helpful for documenting tenant usage

  • Visibility

  • Public: Tenant is searchable by anonymous users
  • Private: Tenant is hidden from public tenant lists

  • Security recommendation: Use Private for production tenants unless public discovery is required

  • Logo

  • Upload a custom logo for your tenant
  • Displayed in the tenant selector and branding elements
  • Supported formats: PNG, JPEG, SVG

Session Management

  • Session Lifetime (seconds)
  • Overall maximum session duration
  • Default: 3600 seconds (1 hour)
  • Controls the absolute maximum time a user can remain authenticated

  • Security recommendation: Set based on your security requirements; shorter is more secure

  • Idle Session Lifetime (seconds)

  • Timeout duration for inactive sessions
  • Minimum: 120 seconds (2 minutes)
  • Default: 1200 seconds (20 minutes)
  • Triggers automatic logout after period of inactivity

  • Security note: Users receive a warning 5 minutes before expiration (or 1 minute for sessions ≤5 minutes)

  • Refresh Token Lifetime (minutes)

  • How long refresh tokens remain valid
  • Default: 20,160 minutes (14 days)

  • Allows users to obtain new access tokens without re-authenticating

  • Time Zone

  • Tenant's default timezone for timestamps and scheduling
  • Used in audit logs, expiration calculations, and UI displays

Security Features

  • Enable Admin MFA
  • Enforces multi-factor authentication for all tenant admins and system admins
  • Security recommendation: Always enable for production tenants

  • Applies tenant-wide to all users with admin privileges

  • Always Require MFA When Set

  • Enforces MFA for all users who have already configured it
  • Applies to all clients in the tenant

  • Use case: Enforce consistent MFA usage after initial opt-in period

  • Enable TOTP Reset Requests

  • Enables the TOTP reset request workflow
  • Allows users to request assistance with lost TOTP devices

  • Exposes TOTP reset endpoints and login features

  • TOTP Reset Link Expiry (minutes)

  • How long TOTP reset links remain valid
  • Default: 15 minutes

  • Only visible when TOTP reset is enabled

  • TOTP Strike Count

  • Maximum failed TOTP attempts before account lockout
  • Default: 5 attempts

  • Security recommendation: Keep at 3-5 attempts

  • TOTP Lockout Period (minutes)

  • Duration of account lockout after exceeding strike count
  • Default: 2 minutes
  • Security note: Protects against brute-force attacks

Advanced Features

  • Enable Command Terminal
  • Enables the web-based CLI terminal feature
  • Availability: Only shown if configured at the platform level

  • Security note: Grants direct CLI access; use with caution

  • User Supplied Attributes

  • Define custom user attributes that clients can request
  • Configured as JSON array with validation rules
  • Format: 
    [
  {
    "name": "attribute_name",
    "required": true,
    "tooltip": "attribute tooltip",
    "validator": "text|number|date|email|url",
    "minLength": 4,
    "maxLength": 20,
    "inputType": "single|multi-line"
  }
]

Audit Log Retention Settings

  • Enable Custom trimByDate Trim Job Settings
  • Customize audit log retention by age

  • Age Limit (days): Number of days to retain audit logs

  • Enable Custom trimBySize Trim Job Settings

  • Customize audit log retention by volume
  • Check Number: Number of records to evaluate
  • Trim Ratio: Proportion of records to remove when threshold is reached (0.0 to 1.0)

Security recommendation: Balance compliance requirements with storage costs; retain audit logs for at least 90 days for most compliance frameworks.

Branding Tab

Purpose: Customize the visual appearance of your tenant's authentication pages and email communications.

Availability: Requires tenant admin or super admin privileges.

Tenant Icon

  • Purpose: Logo displayed in tenant selector and branding elements
  • Supported formats: PNG, JPEG, SVG
  • Recommended size: 200x200 pixels minimum for optimal quality
  • Preview: Live preview shows how the icon will appear

Email Branding

Configure the appearance of system-generated emails sent to users.

  • Email Header Background Color
  • Background color for email header section
  • Default: #01336f (blue)

  • Visual color picker with live preview

  • Email Header Text Color

  • Text color for email header
  • Default: #ffffff (white)

  • Ensure sufficient contrast with header background

  • Email Body Text Color

  • Color for email body text

  • Default: #333333 (dark gray)

  • Font Family

  • Typography for email content
  • Default: Roboto, Helvetica, Arial, sans-serif

  • Options: System font stacks for cross-client compatibility

  • Font Size

  • Base font size for email content

  • Default: 14px

  • Email Header Title

  • Title text displayed in email header
  • Default: Single Sign-On System Message

  • Maximum: 100 characters

  • Email Template Logo (Super Admins Only)

  • Modify the logo used in email templates
  • Restriction: Only super administrators can edit system logo
  • Separate from tenant icon

Email Preview: Live preview pane shows how emails will appear with current settings.

Best practices:

  • Test emails after changing branding settings
  • Ensure colors meet WCAG accessibility guidelines (4.5:1 contrast ratio minimum)
  • Use your organization's brand colors for consistency

Login Page Tab

Purpose: Customize the login page appearance and behavior.

Availability: Requires auth.clients.list or auth.clients.update scope (or tenant admin bypass).

Background and Panels

  • Background Images
  • Upload one or more background images for login page rotation
  • Supports multiple images for variety

  • Recommended size: Full HD (1920x1080) or higher

  • Panel Banner

  • Image displayed at the top of the login panel
  • Single image selection

  • Use case: Organization logo or branding header

  • Footer

  • Image displayed in the login page footer
  • Single image selection
  • Use case: Partner logos, compliance badges

Disclaimer Settings

  • Enable Disclaimer
  • Displays a mandatory acceptance dialog before login

  • Use case: Terms of service, acceptable use policies

  • Disclaimer Text

  • Content of the disclaimer message
  • Maximum: 4000 characters

  • Supports plain text

  • Disclaimer Expiration Days

  • How often users must re-accept the disclaimer
  • Compliance note: Some regulations require periodic re-acceptance

Page Text Customization

  • Title
  • Main heading displayed on the login page

  • Example: "Welcome to [Organization] SSO"

  • Description

  • Subheading or descriptive text

  • Example: "Sign in with your organizational credentials"

  • Login Options Title

  • Text shown above identity provider buttons
  • Example: "Choose your login method"

Template Configuration

  • Do not skip login page
  • When enabled, always shows the login page even when only one identity provider is configured
  • When disabled (default), users are redirected directly to the IdP if only one option exists

  • Use case: Enable if you need users to always see disclaimers or custom messaging

  • Select a template

  • Choose from predefined HTML templates or create custom templates
  • System templates: Marked with a red "System" tag; only super admins can edit

  • Actions:

    • Create (+): Create a new HTML template
    • Edit (pencil): Modify the current template (disabled for system templates unless you're a super admin)
    • Preview (eye): Preview the template in a new window

  • Custom FooterLinks JSON

  • Define footer links as a JSON array
  • Format: 
    [
  {
    "name": "text displayed for the link",
    "title": "title attribute",
    "href": "href attribute: the destination URL"
  }
]
  • Example use cases: Privacy policy, terms of service, support links

Security recommendation: Test login page changes in a non-production tenant first to avoid accidentally blocking user access.

Landing Page Tab

Purpose: Configure the post-authentication landing page users see after successful login.

Availability:

  • May be restricted by global configuration
  • Typical access: Tenant admins and/or super admins (configurable)
  • The tab will be hidden if landing pages are globally disabled

Note: If you see an "Access Restricted" message when clicking this tab, landing page edits may be limited to super administrators only per global policy.

Landing Page Configuration

  • Name* (required)
  • Unique identifier for this landing page template

  • Read-only for system templates

  • Title

  • Page title displayed in browser tab and header

  • Is System Template?

  • Toggle to mark this template as a system template
  • Restriction: Requires super admin or ADMIN_SCOPE.UPDATE_SYSTEM_TEMPLATES

  • System templates can be shared across tenants

  • Custom FooterLinks JSON

  • Same format as Login Page footer links

  • Allows users to navigate to documentation, dashboards, etc. after login

  • Template (HTML)

  • Custom HTML for the landing page
  • Monaco editor with syntax highlighting and validation
  • Preview button: Opens a new window to preview the rendered page
  • Best practice: Use semantic HTML and ensure mobile responsiveness

Use cases:

  • Welcome messages for users
  • Links to applications and resources
  • Onboarding instructions
  • Organizational announcements

Allowed Origins Tab

Purpose: Manage Cross-Origin Resource Sharing (CORS) allowed origins for your tenant.

Critical security feature: Only origins listed here can make authenticated API requests to the Auth service from browser-based applications.

Adding Allowed Origins

  1. Enter the full origin URL (scheme + host only, no path)
  2. Valid: https://myapp.example.com

  3. Invalid: https://myapp.example.com/path, myapp.example.com (missing scheme)

  4. Global checkbox (Super Admins Only):

  5. Mark origin as global (applies to all tenants)

  6. Restriction: Only super administrators can create global origins

  7. Click Add to save

Origin Validation Rules

The system enforces strict origin validation:

  • Must include scheme (https:// or http://)
  • Must not include path, query parameters, or hash fragments
  • Must not include credentials (username:password@host)
  • Must not have leading/trailing whitespace
  • Must not duplicate existing origins

Managing Existing Origins

  • View origins: Table displays all allowed origins for the tenant (includes tenant-specific and global origins)
  • Delete origins: Click the delete icon to remove (config-defined origins cannot be deleted via UI)
  • Global column: Indicates whether an origin is global or tenant-specific

Advanced Features (Super Admins Only)

  • Allow-list Enabled toggle
  • When disabled, CORS allow-list enforcement is bypassed (any origin allowed for non-public endpoints)
  • Security warning: Only disable temporarily for troubleshooting

  • Default: Enabled

  • Discovery Mode toggle

  • Logs all incoming origins to help identify what needs whitelisting
  • Only works when allow-list is disabled

  • Use case: Transition from permissive to restrictive CORS policy

  • Refresh button: Clears the server-side CORS cache to apply changes immediately

Security Best Practices

  1. Only add origins you control and trust
  2. Use HTTPS origins (not HTTP) for production applications
  3. Avoid wildcards - list each origin explicitly
  4. Remove unused origins to minimize attack surface
  5. Monitor the Audit Log for origin changes (critical security event)
  6. Never disable allow-list enforcement in production unless absolutely necessary and time-limited

User Alert Settings Tab

Purpose: Configure which login events trigger user email notifications.

What you can configure:

  • Select which login event types should generate email alerts to users
  • Available event types include:
  • Login success
  • Login failure
  • MFA challenge events
  • Password reset events
  • And other authentication-related events

Use cases:

  • Alert users about suspicious login attempts
  • Notify users of successful logins from new devices
  • Compliance requirements for security event notifications

Best practice: Balance security notifications with alert fatigue; focus on high-risk events (failed logins, new device logins).

Email Settings Tab

Purpose: Configure SMTP settings for sending tenant-specific emails.

Availability: Tenant admin or super admin only (tab is hidden for non-admin users).

Note: The default tenant uses system-wide email settings and cannot be overridden.

Default vs. Custom Email Settings

  • Use Default Email Settings toggle
  • When enabled: Inherits email configuration from the default tenant
  • When disabled: Allows custom SMTP configuration
  • Recommendation: Use default settings unless you have specific requirements

Custom SMTP Configuration

Available when "Use Default Email Settings" is disabled:

  • Host
  • SMTP server hostname

  • Example: smtp.example.com

  • Port

  • SMTP server port

  • Common: 587 (TLS), 465 (SSL), 25 (unencrypted - not recommended)

  • Secure

  • Enable SSL/TLS connection

  • Recommendation: Always enable for production

  • Require TLS

  • Enforce TLS for connection (STARTTLS)

  • Security recommendation: Enable in production environments

  • User

  • SMTP authentication username

  • Must not contain whitespace

  • Password

  • SMTP authentication password
  • Must not contain whitespace
  • Security note: Stored encrypted; never displayed after saving

Email Appearance

  • From
  • Sender email address for tenant emails
  • Must be a valid email format
  • Leave blank to use the default sender address

Testing Email Configuration

  • Test Email Address
  • Enter a valid email address to test your SMTP configuration
  • Click Send Test Email to verify settings
  • Success confirmation shown inline

Best practices:

  • Test email settings after any changes
  • Use a dedicated sending address (e.g., noreply@yourdomain.com)
  • Ensure SPF/DKIM records are configured for your sending domain to avoid spam filtering

Tenant SAML Certificates Tab

Purpose: Manage X.509 certificates used for SAML authentication.

What you can do:

  • View certificates: See all uploaded X.509 certificates for your tenant
  • Upload certificates: Add new certificates for SAML signing/encryption
  • Set active certificate: Designate which certificate is currently in use
  • Update friendly names: Label certificates for easy identification
  • Delete unused certificates: Remove expired or unused certificates

Security requirements:

  • Updating certificate names: Requires tenant admin or super admin
  • Certificates are used to establish trust with SAML identity providers

Certificate lifecycle:

  1. Upload new certificate before the old one expires
  2. Test with new certificate
  3. Set new certificate as active
  4. Monitor for issues
  5. Remove old certificate only after confirming stability

Security best practices:

  • Monitor certificate expiration (check Expiring Items dashboard)
  • Rotate certificates before expiration (recommend 30-60 days before)
  • Use strong key sizes (minimum 2048-bit RSA, prefer 4096-bit or ECC)
  • Protect private keys - never share or expose them

Tenant JWKS Key Set Tab

Purpose: Manage JSON Web Key Sets (JWKS) used for JWT signing and verification.

What you can do:

  • View current JWK: See the active JSON Web Key and any revoked keys
  • Rotate JWK: Generate a new JWK while keeping the old one valid (smooth transition)
  • Rotate and Revoke JWK: Generate a new JWK and immediately revoke the old one
  • Revoke specific JWK: Revoke a key by its Key ID (kid)

Operations

  1. Rotate JWK (recommended)
  2. Generates a new key
  3. Previous key remains valid temporarily
  4. Allows zero-downtime key rotation

  5. Use case: Regular key rotation schedule

  6. Rotate and Revoke JWK (immediate revocation)

  7. Generates new key
  8. Immediately invalidates the old key
  9. All tokens signed with old key become invalid

  10. Use case: Security incident or suspected key compromise

  11. Revoke JWK (by kid)

  12. Revokes a specific key
  13. Use case: Targeted key invalidation

Security best practices:

  • Rotate JWKs regularly (every 90-180 days for routine rotation)
  • Use "Rotate" not "Rotate and Revoke" for scheduled rotations to avoid service disruption
  • Document key rotation in audit trail
  • Use "Rotate and Revoke" only for emergencies (key compromise, security incident)
  • Monitor revoked keys list to ensure old keys are eventually cleaned up

Purpose: Configure GDPR/privacy-compliant cookie consent banners.

Compliance context: Required for GDPR, ePrivacy Directive, and similar privacy regulations.

  • Enable Cookie Consent Message
  • Shows/hides the cookie consent banner on login pages

  • Compliance note: Required for EU users and recommended globally

  • Cookie Consent Expiration (days)

  • How long user consent is remembered
  • Default: 150 days

  • After expiration, users must accept again

  • Cookie Consent Message

  • Text displayed in the consent banner
  • Supports rich text formatting (via Summernote editor)
  • Default: "We use cookies to ensure that you have the best experience on our website. If you continue to use this site we assume that you accept this."
  • Legal recommendation: Include link to privacy policy
  • Cookie Consent Banner Color
  • Background: Banner background color (default: #2B373B)
  • Text: Banner text color (default: #FFFFFF)

  • Live preview shows actual appearance

  • Cookie Consent Button Color

  • Background: Accept button background (default: #e7db08)
  • Text: Accept button text color (default: #000000)

  • Live preview shows button appearance

  • Cookie Consent Button Text

  • Text on the accept button
  • Default: Accept
  • Keep short and clear (e.g., "Accept", "OK", "I Understand")

Best practices:

  • Ensure text is readable - verify color contrast meets accessibility standards
  • Keep message concise - users should understand quickly
  • Include privacy policy link in the consent message
  • Set appropriate expiration - balance user experience with regulatory requirements (typically 6-12 months)

Contacts Tab

Purpose: Manage contact information associated with the tenant.

Availability: View-only for regular users; editing requires tenant admin or super admin.

What you can do:

  • Add contacts: Create new contact records for the tenant
  • Assign contact types: Categorize contacts (e.g., technical contact, security contact, billing contact)
  • Update contact details: Modify name, email, phone number
  • Remove contacts: Delete obsolete contact records

Contact fields:

  • Name: Contact person's full name
  • Email: Contact email address (validated format)
  • Phone Number: Contact phone number
  • Contact Type: Role or purpose of this contact

Use cases:

  • Emergency security contacts
  • Technical escalation contacts
  • Service notifications
  • Compliance and auditing

Best practice: Keep contact information current; designate at least one technical and one security contact per tenant.

Security Recommendations

Critical Security Controls

  1. Always enable Admin MFA
  2. Protects against credential theft

  3. Required for compliance in most frameworks

  4. Use short session lifetimes

  5. Recommend: 1 hour maximum session, 20 minutes idle timeout

  6. Shorter for high-security tenants

  7. Restrict allowed origins

  8. Only add origins you control
  9. Use HTTPS (never HTTP in production)

  10. Remove unused origins immediately

  11. Monitor admin actions

  12. Review audit logs regularly for admin activity

  13. Set up alerts for sensitive operations (certificate changes, admin group modifications)

  14. Rotate cryptographic keys

  15. SAML certificates: Before expiration (30-60 days notice)
  16. JWKS: Every 90-180 days for routine rotation

  17. Immediately upon suspected compromise

  18. Use strong authentication

  19. Require MFA for admin accounts
  20. Use trusted identity providers (flagged as isTrusted)
  21. Avoid password-only authentication

Compliance Considerations

  • Audit log retention: Configure based on compliance requirements (SOC 2, HIPAA, etc.)
  • Cookie consent: Enable for GDPR/ePrivacy compliance
  • Contact information: Maintain current contacts for incident response
  • Session management: Configure based on data sensitivity and compliance frameworks

Regular Maintenance Tasks

Weekly:

  • Review expiring items dashboard
  • Check for unusual authentication patterns in login metrics

Monthly:

  • Review and clean up unused allowed origins
  • Verify contact information is current
  • Review tenant admin membership

Quarterly:

  • Audit admin access logs for suspicious activity
  • Review and update security settings based on threat landscape
  • Test disaster recovery procedures (certificate rotation, admin account recovery)

Annually:

  • Review and update all branding and communications for accuracy
  • Comprehensive security audit of tenant configuration
  • Review and update cookie consent messaging for regulatory changes

Additional Resources

  • 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

If you encounter issues or need assistance:

  1. Check audit logs for error details
  2. Review the Usage Report to identify misconfigurations
  3. Contact your super administrator for elevated privilege requests
  4. Consult API documentation for advanced configurations

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