Single sign-on (SSO)

Your users can sign in to Masttro with your organization's identity provider instead of a Masttro password. This guide is for the identity or IT administrator who registers Masttro in Microsoft Entra ID, Okta or another OpenID Connect provider.

How it works

Masttro uses OpenID Connect with the authorization code flow and PKCE (S256). Masttro is registered as a public client, so there is no client secret to create, share or rotate.
SSO is configured per Masttro instance (the name in your login URL, for example {{WEB_APP_URL}}/acme). One application in your identity provider serves the whole instance.
Masttro matches the signed-in person to their Masttro user by the email in the access token issued by your identity provider. Each user must already exist in Masttro with the same email address.
The same application is used everywhere a user signs in with SSO: the Masttro web application, the Masttro phone and tablet apps, and the MCP server sign-in used by AI assistants such as Claude and ChatGPT.

Redirect URIs

Your identity provider only returns users to addresses you allow. Add each of these to the Masttro application. Use lowercase characters only.

Used by	Redirect URI	Microsoft Entra ID platform	Okta
Masttro web application	`{{WEB_APP_URL}}/[instance]`	Single-page application	Sign-in redirect URI
Masttro phone app	`store.masttro.token://oidc/callback`	Mobile and desktop applications	Sign-in redirect URI
Masttro tablet app	`store.masttro.dfo://oidc/callback`	Mobile and desktop applications	Sign-in redirect URI
MCP server (AI assistants)	`{{MCP_SSO_REDIRECT_URI}}`	Mobile and desktop applications	Sign-in redirect URI

Entra ID: don't add the MCP URI as a single-page application The MCP sign-in is completed by the Masttro authorization server, not by the browser. Entra ID only lets a browser redeem sign-ins for single-page application URIs, so registering the MCP URI there fails with AADSTS9002327. Add it under Mobile and desktop applications instead. See Microsoft Entra ID.

The mobile app redirect URIs are only needed if your users sign in to the Masttro phone or tablet app with SSO, and the MCP redirect URI only if they will connect AI assistants to Masttro. Adding them doesn't change how users sign in to the web application.

What to send Masttro

After you register the application, send these values to your Masttro representative. None of them is a secret.

Value	Microsoft Entra ID	Okta	Other providers
Client ID	Application (client) ID	Client ID	Client ID
Issuer	OpenID Connect metadata document URL	Issuer URI of your authorization server	Issuer or discovery document URL
Scope	Application ID URI and scope name	Not needed (Masttro requests `openid email`)	Any custom scope your access tokens require

Masttro configures your instance with these values and then tests the sign-in with you before SSO is turned on for your users.

Setup guides

Microsoft

Microsoft Entra ID

Formerly Azure Active Directory.

Okta

Okta Workforce Identity.

OpenID Connect

Other providers

Ping, Auth0, Google and any other OpenID Connect provider.

Troubleshooting

Symptom	Fix
Entra ID `AADSTS50011` or Okta "redirect_uri is not whitelisted"	The redirect URI isn't registered, or it differs from the one in the table (check lowercase and a trailing `/`). If it happens only in the phone or tablet app, the mobile app redirect URI is missing.
Entra ID `AADSTS9002327` when connecting an AI assistant	The MCP redirect URI is registered as a single-page application. Move it to Mobile and desktop applications.
Sign-in at the identity provider works, then Masttro shows "Invalid credentials"	The access token has no email, or the email doesn't match the user's email in Masttro. In Entra ID, check the optional email claim.
"Single sign-on is not available for this organization"	SSO isn't configured yet for that Masttro instance, or the instance name is misspelled. Contact your Masttro representative.