> ## 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](/access/self-managed-sso): where each
value goes in your IdP and the per-provider screens for Okta, Microsoft Entra ID, and
Google Workspace. Set up the connection in the SSO portal first, then use this page to
enter the values in your IdP.

<Warning>
  Take your **ACS URL**, **Entity ID**, and **metadata URL** from the SSO portal
  (**Settings > Single Sign-On & SCIM**). The Entity ID contains an **auto-generated
  connection 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 portal shows the exact strings:

| Field                | Value                                                                  |
| -------------------- | ---------------------------------------------------------------------- |
| ACS URL (Reply URL)  | shown in the SSO portal (`https://auth.gecko.security/login/callback`) |
| Entity ID (Audience) | shown in the SSO portal (ends in your auto-generated 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 portal. 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 SSO portal.
    4. On **Service provider details**, paste Gecko's **ACS URL** and **Entity ID**
       from the SSO portal. 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 SSO portal, 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 portal.
  </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 SSO portal, configure
    the claims, then assign users. The **SAML Certificates** section holds the
    **Federation Metadata XML** you enter back in the portal.
  </Accordion>
</AccordionGroup>

Once the app exists and users are assigned, return to the
[SSO portal](/access/self-managed-sso) to enter your IdP's sign-in URL and signing
certificate, verify, and test. That page also covers the common sign-in errors.