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.

The code exchange always happens on the MaestroHub server, which mints and verifies the state, nonce and PKCE challenge. Both confidential clients (those with a client secret) and public clients (those without one, using PKCE) use this same flow.

Configuration Reference

Basic Settings

Field	Type	Required	Default	Description
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 unless the client is a public client — for those, leave it empty and enable Use PKCE instead. Stored encrypted; once saved it is shown as ******** and never sent back to the browser.
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	Read-only	—	Derived	The callback URL MaestroHub sends to your identity provider: https://your-domain.com/auth/oidc/callback. It is shown on the form with a copy button rather than typed, because it follows the address you use to reach MaestroHub — including any reverse-proxy sub-path. Register this exact URL in your identity provider's allowed redirect URIs.

About the Client Secret

The client secret is encrypted before it is written to the database and is never included in an API response. After you save a provider, the field shows ********.

• To keep the current secret, leave the field showing ******** and save. Editing any other setting does not disturb it.
• To replace it, type the new secret over the placeholder and save.
• To switch to a public client, clear the field and enable Use PKCE. The stored secret is removed.

The encryption key is created automatically on first start and kept in MaestroHub's secrets directory, alongside the persistent data volume. Back that directory up with your data: if the key is lost, saved client secrets cannot be read back and you will need to re-enter the secret for each provider.

Advanced Settings

Field	Type	Default	Description
Use PKCE	Switch	Off	Enable Proof Key for Code Exchange. Required for a public client (one registered without a client secret), and adds extra security for confidential clients. When enabled, the 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, Microsoft Entra ID commonly issues upn rather than a plain email claim, and some providers use first_name instead of given_name.

How mapping behaves

• Mapped values are applied at every sign-in, not only the first. Renaming a user at your identity provider updates their MaestroHub profile the next time they sign in.
• If a claim you name is not in the token, MaestroHub falls back to the standard claim and writes a warning to the server log naming the claim it looked for. Check that warning first if a mapping appears to have no effect — a typo in a claim name looks exactly like a mapping that was ignored.
• The Email Claim can supply the address on its own. If your provider issues no standard email claim, map this field and sign-in will use the claim you name. If neither the mapped claim nor the standard one yields an address, the sign-in is refused and the error names the claim that was configured.

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
• Redirect URI: https://your-maestrohub-domain.com/auth/oidc/callback — the address your users reach MaestroHub at, followed by /auth/oidc/callback. If MaestroHub is published under a sub-path, include it (for example https://device.example.com/maestrohub/auth/oidc/callback). The provider form shows the exact value once you get there.
• 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. Copy the Redirect URI shown on the form and confirm it is registered in your identity provider (Step 1).

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"	The URL registered at your identity provider must match the Redirect URI shown on the provider form exactly — copy it from there rather than typing it. Because it follows the address used to reach MaestroHub, changing hostname, switching to HTTPS or publishing under a reverse-proxy sub-path all require registering the new URL.
"Invalid client credentials"	Verify the Client ID and Client Secret. Check they haven't expired or been rotated. The saved secret is shown as ******** and cannot be read back, so if you are unsure it is still correct, type it in again and save.
"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 — when one does not match, the server log names the claim it could not find.
"User email is required"	The token carried no usable email address. Add email to the Scopes, confirm the user has an email address at the identity provider, or set Email Claim to the claim your provider actually issues (Entra ID often uses upn).