Identity Providers

Admins can add identity provider configuration after the bootstrap admin changes the default password.

Supported Provider Kinds

Microsoft Entra ID (OIDC)
Okta (OIDC)
SAML
Google (OIDC)
Generic OAuth (OIDC)

Identity providers establish human browser sessions through Roster Auth. They do not replace Roster identities, do not define mcp:* or api:* scopes, and should not issue tokens that are accepted directly by /mcp or /api/v1.

Runtime login support is implemented for Google (OIDC), Microsoft Entra ID (OIDC), Okta (OIDC), Generic OAuth (OIDC), and SAML.

The protocol suffix is intentional:

• Google (OIDC), Microsoft Entra ID (OIDC), and Okta (OIDC) are provider-specific OpenID Connect login configurations.
• SAML is the generic SAML service-provider integration. Use this provider kind for SAML applications from Microsoft Entra ID, Okta, or another SAML identity provider.
• Generic OAuth (OIDC) is for custom OIDC-compatible OAuth providers that do not have a dedicated provider kind.

Roster currently supports one identity provider row per provider kind. For example, a deployment can configure one Google (OIDC) provider and one Microsoft Entra ID (OIDC) provider, but cannot configure two Google providers or two Microsoft Entra ID providers at the same time. To replace a provider of the same kind, edit the existing row.

When multiple login-capable identity providers are enabled and complete, the login page lists them by creation time, oldest first. When none are configured, the login page shows only the built-in username/password form.

Provisioning and Account Linking

Successful Google (OIDC), Microsoft Entra ID (OIDC), Okta (OIDC), Generic OAuth (OIDC), and SAML logins create a Roster team member when no active member exists for the provider subject. The created member uses the provider display name and email address, has the member role, and is marked email-verified because the email came from a trusted external provider.

Each provider has a Same-email linking policy that controls what happens when a login arrives for an email address that already belongs to a Roster Auth user but is not yet linked to that provider subject.

Mode	Behavior
Never	Rejects the login with account_not_linked unless the provider account is already linked.
Verified email only	Links to the existing user only when the provider confirms the email is verified.
Trusted provider email	Links to the existing user because an admin trusts that provider’s email assertion.

Defaults are conservative by provider kind: Google and Generic OAuth (OIDC) use Verified email only, Microsoft Entra ID (OIDC) and Okta (OIDC) use Trusted provider email, and SAML uses Never.

Disabled or deleted team members remain blocked even when the external provider still authenticates them successfully.

Bootstrap Admin

A clean database starts with the built-in form-auth administrator:

admin / admin

The first sign-in must change the default password to a strong password before the platform can be used.

Email/password sign-up is disabled. Admins create form-auth team members from the platform or add users through configured identity providers.

Microsoft Entra ID (OIDC) Login

Microsoft Entra ID uses Roster Auth’s OIDC provider path. Register a Web redirect URI in the Entra app registration:

${ROSTER_AUTH_URL}/auth/oauth2/callback/microsoft-entra-id

Set ROSTER_AUTH_URL to the public HTTPS origin and register that exact HTTPS callback URI.

Configure the Roster identity provider with:

Issuer URL:  https://login.microsoftonline.com/<tenant-id>/v2.0
Metadata URL: https://login.microsoftonline.com/<tenant-id>/v2.0/.well-known/openid-configuration
Scopes: openid profile email

An enabled Microsoft Entra ID identity provider row must include a client ID, tenant URL, and stored encrypted client secret. The secret is entered in Roster and does not require a provider-specific environment variable. Successful Entra ID logins create verified team members and write the login audit metadata:

{ "method": "oauth", "provider": "microsoft-entra-id" }

Google (OIDC) Login

Google uses Roster Auth’s built-in OIDC-capable social provider. Configure Google from the Google Auth Platform in an organization-owned Google Cloud project for shared or production environments.

Create a Web application OAuth client and register the Roster origin and callback URI:

Authorized JavaScript origin: ${ROSTER_AUTH_URL}
Authorized redirect URI:     ${ROSTER_AUTH_URL}/auth/callback/google

Set ROSTER_AUTH_URL to the public HTTPS origin and register that exact HTTPS callback URI. Each public environment can use its own OAuth client or share one client with every active callback URI registered.

Configure the Roster identity provider with:

Issuer URL: https://accounts.google.com
Scopes: openid profile email

An enabled Google identity provider row must include a client ID and a stored encrypted client secret. The secret is entered in Roster and does not require a provider-specific environment variable. Successful Google logins create verified team members and write the login audit metadata:

{ "method": "oauth", "provider": "google" }

Choose the Google Auth Platform audience based on the deployment:

• Use an internal audience when the app should only be available to users in a Google Workspace or Cloud Identity organization.
• Use an external audience when users can come from outside the organization, including consumer Gmail accounts or Google Accounts backed by non-Gmail email addresses.
• While an external app is in testing status, add each allowed test account as a test user. Broad external access may require publishing the app and completing Google’s verification flow, depending on the requested scopes.

