Skip to content

Authentication#

Configuring VergeOS as an OIDC Client

Overview

Key Points

  • Configure VergeOS to use OIDC authentication
  • Connect to a VergeOS OIDC identity provider
  • Enable automatic user creation and synchronization
  • Customize login appearance and behavior

This guide explains how to configure a VergeOS system or tenant to authenticate using another VergeOS system as an OIDC identity provider.

Prerequisites

  • Access to the VergeOS OIDC provider system
  • Well Known Configuration URL from the provider
  • Client ID and Client Secret from the provider
  • Administrative access to the client VergeOS system
  • Full URL of the client VergeOS system

Steps

1. Access Authorization Settings

  • Navigate to the Main Dashboard
  • Click System in the left menu
  • Select Authorization Sources
  • Click New

2. Configure Basic Settings

  • Name: Enter an identifier for this auth source (appears on login button)
  • Driver: Select OpenID (Well Known Config)
  • Base URL: Enter the Well Known Configuration URL
  • Redirect URI: Enter the full URL of this VergeOS system
  • Client ID: Paste the client ID from the provider
  • Client Secret: Paste the client secret from the provider

3. Configure Authentication Parameters

Default values typically work best for these settings: - Token hint parameter: Leave as post_logout_redirect_uri - Redirect parameter: Leave as post_logout_redirect_uri - Scope: Leave as openid profile email groups - Group Scope: Leave as groups

Check these boxes for optimal functionality: - Decode ID Token - Update Remote User - Update User Email Address - Update User Display Name - Update Group Membership

5. Configure User Creation

Choose your preferred user creation method: - Auto-Create Users: Enter .* to create all users automatically - Auto-Create Users in Group: Specify groups for restricted auto-creation

6. Customize Login Appearance

Optionally configure: - Button background color - Button text color - Custom Font Awesome icon - Icon color (using HEX codes)

7. Save Configuration

  • Click Submit to create the authorization source

Best Practices

  • Test authentication with a test user before rolling out widely
  • Keep debug mode disabled unless troubleshooting
  • Document your configuration choices for future reference
  • Regular verify user synchronization is working as expected

Troubleshooting

Common Issues

  • Authentication Fails

    • Verify Client ID and Secret are correct
    • Check Well Known Configuration URL
    • Ensure Redirect URI matches exactly

  • User Sync Issues

    • Verify Group Scope is enabled
    • Check group membership settings
    • Enable Debug Mode temporarily

  • Login Button Missing

    • Verify authorization source is enabled
    • Check login styling settings
    • Clear browser cache

Additional Resources

Feedback

Need Help?

If you encounter any issues while configuring OIDC client settings or have questions about this process, please don't hesitate to contact our support team.

Document Information

  • Last Updated: 2024-01-22
  • VergeOS Version: 4.12 and later

Setting Up VergeOS as an Identity Provider with OIDC

Overview

Key Points

  • Create an OIDC application to establish VergeOS as an identity provider
  • Enable single sign-on for other VergeOS systems and tenants
  • Configure centralized authentication with third-party providers
  • Support multiple client systems with a single OIDC setup

This guide walks you through the process of configuring VergeOS as an identity provider using OpenID Connect (OIDC), allowing centralized authentication for multiple VergeOS systems and tenants.

Prerequisites

  • Administrative access to the VergeOS system
  • Valid SSL certificate installed on the VergeOS system
  • Basic understanding of OIDC concepts
  • URLs of client systems that will use this authentication

Steps to Create an OIDC Application

  1. Access OIDC Settings - Navigate to the Main Dashboard - Click System in the left menu - Select OIDC Applications - Click New

  2. Configure Basic Settings - Enter a descriptive Name for the application - Check the Enabled box - Add an optional Description

  3. Set Up Redirect URIs - Enter the callback URL(s) where users will be redirected after authentication - Format: https://your-system-name.example.com - Multiple URIs can be added for different client systems

!!! tip "Using Wildcards" You can use wildcards in redirect URIs: - For multiple systems: https://examplecorp-site*.example.com - For multiple subdomains: https://vergesystem.*.example.com

  1. Configure Authentication Options - Force Authorization Source: Optionally select a third-party provider - Map User: Choose if all verified users should map to a specific account - Set Scope Settings (Profile, Email, Groups) - Configure access restrictions if needed

  2. Save Configuration - Click Submit to create the OIDC application - The system will generate a Client ID and Secret

Retrieving Client Credentials

  1. Access Application Dashboard - Navigate to System > OIDC Applications - Double-click your OIDC application

  2. Copy Required Information - Client ID: Copy using the displayed value or copy icon - Client Secret: Use the copy icon (value is hidden) - Well Known Configuration URL: Copy the displayed URL

Best Practices

  • Create separate OIDC applications for different client groups
  • Regularly review and update access restrictions
  • Use specific redirect URIs instead of wildcards when possible
  • Document which systems are using each OIDC application

Troubleshooting

Common Issues

  • Authentication Fails

    • Verify SSL certificate is valid and not expired
    • Check redirect URI matches exactly
    • Ensure client ID and secret are correctly copied

  • Scope Access Denied

    • Verify required scopes are enabled
    • Check user permissions in restriction settings

  • Redirect Problems

    • Confirm URL format matches redirect URI
    • Verify wildcard patterns if used
    • Check for SSL certificate issues

Additional Resources

Feedback

Need Help?

If you encounter any issues while setting up OIDC or have questions about this process, please don't hesitate to contact our support team.

Document Information

  • Last Updated: 2024-08-29
  • VergeOS Version: 4.12 and later