Settings → User Access → Auth Providers

External identity providers let users sign in to MisterShell with their existing corporate identity — LDAP, OIDC (OpenID Connect), or SAML. Each provider you configure appears as an additional sign-in option on the login page.

Providers are ordered: the list you see here is the order in which sign-in buttons are presented.

What you can do

• Create, edit, enable, disable, and delete providers.
• Drag to reorder the sign-in button list.
• Define group mappings that automatically assign MisterShell roles based on the groups a user belongs to in the external directory.

Common tasks

Create a provider

Creating and managing providers requires the Pro edition. Without it, creating, editing (including enabling/disabling), reordering, and testing providers is refused — the Create and edit controls show a padlock naming what is missing. You can still view and delete existing providers, but new sign-ins through them are refused. Local sign-in remains available without the Pro edition and follows its configured MFA policy.

Before creating an enabled OIDC or SAML provider — or enabling one later, set the Application base URL setting to this deployment’s public URL. The sign-in URLs you register with your identity provider are derived from it. You can create either provider in a disabled state first; LDAP does not depend on this setting.

1. Click Create Provider at the top right.

2. Pick the provider type (LDAP, OIDC, SAML). Fields change to match.

3. Every provider has a Name (shown on the login button), a URL Mnemonic — a short stable token used in the provider’s URLs (letters, digits, hyphens) that cannot be changed after creation — and an Enabled toggle.

4. Fill the type-specific fields:

   LDAP:

   • Server URL, Bind DN and Bind Password, Base DN.
   • User Search Filter (use {username} as the placeholder), Group Search Base, and Group Search Filter (use {user_dn}).
   • Use TLS/SSL and Verify TLS certificate toggles.

   OIDC:

   • Issuer URL, Client ID, Client Secret, Scopes, and a Verify TLS certificate toggle.
   • Claims Mapping — the claim names your IdP puts in the ID token for email, first name, last name, and groups. Defaults are the standard OpenID Connect names; the groups claim in particular is often named differently and must match, or no roles get assigned.
   • Enable LDAP group resolution — optionally replace the IdP’s group claim with memberships read from a configured LDAP provider. Select the LDAP provider that contains the same users and groups.
   • Redirect URI — read-only, derived from the Application base URL and the mnemonic. Copy it and register it verbatim with your identity provider.

   SAML:

   • IdP Entity ID, IdP SSO URL, and the IdP X.509 Certificate (pasted as PEM). There is no metadata import — copy these three values out of your IdP’s metadata.
   • Require Signed Assertions and Sign Authentication Requests toggles; enabling request signing asks for an SP private key and certificate.
   • Attribute Mapping — the SAML attribute names your IdP sends for email, first name, last name, and groups. Pick an IdP Preset to prefill, then adjust to match your assertions.
   • Enable LDAP group resolution — optionally replace the IdP’s group attribute with memberships read from a configured LDAP provider. Select the LDAP provider that contains the same users and groups.
   • SP Metadata — read-only SP Entity ID and SP ACS URL, derived from the Application base URL and the mnemonic. Copy both into your identity provider’s configuration.

   If your directory or identity provider presents a certificate signed by an internal certificate authority, load that authority into CA Certificates first, then turn Verify TLS certificate on.

5. Click Create.

6. Optionally add group mappings that map directory groups to MisterShell roles (see below).

Configure Local authentication

Open the Local card’s edit dialog to configure password requirements, password reset link lifetime (in minutes), email verification before account activation, and multi-factor authentication. Password requirements include minimum length and minimum counts of uppercase letters, lowercase letters, digits and special characters. These controls edit the existing application settings and show their current values and allowed limits.

Application settings read permission is required to view these additional controls; application settings write permission is required to edit them. Click Save to apply changes. If an update fails, the dialog stays open and reports whether earlier changes were saved; retry saves the remaining changes. MFA policy changes are saved last because they can require signing in again.

Choose an MFA method

Use the Multi-factor authentication selector for Local authentication or an LDAP provider to choose one required method: None, Email, or Authenticator app (TOTP). Local MFA does not require the Pro edition. OIDC and SAML continue to use the verification methods configured at their identity provider.

Selecting Email opens the existing Test Email MFA activation dialog. The selector changes to Email only after the delivery test succeeds; cancelling or a failed test keeps the previous method. None and Authenticator app do not require an administrator activation test. Any method change, including changing to None, invalidates MFA proof for that provider. Changing your own authentication source signs you out so that the new policy applies immediately.

