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

# SAML provider reference

> Per-provider screens and field values for connecting a SAML 2.0 IdP to Gecko.

This is the SAML reference for [Single Sign-On](/docs/access/self-managed-sso): where each
value goes in your IdP and the per-provider screens for Okta, Microsoft Entra ID, and
Google Workspace. Start the connection from **Settings > Single Sign-On & SCIM**
first, then use this page to enter the values in your IdP.

<Warning>
  Take your **ACS URL**, **Entity ID**, and **metadata URL** from the setup wizard
  that opens when you click **Connect**. The Entity ID contains a **connection ID
  derived from your team's internal ID** (such as `gecko-okta-72468ca55845447aa90c`).
  Copy it exactly, and don't build it from your team slug; a mismatch is the top
  cause of failed logins.
</Warning>

## Service-provider values

These go into your IdP's SAML app. The setup wizard shows the exact strings:

| Field | Value |
| - | - |
| ACS URL (Reply URL) | shown in the setup wizard |
| Entity ID (Audience) | shown in the setup wizard (ends in your connection ID) |
| Name ID format | `EmailAddress` |
| Name ID value | the user's work email |

<Tip>
  Instead of entering these by hand, import Gecko's **SP metadata** into your IdP
  using the metadata URL from the setup wizard. It carries the ACS URL, Entity ID, and
  Gecko's signing certificate in one go, so the values can't drift.
</Tip>

**Attributes** your IdP must send in the assertion:

| Attribute | Claim name | Required |
| - | - | - |
| Email | `http://schemas.xmlsoap.org/ws/2005/05/identity/claims/emailaddress` | Yes |
| First name | `http://schemas.xmlsoap.org/ws/2005/05/identity/claims/givenname` | Recommended |
| Last name | `http://schemas.xmlsoap.org/ws/2005/05/identity/claims/surname` | Recommended |
| Groups | `groups` | Only for group-based role mapping |

The Name ID already carries the email, which satisfies the minimum. Send first and
last name too so Gecko can show real names on assignees and in the audit log;
providers that only expose atomic fields (such as Google Workspace) have no single
display-name attribute, so map the two separately.

## Provider setup

<AccordionGroup>
  <Accordion title="Google Workspace">
    Set this up in the **Google Admin console** at
    [admin.google.com](https://admin.google.com) as a **super admin**, not from
    Gmail or a regular user account.

    1. Go to **Apps → Web and mobile apps**, then **Add app → Add custom SAML app**.
    2. Name the app (for example, `Gecko`) and click **Continue**.
    3. On **Google Identity Provider details**, copy the **SSO URL** and download the
       **Certificate** (or **Download metadata**). These are the IdP details you enter
       back in the setup wizard.
    4. On **Service provider details**, paste Gecko's **ACS URL** and **Entity ID**
       from the setup wizard. Set **Name ID format** to `EMAIL` and **Name ID** to
       **Basic Information > Primary email**.
    5. On **Attribute mapping**, map **First name** and **Last name** to the
       given-name and surname claims above. Google has no single display-name field,
       so map the two separately; Gecko composes the name from them. (Primary email is
       already covered by the Name ID.) Click **Finish**.
    6. Open the app, click **User access**, and turn it **On** for everyone or the org
       units that should use Gecko.
  </Accordion>

  <Accordion title="Okta">
    In the Okta admin console: **Applications → Create App Integration → SAML 2.0**.
    Enter Gecko's **ACS URL** and **Entity ID** from the setup wizard, set the
    **Name ID** and attributes, then assign users. The app's **Sign On** tab exposes
    the **identity provider metadata** URL you enter back in the setup wizard.
  </Accordion>

  <Accordion title="Microsoft Entra ID">
    In the Entra admin center: **Enterprise applications → New application → Create
    your own application** (non-gallery). Under **Single sign-on → SAML**, enter
    Gecko's **ACS URL** (Reply URL) and **Entity ID** from the setup wizard, configure
    the claims, then assign users. The **SAML Certificates** section holds the
    **Federation Metadata XML** you enter back in the setup wizard.
  </Accordion>
</AccordionGroup>

Once the app exists and users are assigned, enter your IdP's sign-in URL and
signing certificate in the wizard, then verify and test from
[Settings > Single Sign-On & SCIM](/docs/access/self-managed-sso). That page also
covers the common sign-in errors.