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

# SSO — Generic SAML 2.0

> Configure SAML SSO between any SAML 2.0 IdP and gavAI

This page is the universal SAML 2.0 reference for IdPs that don't have a vendor-specific guide (PingFederate, Auth0 as IdP, Keycloak, Shibboleth, ADFS, etc.). The gavAI-side counterpart is the wizard at `/console/settings/sso/new/generic`.

## Prerequisites

* Admin access to your IdP.
* Workspace admin in gavAI on a Scale or Enterprise plan.
* One or more email domains you control.

## What gavAI expects

The Service Provider config gavAI runs:

| Field                    | Value                                                                 |
| ------------------------ | --------------------------------------------------------------------- |
| **Entity ID (Audience)** | shown in the wizard at `/console/settings/sso/new/generic`            |
| **ACS URL**              | shown in the wizard                                                   |
| **NameID Format**        | `urn:oasis:names:tc:SAML:1.1:nameid-format:emailAddress`              |
| **Binding**              | HTTP-POST for ACS; HTTP-Redirect for AuthnRequest                     |
| **Signed AuthnRequest**  | Not required (gavAI accepts unsigned)                                 |
| **Signed Assertion**     | **Required**. Signed by your IdP's signing certificate.               |
| **Signed Response**      | Optional; if your IdP signs the Response envelope, gavAI verifies it. |
| **Encrypted Assertion**  | Not required.                                                         |

## Attributes

Map the following at minimum:

| SAML attribute               | Source                       |
| ---------------------------- | ---------------------------- |
| `email` (or NameID)          | user's primary email address |
| `firstName` (or `givenName`) | user's first name            |
| `lastName` (or `surname`)    | user's last name             |

## 1. Register gavAI as a Service Provider in your IdP

Use the Entity ID + ACS URL above. Most IdPs accept those two values plus the SP metadata XML, which gavAI exposes at the URL shown in the wizard.

## 2. Hand IdP metadata to gavAI

The simplest path: paste your IdP's metadata URL into the gavAI wizard. gavAI fetches it, validates the certificate, and stores the SSO config.

If your IdP doesn't expose a metadata URL, paste the raw metadata XML instead.

## 3. Verify domains

gavAI shows a TXT record for each email domain. Add it to your DNS, then wait for re-verification.

## 4. Test

Sign in at `https://gavai.io/login` with an IdP-managed account. Audit-log traffic appears at `/console/activity`.

## Troubleshooting

| Symptom                         | Likely cause                                                                                     |
| ------------------------------- | ------------------------------------------------------------------------------------------------ |
| `InvalidSignature` in audit log | Your IdP's signing cert rotated; refresh the metadata URL in `/console/settings/sso/<provider>`. |
| `AudienceMismatch`              | Entity ID in your IdP config doesn't exactly match gavAI's. Re-copy from the wizard.             |
| `RequestExpired`                | Clock skew between your IdP and gavAI's runtime exceeds 5 minutes.                               |
| `EmailDomainNotAllowed`         | The signed-in user's email domain isn't in the verified list yet.                                |