Changing away from TOTP retains existing authenticator enrollments and unused recovery codes; enabling TOTP again reuses them. To require a new setup for a user, use Reset MFA enrollment. Deleting a user removes their enrollment. Deleting an LDAP provider removes its users’ enrollments but preserves the user accounts and historical security audit evidence.

Activate Email MFA

First configure the smtp_ settings in System → Advanced Settings. Use a reachable mail server and a sender address that it accepts; for remote SMTP, configure TLS and certificate verification with the appropriate trusted CA. Authentication email uses these SMTP settings even when ordinary email notifications are disabled.

1. Open the authentication provider’s configuration.
2. Select Email under Multi-factor authentication.
3. Enter a test email address and click Request code.
4. Enter the code received in that mailbox and click Verify code.
5. Once verification succeeds, save the provider configuration.

An incorrect or expired code returns the modal to the email and request-code step, retaining the address. Cancelling keeps the previous method. The activation check uses the same email template, six-digit codes, five-minute expiry, five-attempt limit and one-minute resend cooldown as user sign-in. Requesting another code does not reset the attempt limit. Activation proof expires with the original challenge; if it expires before saving, repeat the test. Changing SMTP settings or a new provider’s URL mnemonic also requires a new test.

The test address is used only for this activation check. Local users receive codes at their account email address. LDAP users receive codes at the email attribute returned by the directory during authentication, even when profile attribute synchronization is disabled. Configure the LDAP email mapping and ensure users have real, deliverable addresses: a synthesized @external.invalid address cannot receive a login code. The administrator’s successful test proves delivery to that mailbox, not to every directory user.

API keys remain a separate authentication mechanism and do not acquire an interactive MFA step.

The fixed Local recovery account, admin@mistershell.local, remains password-only under every Local MFA method. Its session stays active when the policy changes; password verification, account lockout and disabled-account checks still apply. This exception applies only to that Local identity. Other Local administrators, other .local addresses and LDAP accounts follow their configured MFA policy.

Sign in with an email code

Enter your usual local or LDAP credentials. When email MFA is required, the sign-in screen shows the masked destination and a code field. Paste the emailed code and select Verify code. You receive access only after successful verification. Use Resend code when the resend countdown finishes; only the newest code works. Use Back to sign in to start again, including after a challenge expires.

Sign in with an authenticator app

When Authenticator app is required, an unenrolled user must set it up before access is granted. Scan the QR code or expand Can’t scan? and copy the setup key, enter a six-digit code, then copy or download the ten one-time recovery codes. Sign-in completes only after I’ve saved my recovery codes is checked. An enrolled user can enter an authenticator code or select Use a recovery code. Authenticator flows do not show a resend action.

Users can replace their authenticator or regenerate recovery codes under My Account → Account Security → Authenticator App after confirming their password and current factor. Replacing an authenticator signs out the current session.

Delivery problems and administrator recovery

If sending fails, sign-in remains incomplete; MisterShell does not fall back to password-only access. Check SMTP connectivity, sender restrictions, TLS settings and mail filtering. A missing LDAP address requires fixing the directory mapping or the user’s directory attributes.

Restore email delivery, or use an administrator authenticated through another working source to select None or Authenticator app for the affected provider. Local MFA policy is changed through the Local authentication dialog or provider API. Generic setting update and reset operations refuse the internal local_mfa setting. An existing administrator API key with the required permissions can use the provider API. Password resets retain MFA enrollment.

Email codes depend on the security of the mailbox. If the same password grants access to LDAP and email, a stolen password may grant access to both. This feature provides email two-step verification; it is not phishing-resistant authentication or a claim of NIST authenticator assurance compliance.

Test a provider

Click the Test Connection icon on the provider’s row. A dialog reports success or the failure detail. For LDAP this exercises the directory bind; for OIDC it checks the provider’s discovery endpoint; for SAML it validates the certificate and settings.

Allow AI agents to act on a user’s behalf (MCP)

External AI agent platforms can call MisterShell on behalf of one of your users, using an access token issued by the same identity provider they already sign in with. The agent gets exactly that user’s permissions — no more, and nothing an agent can do that the person could not do themselves in the interface.

This is available on OIDC providers only. SAML and LDAP have no token an agent can carry, so those provider types do not offer the option.

To turn it on:

1. Edit the OIDC provider and switch on Enable MCP support.

2. Enter the MCP audience — the value your identity provider stamps into access tokens meant for MisterShell. Each vendor names this differently:

   Identity provider	What the setting is called
   Microsoft Entra ID	Application ID URI (the token carries the application’s ID)
   Okta	Audience, on a custom authorization server
   Auth0	API Identifier
   Keycloak	Included Custom Audience, on an Audience mapper
   Ping	Audience / Audience Claim Value

