One-click Microsoft

Part of Authio Lobby

For customers on Microsoft Entra ID, this is the fastest way to turn on SSO and the path you should lead with. Instead of walking an IT admin through an App registration, redirect URIs, client secrets, and Graph permissions, the admin grants admin consent once and Authio does the rest through Microsoft Graph.

What the admin sees

1. In your dashboard, open the organization, go to the Features tab → Single Sign-On, and click Connect Microsoft. (Only an org owner or admin can start the flow.)
2. The browser is sent to Microsoft’s admin-consent screen. A Microsoft tenant admin approves Authio’s provisioning app for their directory.
3. Microsoft redirects back to Authio, which provisions the connection and bounces the admin back to the dashboard with a Microsoft connected confirmation. The connection is already active — nothing else to fill in.

What Authio auto-creates

After consent, Authio calls Microsoft Graph against the customer’s tenant and, in sequence:

• Instantiates an application + service principal from the Microsoft “custom enterprise app” template via applicationTemplates/{id}/instantiate — both objects are created atomically.
• Configures OIDC on the application: signInAudience: AzureADMyOrg, Authio’s per-connection redirect URI, and a groups claim on the id_token.
• Adds a client secret (addPassword, ~2-year expiry) — the plaintext is read once and immediately sealed with envelope encryption before it touches the database.

Authio then writes an sso_connections row with protocol = oidc, provider = entra, status = active, and managed_by = microsoft_graph, recording the Entra tenant id, app id, and the discovered issuer (https://login.microsoftonline.com/{tenant}/v2.0). If any Graph step fails, Authio best-effort deletes the half-created app so the tenant isn’t left with an orphan.

The flow, end to end

Dashboard (your customer's admin)                    Authio
─────────────────────────────────        ──────────────────────────────
1. Click "Connect Microsoft"
   POST /v1/session/orgs/{orgId}/ms-provision/start
                                          2. Mints a single-use request,
                                             returns a Microsoft
                                             admin-consent URL
3. Browser → login.microsoftonline.com/organizations
   /v2.0/adminconsent  (admin approves)
                          ↓
                                          4. Microsoft → Authio:
                                             GET /v1/sso/microsoft/consent/callback
                                             ?admin_consent=True&tenant=...&state=...
                                          5. Graph: instantiate app + SP,
                                             configure OIDC, add secret
                                          6. Seal secret, upsert connection
                                             status=active, managed_by=microsoft_graph
7. Redirect back to dashboard
   ?ok=microsoft_connected&connection=sso_...
                          ↓
            SSO is live for this organization.

Operator / self-hosting setup

One-click Microsoft relies on a single multitenant Entra application that you, the Authio operator, own — not one per customer. You register it once; customers only ever grant consent to it. Until it’s configured the Connect Microsoft button is hidden / disabled and the management API answers 503 ms_provision_not_configured; customers can still use OIDC or SAML.

1. Register a multitenant app in your Entra tenant. Add the Microsoft Graph application permission Application.ReadWrite.All (this is what lets Authio create apps in the customer tenant after their admin consents).
2. Add the consent callback as a redirect URI: https://sso.authio.com/v1/sso/microsoft/consent/callback (swap in your SSO service origin).
3. Create a client secret for the app.
4. Set the environment variables below on the services.

# authio_sso service — the multitenant provisioning app's credentials
AUTHIO_MS_PROVISION_CLIENT_ID=...          # the multitenant app (client) id
AUTHIO_MS_PROVISION_CLIENT_SECRET=...      # its client secret

# Hosts allowed as the post-consent dashboard return URL (comma-separated,
# https only). Read by both authio_sso and authio_management-api.
AUTHIO_MS_CONSENT_RETURN_HOSTS=dashboard.authio.com,app.acme.com

Related

• Connecting an identity provider — the three-option overview.
• OIDC connections — what one-click produces, and the manual generic-OIDC path.
• Migrate from WorkOS — why one-click Microsoft is the WorkOS-parity onboarding.