Authentication methods reference

Configure how users sign in to a Permit MCP Gateway host during the consent flow. This reference is for host admins who turn on sign-in methods, connect an identity provider (IdP), or limit sign-in to company email domains.

Each host has its own authentication configuration. Different hosts can use different methods, credentials, and domain restrictions.

Configure authentication for a host

1. In the Permit MCP Gateway dashboard, open the host's Settings from the host selector in the header.
2. Turn on a method and enter the values the method needs. The available methods table lists them.
3. Save the settings. The dashboard checks the configuration rules on save.
4. Connect an MCP client to the host's gateway URL. The sign-in screen of the consent flow shows the method you turned on.

A host starts with Email / Password on and all other methods off.

Available methods

Method	Configuration required	Callback URL
Email / Password	None	None
Email OTP	None	None
Passkeys	None	None
Google OAuth	Client ID and client secret	https://{subdomain}.agent.security/api/auth/callback/google
GitHub OAuth	Client ID and client secret	https://{subdomain}.agent.security/api/auth/callback/github
Microsoft OAuth	Client ID, client secret, optional tenant ID	https://{subdomain}.agent.security/api/auth/callback/microsoft
SAML 2.0 SSO	IdP entry point URL, IdP entity ID, X.509 certificate in PEM format	ACS URL: https://{subdomain}.agent.security/api/auth/sso/saml2/callback/sso-{subdomain}
OIDC SSO	Issuer URL, client ID, client secret	https://{subdomain}.agent.security/api/auth/oauth2/callback/sso-{subdomain}

In every URL, replace {subdomain} with the host's full subdomain, for example acme-brave-coral-37. The host settings page also shows the exact URLs for each method.

Email / Password

Users create an account with an email address and a password, then sign in with those credentials. Email / Password needs no configuration and is on by default.

If a host has no saved authentication configuration, the host uses Email / Password only.

Email OTP

Email one-time passcode (OTP) sign-in is passwordless. The user enters an email address, receives a 6-digit code by email, and enters the code within 5 minutes.

Email OTP needs no configuration; the host sends the code with its built-in email delivery. You can turn on Email OTP next to Email / Password, and the sign-in screen shows both.

Passkeys (WebAuthn)

Passkeys use the FIDO2 Web Authentication (WebAuthn) standard. A user signs in with a passkey, such as a biometric or a security key, instead of a password.

• Configuration required: none.
• Browser support: the user's browser must support the Web Authentication API.
• Registration: the sign-in screen offers sign-in with an existing passkey. A user without a registered passkey can't sign in with a passkey, so keep another method on next to Passkeys.

Google OAuth

Users sign in with a Google account. Google OAuth needs a Google OAuth client ID and client secret.

Set up Google OAuth

1. Go to the Google Cloud Console.
2. Go to APIs & Services > Credentials.
3. Click Create Credentials > OAuth client ID.
4. Select Web application as the application type.
5. Under Authorized redirect URIs, add the Google callback URL:

   https://{subdomain}.agent.security/api/auth/callback/google

   Replace {subdomain} with your host's full subdomain, for example acme-brave-coral-37.
6. Copy the Client ID and Client Secret.
7. In the Permit MCP Gateway dashboard, open the host's Settings and turn on Google OAuth.
8. Paste the client ID and client secret, and save.

One OAuth app per host

The callback URL contains the host's subdomain, so each host needs its own OAuth app registration. For several hosts, create a separate Google OAuth app for each host, with that host's callback URL.

GitHub OAuth

Users sign in with a GitHub account. GitHub OAuth needs a GitHub OAuth client ID and client secret.

Set up GitHub OAuth

1. Go to GitHub Developer Settings > OAuth Apps.
2. Click New OAuth App.
3. Fill in the app details:
   • Application name: for example, "Permit MCP Gateway (acme)".
   • Homepage URL: https://{subdomain}.agent.security
   • Authorization callback URL:

     https://{subdomain}.agent.security/api/auth/callback/github

4. Click Register application.
5. Copy the Client ID, then generate and copy a Client Secret.
6. In the Permit MCP Gateway dashboard, open the host's Settings and turn on GitHub OAuth.
7. Paste the client ID and client secret, and save.

Microsoft OAuth

Users sign in with a Microsoft account through Microsoft Entra ID (formerly Azure AD). Microsoft OAuth supports single-tenant and multi-tenant apps. It needs a Microsoft OAuth client ID and client secret, and optionally a tenant ID.

