Generic OIDC authentication

The Generic OIDC login option allows administrators to enable end-users to authenticate via their organization's identity provider (IdP) that supports OpenID Connect (OIDC). This feature integrates seamlessly with OIDC-compliant providers, offering secure and standardized authentication.

For more details on the OIDC protocol, refer to the OpenID Connect Core Specification.

Support for OIDC providers is provided on a best-effort basis only. Refer to the Limitations section below for further details.

Step 1: Configure the Identity Provider

  1. Create an OAuth2/OIDC Client:

    • Log in to your identity provider's admin console.

    • Navigate to the section for creating or managing applications (often called "Clients" or "Applications").

    • Create a new client/application and ensure it is configured as a confidential client (often called “Web Application”), which requires a Client ID and Client Secret.

  2. Configure Redirect URIs:

    • Add the callback URI(s) provided by Dispatcher Paragon Cloud in the Authentication provider form. These URIs are used by the identity provider to redirect users back to our application after authentication.

    • Example: https://your-app-domain.com/callback/oidc-login, https://your-app-domain.com:8443/callback/oidc-login

  3. Set Scopes:

    • Ensure the following default scopes are allowed: OpenID, profile, email, and offline_access. These scopes enable retrieving user identity, profile details, and email address, and they make sure to be able to refresh users as they use Dispatcher Paragon Cloud.

  4. Configure Grant Type:

    1. Ensure Authorization Code flow is enabled.

  5. Save the Configuration:

    • Once configured, note down the following details:

      • Client ID

      • Client Secret

      • OpenID Provider Configuration Endpoint (well-known endpoint)

Refer to your identity provider’s documentation for the exact steps to register an application.

Step 2: Configure Generic OIDC in Dispatcher Paragon Cloud

Once you have registered the application with your IdP, configure it in our application:

  1. Log in to Dispatcher Paragon Cloud Web UI and navigate to the Users page, then select the Authentication Providers tab.

  2. Click Add and select the Generic OIDC option for the Type.

  3. Fill out the following fields:

    • Name – A name used to identify the particular authentication provider configuration.

    • Domains – The domain names of the authenticating users. If you have domain aliases that the users can use to log in, add them to this field. If the usernames of the authenticating users contain a domain, it must match one domain in this list. If the usernames of the authenticating users don’t contain a domain, the behavior depends on the Strict domain validation configuration in the account’s Security options configuration. If strict domain validation is disabled (default), Dispatcher Paragon Cloud will allow users without a domain to authenticate; otherwise, users without a domain in the username won’t be able to authenticate.
      For example, if the authenticating user has a username john@my-company.com, the Domains field must contain the my-company.com domain for the user to authenticate successfully.

    • Priority – A number determining the order in which authentication providers will be called until one succeeds. Higher-priority providers will be called first.

    • Active – If enabled, the authentication provider will be used for authentication. If disabled, this authentication provider will not be used.

    • Client ID – Enter the Client ID obtained from your IdP.

    • Client Secret – Enter the Client Secret obtained from your IdP.

    • OpenID Provider Configuration endpoint – Enter your IdP's well-known configuration URL (e.g., https://idp.example.com/.well-known/openid-configuration). This endpoint provides metadata such as authorization and token endpoints.

    • Scopes: The default scopes (openid profile email offline_access) are prefilled but can be customized if needed.

    • Prompts – (Optional) Set the OIDC prompt parameter to customize your IdP's behavior during user login.

    • Callback domain – Select from the list of available domains the one where you want your users to be redirected after authentication in the external IdP (the one configured in Step 1 as Redirect URIs).

    • Custom token claim names – This allows you to remap the claims for the Username, Full name, Email, and Groups user fields. Note that these claims need to be provided in the ID token during user authentication.

    • Show on Login page – Enable this to show “Login via <provider Name>“ button on the login page. The name on the button is the name you entered in the Name field.

  4. Save your changes.

    localhost_8080_main (2)-20250424-092653.png

The users from the external IdP will now be able to log in to Dispatcher Paragon Cloud.

Advanced Configuration and Troubleshooting

OIDC Specification Reference

For advanced users, the OpenID Connect specification provides detailed information about the protocol and its components. You can refer to the following resources:

Verifying and troubleshooting the integration

To verify the configuration and ensure that authentication via the external IdP works correctly, perform OIDC authentication from Dispatcher Paragon Cloud (like a regular user authenticating). In case there are any issues during the authentication process, the user won’t be logged in to Dispatcher Paragon Cloud, and they will end up on either the external IdP’s error screen (in case of misconfiguration on the external IdP side) or on the Dispatcher Paragon Cloud login screen with an error detail. Follow the instructions in the error message to resolve the problems.

Common Issues

  • Username domain mismatch / no user authenticated: Make sure that the domain in the username (the part after the “@” (at) sign) of the user matches one of the domains listed in the Domains field in the Authentication provider configuration in Dispatcher Paragon Cloud.

  • Invalid Callback URI: Ensure the callback URI configured in the identity provider matches the one the application expects.

  • Incorrect Scopes: Verify that the required scopes are enabled in the identity provider and match those configured in the application.

  • Expired Client Secret: If authentication fails, ensure the Client Secret has not expired and is correctly entered in the application.

Limitations

The configuration options provided for integration with an OIDC provider are limited; therefore, many OIDC specification-compliant providers that require configuration options currently not available are not supported by Dispatcher Paragon Cloud.

Many OIDC providers require customizations to the standard OIDC protocol (outside the OIDC specification), meaning they are also not supported by Dispatcher Paragon Cloud.

If you find out that Dispatcher Paragon Cloud is not compatible with your OIDC provider, you can always create a feature request.

Unsupported configuration scenarios

Hosting an OIDC provider on a domain that lacks a globally trusted certificate (signed by a trusted Certificate Authority) is not supported. Importing the OIDC provider’s certificate under the Trusted CA certificates section does not affect OIDC authentication.