Users still need a valid Google Account for Google login. A non-Gmail email address can work only when it belongs to Google Workspace, Cloud Identity, or a consumer Google Account created with that email address.

Okta (OIDC) Login

Okta can issue both OIDC and SAML responses, but Roster treats them as separate provider kinds. The Okta (OIDC) provider kind is for Okta OpenID Connect application settings such as issuer URL, metadata URL, client ID, client secret, and openid profile email scopes.

Create an Okta OIDC Web Application integration and register the Roster callback URI:

Sign-in redirect URI:  ${ROSTER_AUTH_URL}/auth/oauth2/callback/okta
Sign-out redirect URI: ${ROSTER_AUTH_URL}/login

Set ROSTER_AUTH_URL to the public HTTPS origin and register that exact HTTPS callback URI.

Configure the Roster identity provider with:

Issuer URL:   https://<okta-org>.okta.com
Metadata URL: https://<okta-org>.okta.com/.well-known/openid-configuration
Scopes:       openid profile email

For deployments that use an Okta custom authorization server, use the matching issuer and metadata URLs instead:

Issuer URL:   https://<okta-org>.okta.com/oauth2/default
Metadata URL: https://<okta-org>.okta.com/oauth2/default/.well-known/openid-configuration

An enabled Okta identity provider row must include a client ID, issuer URL or metadata URL, and stored encrypted client secret. The secret is entered in Roster and does not require a provider-specific environment variable. Successful Okta logins create verified team members and write the login audit metadata:

{ "method": "oauth", "provider": "okta" }

If a deployment needs Okta through SAML, configure the SAML provider kind with an Okta SAML application instead of using Okta (OIDC).

Generic OAuth (OIDC) Login

Generic OAuth (OIDC) uses Roster Auth’s generic OAuth/OIDC provider path. Use it for OIDC-compatible providers that expose an OpenID Connect discovery document and a userinfo endpoint returning an email address.

Register the Roster callback URI in the provider:

Redirect URI: ${ROSTER_AUTH_URL}/auth/oauth2/callback/generic-oauth

Set ROSTER_AUTH_URL to the public HTTPS origin and register that exact HTTPS callback URI.

Configure the Roster identity provider with:

Issuer URL:   https://<provider-host>/
Metadata URL: https://<provider-host>/.well-known/openid-configuration
Scopes:       openid profile email

An enabled Generic OAuth (OIDC) identity provider row must include a client ID, issuer URL or metadata URL, and stored encrypted client secret. The secret is entered in Roster and does not require a provider-specific environment variable. Successful Generic OAuth (OIDC) logins create verified team members and write the login audit metadata:

{ "method": "oauth", "provider": "generic-oauth" }

SAML Login

SAML uses a Roster service provider endpoint and a customer identity provider metadata document. Roster currently supports SP-initiated SAML login: users start from the Roster login page, Roster sends an authentication request, and the identity provider posts the SAML response back to Roster.

Register these Roster service provider values in the SAML application:

SP Entity ID / Audience: ${ROSTER_AUTH_URL}/auth/saml/metadata/saml
ACS / Reply URL:         ${ROSTER_AUTH_URL}/auth/saml/callback/saml
SP Metadata URL:         ${ROSTER_AUTH_URL}/auth/saml/metadata/saml

Set ROSTER_AUTH_URL to the public HTTPS origin and register the exact HTTPS SAML service provider values.

Configure the Roster identity provider with:

Entity ID / Issuer: the identity provider entity ID
Metadata URL:       the identity provider metadata URL
Certificate:        optional signing certificate override

The metadata URL must expose the identity provider SSO URL and signing certificate. The certificate field is optional when the metadata document already contains the signing certificate; use it when the customer wants to pin or override the certificate from metadata.

For Microsoft Entra ID Enterprise Applications using SAML:

• In Basic SAML Configuration, set Identifier (Entity ID) to the Roster SP Entity ID and Reply URL (Assertion Consumer Service URL) to the Roster ACS URL.
• Use the Entra App Federation Metadata URL as the Roster metadata URL.
• Ensure the SAML response includes an email address. Roster accepts common email, mail, UPN, and email-address claim names, and falls back to NameID when it is an email address.

When a SAML login succeeds, Roster creates a verified team member by email and creates a normal Roster browser session. It writes the login audit metadata:

{ "method": "saml", "provider": "saml" }

MCP OAuth Flow

For MCP OAuth, human login still goes through Roster Auth first:

/oauth/authorize
  -> Roster Auth login
  -> optional external OIDC/SAML provider
  -> Roster Auth callback/session
  -> /oauth/authorize/resume
  -> Roster MCP consent
  -> Roster-issued MCP authorization code and tokens