3. MCP email claim defaults to the email claim configured for browser sign-in (normally email). If the access token carries the user’s email under another name, enter that exact claim name. For example, Auth0 API-audience tokens can use a namespaced custom claim such as https://your-mistershell-url/email; configure that claim in Auth0 and enter the same name here.

4. Click Update. Clearing the audience field again switches MCP access off for that provider.

Your identity team also has work to do on their side: register MisterShell as an application that can be issued tokens, authorise the agent platform to request them, and ensure the resulting access token contains the configured audience and an email claim. Claim defaults vary by provider, authorization server, tenant, scopes, and token type, so inspect a representative access token instead of assuming that an ID-token claim is also present in it. For Microsoft Entra managed users, configure the email optional claim for access tokens (or the applicable v2 OpenID scope) when it is not already emitted.

For Microsoft Entra ID, match the access-token version to the configured issuer. If the provider’s issuer uses the v2 endpoint (login.microsoftonline.com/.../v2.0), set requestedAccessTokenVersion to 2 on the app registration that represents MisterShell. A v1 access token uses a different issuer format and therefore fails issuer validation against that v2 configuration.

Two things to expect:

• The person must have signed in to MisterShell at least once. Accounts are never created from an agent’s token, so a token for someone with no MisterShell account is refused.
• Turning this on for one provider does not affect the others. A provider with no audience set is used for signing in only, and tokens from it are refused.

Edit a provider

1. Click the edit icon.
2. Adjust any field. Secret fields (bind password, client secret) are masked; leave them blank to keep the stored value.
3. Click Update.

Enable / disable a provider

Edit the provider and flip Enabled. Disabled providers stop appearing on the login page but are kept in the list so you can re-enable them later.

Re-order providers

Grab the ⋮⋮ drag handle and drop at the new position. The login page buttons appear in this order.

Delete a provider

1. Click the red trash icon.
2. Confirm.

Users who had authenticated through this provider can no longer use it to sign in. Their existing MisterShell accounts and history remain. There is no manual provider-conversion action, but with external_auth_auto_provision enabled (the default), a first sign-in through another provider using the same email address re-links the existing account instead of creating a duplicate; its authentication type and provider association are replaced. If automatic provisioning is disabled, that re-link does not happen. Deactivate or delete accounts from the Users tab if they are no longer needed.

Manage group mappings

Click the group icon on a provider row. A modal lists mappings between directory groups and MisterShell roles:

1. Add a mapping: click Add Mapping, type the External Group identifier — the full group DN for LDAP, the group claim value for OIDC, the group attribute value for SAML — pick the Local Role, and click Create. Each mapping is saved individually.
2. Edit a mapping: click the pencil icon next to it, adjust, and click Update.
3. Remove a mapping: click the trash icon and confirm.

When LDAP group resolution is enabled on an OIDC or SAML provider, keep the mappings on that OIDC or SAML provider, but enter the full LDAP group DNs. The referenced LDAP provider supplies memberships only; its own role mappings are not used. Its Enabled toggle controls direct LDAP login, so it may remain disabled while OIDC or SAML continues using it for group resolution.

The join is strict and uses the email asserted by OIDC or SAML. Configure the IdP to provide a verified, administrator-controlled email that uniquely matches one LDAP entry below the LDAP Base DN. An ambiguous match or an LDAP connection, bind, or search failure denies the login instead of falling back to the IdP group claim. A user absent from LDAP has no resolved groups and follows the role-mapping mode described below.

When a federated user signs in, MisterShell evaluates all mappings against the user’s directory groups and stores the matching roles on the account. By default the provider is authoritative: on every sign-in the user’s roles are replaced with what the mappings resolve to (so role changes made on the Users tab do not survive the next sign-in), and a user whose groups match no mapping is denied login. An administrator can switch this to additive behavior — mapped roles are added and nothing is removed or denied — with the external_auth_override_roles setting under Settings → System → Advanced Settings.

Provider list

Each row shows:

Element	Notes
Icon	Type-specific icon. Grey when the provider is disabled.
Name	Display name (also shown on the login button).
Type badge	LDAP, OIDC, or SAML.
Status badge	Enabled or Disabled.
Group mappings count	Number of mappings configured.

Permissions

• Read: app.auth_providers.read.
• Create / edit / reorder: app.auth_providers.write.
• Delete: app.auth_providers.delete.