OpenID Connect (OIDC)

OpenID Connect is a modern authentication protocol built on OAuth 2.0. Use it to integrate with cloud identity providers such as Google Workspace, Microsoft Entra ID, Okta, Auth0, and any other OIDC-compliant service.

How It Works

1. A user clicks Sign in with {Provider Name} on the login page.
2. The browser redirects to the identity provider's authorization endpoint.
3. The user authenticates at the identity provider.
4. The identity provider redirects back to MaestroHub with an authorization code.
5. MaestroHub exchanges the code for tokens, validates the ID token, and creates or links a local user account.
6. The user is logged in.

MaestroHub supports two application types:

Application Type	Flow	Client Secret	PKCE	Use Case
Web (default)	Authorization Code	Required (unless PKCE enabled)	Optional	Server-rendered applications, traditional web apps
SPA	Authorization Code + PKCE	Not required	Automatic	Single-page applications, frontend-only apps

Configuration Reference

Basic Settings

Field	Type	Required	Default	Description
Application Type	Select	No	Web	Choose Web for server-side apps or SPA for single-page apps. Determines whether a client secret is needed.
Client ID	Text	Yes	—	OAuth 2.0 client identifier from your identity provider. You receive this when registering your application.
Client Secret	Password	Conditional	—	OAuth 2.0 client secret. Required for Web applications when PKCE is not enabled. Hidden for SPA applications.
Issuer URL	URL	Yes	—	The OIDC issuer URL (e.g., https://accounts.google.com). MaestroHub fetches the discovery document at the /.well-known/openid-configuration path to auto-configure endpoints.
Redirect URI	URL	No	Auto-generated	Callback URL where users return after authentication. Format: https://your-domain.com/auth/oidc/callback/your-slug. Auto-populated from the provider slug. Configure this exact URL in your identity provider's allowed redirect URIs.

Advanced Settings

Field	Type	Default	Description
Use PKCE	Switch	Off	Enable Proof Key for Code Exchange. Recommended for SPA applications and adds extra security for web applications. When enabled, client secret becomes optional.
Post Logout Redirect URI	URL	—	URL to redirect users to after OIDC logout completes. Optional.
Scopes	Text	openid profile email	Space-separated list of OAuth 2.0 scopes. The default scopes request basic profile and email information. Add additional scopes if your identity provider offers custom claims.
Response Type	Select	code	OAuth 2.0 response type. Options: code, id_token, code id_token. Most providers use code for the standard authorization code flow.
Response Mode	Select	—	How the authorization response is delivered. Options: query, fragment, form_post. Leave empty to use the provider's default.

Attribute Mapping (Claims)

Map identity provider claims to MaestroHub user fields. These defaults follow the standard OIDC claim names and work with most providers out of the box.

Field	Default Claim	Description
Email Claim	email	Claim containing the user's email address
Username Claim	preferred_username	Claim containing the username
First Name Claim	given_name	Claim containing the first name
Last Name Claim	family_name	Claim containing the last name
Full Name Claim	name	Claim containing the full display name
Picture Claim	picture	Claim containing the profile picture URL

tip

Only change these if your identity provider uses non-standard claim names. For example, some providers use upn instead of preferred_username or first_name instead of given_name.

Role Mapping

Optionally map OIDC groups/roles to MaestroHub roles.

Field	Type	Default	Description
Enable Role Mapping	Switch	Off	Activate role mapping for this provider.
Role Claim	Text	groups	The ID token claim containing groups or roles (e.g., groups, roles, cognito:groups).
Default Role	Select	Member	Role assigned when no mapping matches the user's groups.
Strict Enrollment	Switch	Off	Block login if no specific mapping matches.
Mappings	Key → Value pairs	—	Map IdP group names to MaestroHub roles (e.g., Admins → System.Admin).

Setup Guide

Step 1: Register an Application

In your identity provider's admin console, create a new application (or "client") with these settings:

• Application type: Web application (or SPA if applicable)
• Redirect URI: https://your-maestrohub-domain.com/auth/oidc/callback/your-slug
• Grant type: Authorization Code
• Scopes: openid, profile, email

Note down the Client ID, Client Secret, and Issuer URL.

Step 2: Create the Provider in MaestroHub

1. Go to Identity & Access → SSO Configuration.
2. Click Add Provider → OpenID Connect.
3. Fill in the provider name and slug.
4. Enter the Issuer URL, Client ID, and Client Secret from your identity provider.
5. Verify the Redirect URI matches what you configured in your identity provider.

Step 3: Test and Enable

1. Click Test Connection. MaestroHub fetches the discovery document from the issuer URL. A success message confirms the provider is reachable.
2. Save the provider.
3. The provider appears on the login page as a Sign in with {Name} button.

Logout Behavior

MaestroHub supports RP-Initiated Logout for OIDC providers:

1. The local session is invalidated.
2. If the identity provider supports logout (advertised in the discovery document), the user is redirected to the provider's end_session_endpoint.
3. After logout completes at the provider, the user is redirected to the Post Logout Redirect URI (if configured) or back to the login page.

If the provider does not support logout, only the local session is invalidated.

Troubleshooting

Problem	Solution
"Invalid redirect URI"	Ensure the Redirect URI in MaestroHub exactly matches the one registered in your identity provider, including the protocol (https://) and trailing slash.
"Invalid client credentials"	Verify the Client ID and Client Secret. Check they haven't expired or been rotated.
"Issuer URL errors"	Confirm the URL is accessible from the MaestroHub server and returns a valid discovery document at the /.well-known/openid-configuration path.
"PKCE required"	Your identity provider may require PKCE. Enable the Use PKCE toggle in Advanced Settings.
Users not getting correct roles	Check the Role Claim matches the actual claim name in the ID token. Inspect the token claims in your identity provider's test tools.
Missing user attributes	Verify the Scopes include profile and email. Check the Attribute Mapping claims match your provider's claim names.