# Set up single sign-on (SSO)

import { Steps } from "@astrojs/starlight/components"

**Single sign-on (SSO)** lets people sign in to Mindflow with your company identity provider (IdP) instead of a local
password. Mindflow supports **OIDC** and **SAML2** with providers such as Microsoft Entra ID (Azure), Okta,
PingIdentity, AWS IAM Identity Center, Google, and Cloudflare. SSO is not self-service in Studio—Mindflow configures
the tenant after you share the IdP details securely.

## When to use

- Your organization requires corporate IdP login for Mindflow.
- You are migrating existing username/password users to SSO.
- Prefer the sign-in page SSO buttons only after Customer Success confirms activation for your tenant.

Before you begin, involve your IdP administrators. Decide whether you need OIDC or SAML2, and whether you will migrate
existing Mindflow users or start with new SSO-only accounts.

## Guide

### Plan migration and protocol

If you already have Mindflow users, SSO sign-ups create **new** profiles unless Mindflow runs a migration to merge
them. You can keep password sign-in enabled during a transition when Mindflow configures that option.

1. **Choose the migration path.** New SSO-only users with no merge, or migrate existing non-SSO users after setup.
2. **Choose the protocol.** OIDC or SAML2, based on what your IdP supports for Mindflow.

### Collect IdP credentials and attribute mapping

Gather secrets in a secure channel—never paste client secrets or metadata into chat or tickets in the clear.

1. **Collect protocol credentials.** For OIDC: client ID and client secret. For SAML2: metadata URL (or metadata your
   IdP exports).
2. **Map required attributes.** Email (required), full name (required), profile picture URL (optional).
   - OIDC: simple claim names such as `email` or `name`.
   - SAML2: often URIs such as `https://schemas.xmlsoap.org/ws/2005/05/identity/claims/emailaddress`. Some IdPs (for
     example AWS IAM Identity Center) allow simpler mappings—follow your IdP docs.

### Work with Customer Success

Mindflow applies the IdP configuration on your Cognito-backed tenant and tells you when sign-in is ready.

1. **Share the plan securely.** Send migration choice, protocol, credential handles (not plaintext in email if
   possible), and attribute mapping to Customer Success.
2. **Wait for activation.** Mindflow notifies you when the IdP is configured and gives you the callback URL for your
   tenant.

### Configure the callback URL in your IdP

After Mindflow activates SSO, register the callback (redirect / ACS) URL in your IdP so authentication responses return
to Mindflow.

1. **Register the callback.** Use the URL Mindflow provides. Typical shapes:
   - OIDC: `https://auth-<tenant>.mindflow.io/oauth2/idpresponse`
   - SAML2: `https://auth-<tenant>.mindflow.io/saml2/idpresponse`
     Replace `<tenant>` with your tenant slug. Some environments use a different root domain—use the exact URL from
     Customer Success.
2. **Test sign-in.** Open the Mindflow sign-in page and use **Sign in with** your provider. Confirm a test user lands
   in the correct organization.

## Example

A company already on Okta SAML wants all operators on SSO. IT picks SAML2, maps email and name claims, shares the
metadata URL with Customer Success, then pastes `https://auth-acme.mindflow.io/saml2/idpresponse` into Okta. Existing
users are merged in a follow-up migration so each person keeps one Mindflow profile.

## Keep in mind

- Always handle IdP secrets securely.
- Attribute mapping mistakes are a common failure mode—plan a short trial-and-error window with a test account.
- Facebook, Apple, and consumer “Sign in with Amazon” are not Mindflow enterprise SSO paths; use the IdPs listed above.
- Mindflow can close email **Sign Up** for your tenant while SSO and existing password sign-in stay available. Ask
  Customer Success if you need that lock for an SSO-first rollout. Operators then join through **Sign in with** your
  provider or an administrator-created account—see [Sign in](/getting-started/sign-in/#create-an-account).

Related: [Sign in](/getting-started/sign-in/#create-an-account), [Manage users](../../manage-access/manage-users/).