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

# Set up SAML SSO with Okta

> Configure the Okta application and send the right metadata and group mappings to Webless.

<Info>
  Webless handles the Firebase SAML configuration. Your team only needs to
  configure the Okta app and send the resulting IdP metadata and group mappings.
</Info>

## Prerequisites

* Okta admin access
* Your SAML provider ID from Webless
* The ACS URL from Webless

## Configure Okta

<Steps>
  <Step title="Collect the values from Webless" icon="key">
    Webless will provide:

    * Your SAML provider ID, such as `saml.okta.client1`
    * The ACS URL, such as `https://webless-frontend.firebaseapp.com/__/auth/handler`
  </Step>

  <Step title="Create the SAML app in Okta" icon="app-window">
    In Okta, create a new **SAML 2.0** app integration and use the provider ID
    in the app name so the app is easy to identify.
  </Step>

  <Step title="Enter the required SAML settings" icon="settings-2">
    Use these values exactly.

    | Field                | Value                                                      |
    | -------------------- | ---------------------------------------------------------- |
    | Single Sign On URL   | `https://webless-frontend.firebaseapp.com/__/auth/handler` |
    | Recipient URL        | `https://webless-frontend.firebaseapp.com/__/auth/handler` |
    | Audience Restriction | Your exact provider ID                                     |
    | Name ID Format       | `EmailAddress`                                             |
    | Application username | `Email`                                                    |
  </Step>

  <Step title="Add attributes and groups" icon="users">
    Add the following attribute statements:

    | Name        | Format      | Value            |
    | ----------- | ----------- | ---------------- |
    | `email`     | Unspecified | `user.email`     |
    | `firstName` | Unspecified | `user.firstName` |
    | `lastName`  | Unspecified | `user.lastName`  |

    Then add a group attribute statement so Okta emits the full group list:

    | Name     | Format      | Filter |
    | -------- | ----------- | ------ |
    | `groups` | Unspecified | `.*`   |
  </Step>

  <Step title="Assign groups and users" icon="user-round-check">
    Create and assign your admin and user groups to the SAML app. Common examples
    include:

    * Admin groups: `admin`, `administrator`, `team_lead`, `managers`
    * User groups: `user`, `employee`, `staff`, `general`
  </Step>

  <Step title="Send the IdP metadata to Webless" icon="send">
    Send all of the following to Webless:

    * The Okta SSO URL
    * The Entity ID or Issuer
    * The full X.509 certificate
    * The list of admin group names
    * The list of user group names
    * Your email domain
    * Your authentication preferences for SAML, Google login, and password login
  </Step>

  <Step title="Test login" icon="badge-check">
    After Webless enables your domain, sign in with SSO and verify the expected
    role assignment.

    * Admin users should receive `{domain}_admin`
    * Regular users should receive `{domain}_user`
  </Step>
</Steps>

## Troubleshooting

<AccordionGroup>
  <Accordion title="Groups are not being sent" icon="triangle-alert">
    * Verify the group attribute statement exists
    * Verify users are assigned to the correct Okta groups
    * Verify those groups are assigned to the SAML application
  </Accordion>

  <Accordion title="Users receive the wrong roles" icon="shield-x">
    * Verify the group names you gave Webless exactly match the group names in
      Okta
    * Verify the affected users belong to the expected groups
  </Accordion>

  <Accordion title="Audience restriction errors appear" icon="shield-alert">
    The Audience URI in Okta must exactly match the provider ID Webless gave
    you, including case.
  </Accordion>
</AccordionGroup>