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

# SAML SSO

> Allow your team to sign in to Galtea through your company's identity provider using SAML 2.0 single sign-on

> [!WARNING]
>
> You are reading the docs of Galtea 5.10. [Read this page in the latest version](https://docs.galtea.ai/security/saml-sso.md).

## Overview

SAML SSO (Security Assertion Markup Language Single Sign-On) lets your team sign in to Galtea using your company's existing identity provider (IdP) — such as Microsoft Entra ID (Azure AD), Okta, or Google Workspace — instead of a separate password.

When SSO is active, users authenticate with the identity provider. The provider then sends a signed SAML assertion to Galtea, which creates or updates the user session. No Galtea password is needed.

> [!NOTE]
>
> SAML SSO is an **Enterprise feature**. Contact [support@galtea.ai](mailto:support@galtea.ai) to enable it for your organization.

## Prerequisites

* You must be an **Owner** of the Galtea organization.
* You must have admin access to your identity provider.

## How it works

```
User → Galtea login → redirected to your IdP → user authenticates → IdP sends SAML response → Galtea creates session
```

Galtea acts as the **Service Provider (SP)**. Your company's directory (Azure AD, Okta, Google Workspace, etc.) is the **Identity Provider (IdP)**.

## Setup overview

Follow these four steps to connect your identity provider:

**1. Create a SAML application in your IdP**

Add Galtea as a new SAML application inside your identity provider's admin console.

**2. Configure Galtea's SP values in the IdP**

Copy the **ACS URL** and **SP Entity ID** from Galtea's organization settings into your IdP.

| Galtea value | What to enter |
| - | - |
| ACS URL | `https://api.galtea.ai/auth/saml/callback` |
| SP Entity ID | The value you enter in the **SP Entity ID** field in Galtea's settings |

**3. Copy IdP values into Galtea**

After saving in your IdP, copy these two values back into Galtea's **Organization Settings → Advanced Options**:

| IdP value | Galtea field |
| - | - |
| IdP SSO URL | **Sign on URL** |
| X.509 certificate | **Public Certificate** |

**4. Save and test**

Save the organization settings. Ask a team member to sign in using the **Team Slug** shown in the **SAML Configuration** section of your Organization Settings.

## Configuration fields

Open **Organization Settings** and scroll to the **Advanced Options** section. The following fields control SAML SSO.

> [!NOTE]
>
> Only organization Owners can view and edit these fields.

| Field | Description |
| - | - |
| **Sign on URL** | The IdP's SSO endpoint. Copy it from your identity provider. Example: `https://login.microsoftonline.com/{tenant}/saml2` |
| **SP Entity ID** | A unique identifier for your organization within the identity provider. **You define this value.** It can be a short string (e.g. `my-company`), a URL, or a URN. The same value must be registered in both Galtea and your identity provider. Enter this same value in the **Issuer** field too. |
| **Issuer** | The issuer Galtea sends in SAML requests, also used as the expected **audience** of the IdP's response. Set it to the **same value as the SP Entity ID**. Your IdP's Identifier / Entity ID / Audience must match this value. |
| **Public Certificate** | The X.509 signing certificate from your IdP, in PEM format (starts with `-----BEGIN CERTIFICATE-----`). |
| **Signed Response** | Require the IdP to sign the full SAML response. Enabled by default. Most enterprise IdPs support this. |
| **Signed Assertions** | Require the IdP to sign the assertions inside the SAML response. These two toggles must match **what your IdP actually signs**. If you are unsure, enable both — most modern IdPs (Azure AD, Okta, Google Workspace) support signing both. If sign-in fails with an *Invalid signature* error, your IdP is likely signing only one of the two: turn the other off so the settings match (for example, disable **Signed Assertions** when the IdP signs only the response). |
| **Force password authentication** | Disabled by default: the IdP decides how to authenticate the user. That is what lets an IdP such as ADFS sign in a user who already has an active Windows session, with no password prompt. Enable it only when your policy requires Galtea to ask for a password form on every sign-in. |

## How users sign in

After SAML is configured, users sign in using the **Team Slug** assigned to your organization.

1. Open the Galtea login page.
2. Click **Continue with SAML SSO**.
3. Enter the **Team Slug** (shown in the **SAML Configuration** section of your Organization Settings).
4. Click **Continue** — the browser redirects to your identity provider.
5. Authenticate with the identity provider.
6. The browser returns to Galtea with an active session.

On first sign-in, Galtea creates a new user account linked to the SAML identity. On later sign-ins, the same account is reused. Matching happens only inside the organization the sign-in targets: Galtea matches accounts by **email** and by **SAML NameID**, and on first sign-in the two get linked, so an existing account found by one gets the other attached. If the email belongs to an active account in a different organization, Galtea refuses the sign-in instead of matching, reusing, or changing that account. If the email and the SAML NameID already belong to two different accounts in the same organization, sign-in fails and the accounts must be reconciled manually.

> [!NOTE]
>
> In this SAML setup, users are created with the default **Member** role. Galtea does **not** read group or role claims from your IdP — the IdP controls *who* can sign in, not *what* role they receive in Galtea. To grant **Owner** or **Admin**, change the user's role manually in Galtea after their first sign-in.

## Provider-specific guides

Follow the guide for your identity provider:

> [card] [Microsoft Entra ID (Azure AD)](https://docs.galtea.ai/v5.10/security/saml-sso/azure.md)
>
> Configure SAML SSO with Microsoft Entra ID.

> [card] [Okta](https://docs.galtea.ai/v5.10/security/saml-sso/okta.md)
>
> Configure SAML SSO with Okta.

> [card] [Google Workspace](https://docs.galtea.ai/v5.10/security/saml-sso/google.md)
>
> Configure SAML SSO with Google Workspace.

## Certificate format

The public certificate must be in PEM format. PEM is a base64-encoded certificate wrapped in header and footer lines:

```
-----BEGIN CERTIFICATE-----
MIIDpDCCAoygAwIBAgIGAX...
-----END CERTIFICATE-----
```

Most identity providers offer a "Download Certificate (Base64)" or "PEM" option. If you download a `.cer` or `.crt` file, open it in a text editor — if it starts with `-----BEGIN CERTIFICATE-----`, it is already in PEM format.

## Troubleshooting

| Error | Likely cause | Fix |
| - | - | - |
| `unknown_team_slug` | The team slug entered does not match any organization | Check the Team Slug in Organization Settings |
| `saml_auth_failed` / `Invalid signature` | The certificate is wrong, **or** the **Signed Response** / **Signed Assertions** toggles don't match what the IdP signs | Re-download the IdP certificate and paste it again. If the certificate is correct, make **Signed Response** / **Signed Assertions** match exactly what your IdP signs (see [Configuration fields](#configuration-fields)); for example, disable **Signed Assertions** if the IdP signs only the response |
| `saml_disabled` | SAML SSO is not enabled for your account | Contact [support@galtea.ai](mailto:support@galtea.ai) |
| `saml_foreign_organization` | The email address already belongs to an active user in a different organization. Galtea refuses the sign-in on purpose | An owner of the organization that holds the address removes the account there, or the person signs in with an address that organization does not hold |
| `organization_frozen` | The organization is frozen, so Galtea refuses a person who has no account in it yet. Existing users still sign in, with read-only access | Contact [support@galtea.ai](mailto:support@galtea.ai) |
| Assertion expired | Clock difference between IdP and Galtea servers | Ensure the IdP server clock is accurate (up to 90 seconds of skew is accepted) |
| Users are asked for a password even though they have an active Windows session on the corporate network | **Force password authentication** is enabled, so Galtea asks the IdP for a password form instead of letting it choose the method | Turn off **Force password authentication** in Organization Settings (see [Configuration fields](#configuration-fields)) so the IdP can sign the user in silently |


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.