Set up Microsoft OAuth

1. Go to Azure Portal > App registrations.
2. Click New registration.
3. Fill in the registration:
   • Name: for example, "Permit MCP Gateway (acme)".
   • Supported account types:
     • Single tenant: only users in your Microsoft Entra directory.
     • Multitenant: users in any Microsoft Entra directory.
     • Multitenant and personal Microsoft accounts: users in any Microsoft Entra directory and personal Microsoft accounts.
   • Redirect URI: select Web and enter the Microsoft callback URL:

     https://{subdomain}.agent.security/api/auth/callback/microsoft

4. Click Register.
5. Copy the Application (client) ID.
6. Go to Certificates & secrets > New client secret, create a secret, and copy its Value.
7. In the Permit MCP Gateway dashboard, open the host's Settings and turn on Microsoft OAuth.
8. Paste the client ID and client secret.
9. Optional: set the Tenant ID to limit sign-in to one Microsoft Entra directory. See Tenant ID values.
10. Save the settings.

Tenant ID values

Value	Who can sign in
Empty	Same as common.
common	Any Microsoft Entra account or personal Microsoft account.
organizations	Any Microsoft Entra account. No personal accounts.
consumers	Personal Microsoft accounts only.
A directory UUID	Only users in that Microsoft Entra directory.

SAML 2.0 SSO

Security Assertion Markup Language (SAML) 2.0 single sign-on (SSO) connects the host to your company IdP, such as Okta, Microsoft Entra ID, or Google Workspace. Permit MCP Gateway is the service provider (SP), and your IdP is the identity provider.

SAML SSO needs the IdP entry point URL, the IdP entity ID, and the IdP's X.509 signing certificate in PEM format.

Service provider details

Enter these values in your IdP when you create the SAML app. The host settings page shows the same values.

Field	Value
SP Entity ID / Audience URI	https://{subdomain}.agent.security/api/auth/sso/saml2/sp/metadata
ACS (Assertion Consumer Service) URL	https://{subdomain}.agent.security/api/auth/sso/saml2/callback/sso-{subdomain}
SP Metadata URL	https://{subdomain}.agent.security/api/auth/sso/saml2/sp/metadata?providerId=sso-{subdomain}

Attribute mapping

Configure your IdP to send these SAML attributes:

Attribute	SAML claim URI
Email	http://schemas.xmlsoap.org/ws/2005/05/identity/claims/emailaddress
Name	http://schemas.xmlsoap.org/ws/2005/05/identity/claims/name

SAML security settings

Setting	Behavior
SP-initiated SSO only	The host rejects IdP-initiated SSO. Users start sign-in from the gateway's sign-in screen, not from the IdP's app dashboard.
InResponseTo validation	Each SAML response must reference the authentication request the host sent.
Certificate format	The IdP certificate must be PEM: it starts with -----BEGIN CERTIFICATE----- and ends with -----END CERTIFICATE-----.

Identity provider consoles change

The Okta, Microsoft Entra ID, and Google Workspace steps below use the console labels those vendors show at the time of writing. If a label differs in your console, match the field by purpose: ACS URL, SP entity ID, name ID format, and the email and name attributes.

Okta setup

1. In the Okta Admin Console, go to Applications > Create App Integration.
2. Select SAML 2.0 and click Next.
3. Set App name, for example "Permit MCP Gateway".
4. Configure the SAML settings:
   • Single sign-on URL (ACS URL): https://{subdomain}.agent.security/api/auth/sso/saml2/callback/sso-{subdomain}
   • Audience URI (SP Entity ID): https://{subdomain}.agent.security/api/auth/sso/saml2/sp/metadata
   • Name ID format: EmailAddress
   • Application username: Email
