> For the complete documentation index, see [llms.txt](https://docs.vergeos-demo.com/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://docs.vergeos-demo.com/knowledge-base/system-administration/setting-up-vergeos-as-identity-provider-oidc.md).

# Setting Up VergeOS as an Identity Provider with OIDC

## Overview

{% hint style="info" %}
**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
  {% endhint %}

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 **System** > **OIDC Applications** from the top menu
   * 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

{% hint style="success" %}
**Using Wildcards**

You can use wildcards in redirect URIs:

* For multiple systems: `https://examplecorp-site*.example.com`
* For multiple subdomains: `https://vergesystem.*.example.com`
  {% endhint %}

4. **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
5. **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

{% hint style="warning" %}
**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
    {% endhint %}

## Additional Resources

* [Configuring VergeOS as an OIDC Client](/knowledge-base/system-administration/configuring-vergeos-as-oidc-client.md)
* [Third-Party Authorization Sources](/run-the-platform/authentication/auth-sources-overview.md)
* [SSL Certificate Management](/run-the-platform/system-administration/certificates.md)

## Feedback

{% hint style="info" %}
**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.
{% endhint %}

***

{% hint style="info" %}
**Document Information**

* Last Updated: 2024-08-29
* VergeOS Version: 4.12 and later
  {% endhint %}


---

# Agent Instructions
This documentation is published with GitBook. GitBook is the documentation platform designed so that both humans and AI agents can read, navigate, and reason over technical content effectively. Learn more at gitbook.com.

## Querying This Documentation
If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question.

Perform an HTTP GET request on the current page URL with the `ask` query parameter:

```
GET https://docs.vergeos-demo.com/knowledge-base/system-administration/setting-up-vergeos-as-identity-provider-oidc.md?ask=<question>
```

The question should be specific, self-contained, and written in natural language.
The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.