> ## Documentation Index
> Fetch the complete documentation index at: https://docs.minoa.io/llms.txt
> Use this file to discover all available pages before exploring further.

# Single Sign-On (SSO)

> Enable seamless authentication for your team with SSO

## Overview

Single Sign-On (SSO) allows your team to access Minoa using your organization's existing identity provider, eliminating the need for separate passwords. Once configured, users sign in through your identity provider instead of managing separate Minoa credentials.

## Benefits

* **Enhanced Security**: Centralized authentication and access control
* **Simplified Access**: One set of credentials for all your tools
* **Faster Onboarding**: New team members get instant access
* **Compliance**: Meet security and regulatory requirements

## Out-of-the-Box Providers

Minoa provides built-in SSO support for these identity providers:

* **Microsoft** (Azure AD / Microsoft Entra ID)
* **Google** (Google Workspace)

These providers can be configured directly in your Minoa settings without additional setup.

<Note>
  **Google Workspace can be set up two different ways.** The built-in **Google** option above uses
  `google.com` OAuth and is the simplest choice for most organizations. If you need SAML-based
  authentication through Google Workspace (for example, to enforce SSO via Google's Identity
  Service or to meet compliance requirements), configure Google Workspace as a **custom SAML
  provider** using the Custom Identity Providers section below instead. The two setups are
  mutually exclusive per tenant.
</Note>

<Info>Contact our support team to enable SSO for your organization.</Info>

## Custom Identity Providers

For organizations using other identity providers, Minoa supports custom SSO configuration using:

* **OpenID Connect (OIDC)** — Recommended
* **SAML 2.0**

<Warning>
  Custom SSO configuration requires assistance from our support team. We recommend using OIDC over SAML for easier
  setup and better compatibility.
</Warning>

### Setting Up Custom OIDC

To configure a custom OIDC identity provider (such as Okta, Auth0, or other OIDC-compliant providers), you'll need to create an OIDC Web App in your identity provider and share the following details with our support team:

**Required Information:**

* **Client ID**: The OAuth client identifier
* **Client Secret**: The OAuth client secret
* **Issuer URL**: The OpenID Connect issuer URL (e.g., `https://your-org.okta.com/oauth2/default`)
* **Scopes**: The OAuth scopes to request (we recommend at least: `openid`, `email`, `profile`)

<Note>
  After you provide this information, our support team will configure SSO for your organization. The setup typically
  takes 1-2 business days.
</Note>

### Setting Up Custom SAML

Minoa supports SAML 2.0 with all major identity providers, including:

* Okta
* Azure AD
* OneLogin
* Google Workspace

<Info>We generally recommend using OIDC over SAML for easier setup and better compatibility.</Info>

The setup is a three-step exchange between your team and Minoa support:

**1. Contact our support team to start the setup.**

We'll share the two Minoa-side values you need to register the app in your identity provider:

* An **ACS (Assertion Consumer Service) URL**
* A tenant-specific **SP Entity ID**

**2. Create a SAML 2.0 app in your identity provider** using those two values, and configure:

* **NameID / primary identifier**: set to the user's email address
* **Attribute mapping** (recommended): the user's display name, and optionally their profile photo
* **Login flow**: Minoa supports **SP-initiated login only** (IdP-initiated login is not supported)

**3. Share the following three credentials back with our support team** so we can complete the Minoa-side configuration:

* **IdP SSO URL**
* **IdP Issuer (Entity ID)**
* **IdP X.509 certificate**

Once we receive these, we'll enable the connection and test the sign-in flow with you.

<Note>
  Setup typically takes 1-2 business days after we receive your three IdP credentials.
</Note>

## User Provisioning

Read more about how to automatically provision and deprovision users using [SCIM](/pages/integrations/authentication/scim). SCIM ensures your Minoa user list stays in sync with your identity provider.

## Troubleshooting

<AccordionGroup>
  <Accordion title="Users can't sign in with SSO">
    **Check these items:**

    1. Verify SSO is enabled for your organization
    2. Confirm users are assigned to the Minoa application in your identity provider
    3. Check that the redirect URL is correctly configured
    4. Verify the user's email address matches between your identity provider and Minoa
  </Accordion>

  <Accordion title="SSO redirects to error page">
    **Troubleshooting steps:**

    1. Verify the SSO configuration details (Client ID, Issuer URL, etc.) are correct
    2. Check that the redirect URI in your identity provider matches Minoa's expected URL
    3. Ensure the required scopes are configured
    4. Contact support if the issue persists
  </Accordion>

  <Accordion title="Users created via SSO missing roles">
    **Solution:**

    Use [SCIM](/pages/integrations/authentication/scim) to automatically assign roles when users are provisioned. SCIM allows you to map identity provider groups to Minoa roles.
  </Accordion>
</AccordionGroup>