5. Add attribute statements:
   • email to user.email (URI: http://schemas.xmlsoap.org/ws/2005/05/identity/claims/emailaddress)
   • name to user.displayName (URI: http://schemas.xmlsoap.org/ws/2005/05/identity/claims/name)
6. Click Next, then Finish.
7. On the app's Sign On tab, copy the IdP SSO URL (entry point) and the IdP Entity ID (issuer), and download the X.509 Certificate.
8. In the Permit MCP Gateway dashboard, open the host's Settings and turn on SAML 2.0 SSO.
9. Paste the entry point URL, entity ID, and PEM certificate, and save.

Microsoft Entra ID setup

1. In the Azure Portal, go to Enterprise Applications > New Application > Create your own application.
2. Select Integrate any other application you don't find in the gallery (Non-gallery).
3. Name the application, for example "Permit MCP Gateway", and click Create.
4. Go to Single sign-on > SAML.
5. In Basic SAML Configuration, set:
   • Identifier (Entity ID): https://{subdomain}.agent.security/api/auth/sso/saml2/sp/metadata
   • Reply URL (ACS URL): https://{subdomain}.agent.security/api/auth/sso/saml2/callback/sso-{subdomain}
6. In Attributes & Claims, check these mappings:
   • emailaddress to user.mail
   • name to user.displayname
7. In SAML Certificates, download Certificate (Base64). The Base64 certificate is in PEM format.
8. In the Set up section for your application, copy the Login URL (entry point) and the Microsoft Entra identifier (entity ID). Older portal versions label the identifier Azure AD Identifier.
9. In the Permit MCP Gateway dashboard, open the host's Settings and turn on SAML 2.0 SSO.
10. Paste the entry point URL, entity ID, and certificate, and save.

Google Workspace setup

1. In the Google Admin Console, go to Apps > Web and mobile apps > Add app > Add custom SAML app.
2. Name the app, for example "Permit MCP Gateway", and click Continue.
3. On the Google Identity Provider details page, copy the SSO URL (entry point) and the Entity ID, and download the Certificate.
4. Click Continue.
5. Fill in Service provider details:
   • ACS URL: https://{subdomain}.agent.security/api/auth/sso/saml2/callback/sso-{subdomain}
   • Entity ID: https://{subdomain}.agent.security/api/auth/sso/saml2/sp/metadata
   • Name ID format: EMAIL
   • Name ID: Basic Information > Primary email
6. Add attribute mappings:
   • email to Basic Information > Primary email
   • name to Basic Information > First name and Last name
7. Click Finish, then turn the app ON for the organizational units that use the gateway.
8. In the Permit MCP Gateway dashboard, open the host's Settings and turn on SAML 2.0 SSO.
9. Paste the entry point URL, entity ID, and certificate, and save.

OIDC SSO

OpenID Connect (OIDC) SSO connects the host to any IdP that supports OIDC discovery. OIDC SSO needs the issuer URL, a client ID, and a client secret. The host requests the openid, profile, and email scopes.

How OIDC discovery works

Permit MCP Gateway reads your IdP's endpoints from the standard OpenID Connect discovery URL:

{issuerUrl}/.well-known/openid-configuration

You enter the issuer URL. The gateway reads the authorization, token, and key endpoints from the discovery document.

Set up OIDC SSO

1. In your IdP, register a web application (sometimes called an OIDC app).
2. Set the redirect URI (callback URL). Copy the exact value from Redirect URI (Callback URL) in the OIDC section of the host settings page:

   https://{subdomain}.agent.security/api/auth/oauth2/callback/sso-{subdomain}

3. Note the Issuer URL, for example https://accounts.google.com, https://login.microsoftonline.com/{tenant}/v2.0, or https://{domain}.okta.com.
4. Copy the Client ID and Client Secret.
5. In the Permit MCP Gateway dashboard, open the host's Settings and turn on OIDC SSO.
6. Paste the issuer URL, client ID, and client secret, and save.

One SSO method per host

A host can use SAML 2.0 SSO or OIDC SSO, not both. To switch, turn off the current SSO method before you turn on the other one.

Domain restrictions

Domain restrictions limit which email domains can sign in with each method. Set them in the host's Settings.

Global and per-method restrictions

Restriction	Scope
Global	All authentication methods on the host.
Per-method	One authentication method.

An empty list means no restriction at that level.

How global and per-method restrictions combine

When both lists are set, an email domain must be in the global list and in the per-method list. A per-method list narrows the global list. A per-method list can't add a domain that the global list blocks.

Global allows	Per-method allows	user@acme.com	user@partner.io	user@outsider.com
acme.com, partner.io	Not set	Allowed	Allowed	Blocked
Not set	acme.com	Allowed	Blocked	Blocked
acme.com, partner.io	acme.com	Allowed	Blocked (not in per-method)	Blocked
acme.com	acme.com, outsider.com	Allowed	Blocked	Blocked (not in global)

Per-method lists don't bypass the global list

If the global list allows only acme.com and a per-method list adds outsider.com, users with @outsider.com addresses still can't sign in with that method. Add a domain to the global list before you add it to a per-method list.

Domain restriction examples

Scenario	Global allowed domains	Per-method allowed domains	Result
One organization	acme.com	Not set	All methods accept only @acme.com addresses.
Employees on SSO, contractors on Email / Password	acme.com, contractor.acme.com	SSO: acme.com	Employees use SSO. Users with @contractor.acme.com addresses can use Email / Password but not SSO.
Partner organizations	acme.com, partner1.com, partner2.com	Optional: SSO limited to acme.com	All three domains can use any enabled method, except where a per-method list narrows them.

Force-redirect domains

For SAML or OIDC SSO, you can set force-redirect domains (Force SSO for Domains in the SSO settings). When a user enters an email address with a matching domain, the sign-in screen sends the user to the SSO provider without showing the other methods.

1. The user enters an email address on the sign-in screen.
2. If the domain matches a force-redirect domain, the browser redirects to the SSO provider.
3. After SSO authentication, the user returns to the consent flow.

If the SSO sign-in fails, for example because the IdP is unavailable or the user cancels, the user returns to the sign-in screen with the message "SSO sign-in was unsuccessful. Please try another method or contact your administrator." The user can then sign in with any other method allowed for the user's domain.

Enable multiple methods

Combine methods on one host

You can turn on any combination of methods, with one limit: a host can use only one SSO type, SAML 2.0 or OIDC.

What users see on the sign-in screen

The sign-in screen shows only the methods that are on. When domain restrictions are set, the user enters an email address first, and the screen shows only the methods allowed for that domain.

Methods appear in this order:

1. Passkeys
2. Social sign-in buttons (Google, GitHub, Microsoft)
3. SSO button (SAML or OIDC)
4. Email / Password form
5. Email OTP form

The Create Account link appears only when Email / Password or Email OTP is on.

Recommended configurations

Organization type	Methods	Notes
Small team	Email / Password	No external setup.
Developer team	GitHub OAuth and Email / Password	GitHub for daily sign-in, Email / Password as a fallback.
Google Workspace organization	Google OAuth and Email / Password	Limit Google OAuth to your domain with a per-method restriction.
Microsoft 365 organization	Microsoft OAuth or OIDC SSO	Set the tenant ID to limit sign-in to your directory.
Enterprise with an IdP	SAML 2.0 or OIDC SSO, and Email / Password	SSO for employees, Email / Password for exceptions. Add force-redirect domains so employees go straight to SSO.
Organization with contractors	SSO and Email / Password, with domain restrictions	SSO limited to the employee domain, Email / Password for the contractor domain.

Configuration rules

The dashboard enforces these rules when you save authentication settings:

Rule	Description
At least one method	At least one authentication method must be on. You can't turn off all methods.
One SSO type per host	A host can use SAML 2.0 SSO or OIDC SSO, not both.
SAML requires all fields	SAML needs the entry point URL, the entity ID, and the X.509 certificate.
OIDC requires all fields	OIDC needs the issuer URL, the client ID, and the client secret.
Social providers require credentials	Google, GitHub, and Microsoft OAuth each need a client ID and a client secret.
PEM format	The dashboard rejects a SAML certificate that doesn't start with -----BEGIN CERTIFICATE----- and end with -----END CERTIFICATE-----.

Callback URL reference

Use these URLs when you register OAuth apps or configure an IdP:

Method	Callback URL
Google OAuth	https://{subdomain}.agent.security/api/auth/callback/google
GitHub OAuth	https://{subdomain}.agent.security/api/auth/callback/github
Microsoft OAuth	https://{subdomain}.agent.security/api/auth/callback/microsoft
OIDC SSO	https://{subdomain}.agent.security/api/auth/oauth2/callback/sso-{subdomain}
SAML 2.0 ACS	https://{subdomain}.agent.security/api/auth/sso/saml2/callback/sso-{subdomain}

Replace {subdomain} with the host's full subdomain, for example acme-brave-coral-37.

Next steps

• Set up a host: create a host, import MCP servers, and share the gateway URL.
• Filter users with domain restrictions: onboard a company's users at scale.
• Consent service: what happens after a user signs in.
• Platform reference: Settings: the other host settings.