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

# SAML SSO Authentication

> Set up enterprise-grade SAML Single Sign-On (SSO) for secure authentication in Openlayer with step-by-step instructions for Okta, Azure AD, and Google Workspace

<img width="700" style={{ borderRadius: "0.5rem" }} src="https://mintcdn.com/openlayer-44/jN8MTVdaEnRVD4sY/images/documentation/security.png?fit=max&auto=format&n=jN8MTVdaEnRVD4sY&q=85&s=d50a0685c063cce66d4bba7a5449d9e1" alt="SAML SSO Authentication for Openlayer" data-path="images/documentation/security.png" />

## What is SAML SSO?

SAML (Security Assertion Markup Language) Single Sign-On (SSO) allows your organization to authenticate users through your identity provider (IdP), providing enhanced security and a streamlined login experience. Openlayer supports SAML SSO with all major identity providers, including Okta, Azure AD, Google Workspace, OneLogin, and more.

With SAML SSO, you can:

* Enforce your organization's authentication policies
* Simplify user management with automatic provisioning
* Enhance security with your existing IdP's features (MFA, conditional access, etc.)
* Streamline the login experience for your team members
* Authenticate bot users for automated workflows

## Setting Up SAML SSO

### Prerequisites

* Admin access to your Openlayer workspace
* Admin access to your identity provider (IdP)
* A paid Openlayer plan that includes SAML SSO support

### Configuration Steps

<Steps>
  <Step title="Access Workspace Settings">
    * Navigate to your workspace
    * Click on the workspace name in the upper left corner
    * Select "Workspace Settings"
  </Step>

  <Step title="Access Security and Privacy Settings">
    * In the Workspace Settings sidebar, click on "Security and Privacy"
  </Step>

  <Step title="Configure SAML SSO">
    * Click on the "Configure" button in the SAML SSO section - You'll be guided
      through a configuration flow
  </Step>

  <Step title="Set Up Your Identity Provider">
    During the configuration process, you'll need to provide the following information to your IdP:

    * **ACS URL (Assertion Consumer Service)**: `https://api.openlayer.com/auth/saml/callback`
    * **Entity ID**: `https://api.openlayer.com/auth/saml`
    * **Start URL**: `https://app.openlayer.com/login`

    You'll also need to configure the following SAML attributes in your IdP:

    | Attribute Name | Description                                          |
    | -------------- | ---------------------------------------------------- |
    | `email`        | User's email address (required)                      |
    | `firstName`    | User's first name (optional)                         |
    | `lastName`     | User's last name (optional)                          |
    | `groups`       | User's group memberships for role mapping (optional) |
  </Step>

  <Step title="Complete the Configuration">
    * After setting up your IdP, return to Openlayer and complete the flow
    * Your SAML SSO integration will be active once configuration is complete
    * Users can now log in using their IdP credentials
  </Step>
</Steps>

## Identity Provider Setup Instructions

Find your identity provider in the link below for specific configuration instructions:

<Card title="Identity Provider Guides" icon="file" href="https://workos.com/docs/integrations" horizontal>
  Setup instructions for Okta, Google Workspace, Azure AD and more.
</Card>

## Directory Sync and Role Mapping

Openlayer supports automatic role assignment based on IdP group membership. This allows you to manage user permissions directly through your identity provider. For a full overview of workspace roles and what each one can do, see [Roles and permissions](/security/roles-and-permissions).

When Directory Sync is set up for a workspace, membership for the workspace will be controlled entirely by Directory Sync. This means if any user is not part of any IdP groups pushed to our platform, then their membership to the workspace will get removed.

Enabling a workspace with Directory Sync also locks down the workspace to SAML SSO logins only.

### Prerequisites

* Set up SAML SSO for the Workspace

### Setting Up Directory Sync

<Steps>
  <Step title="Access Workspace Settings">
    * Navigate to your workspace - Click on the workspace name in the upper left
      corner - Select "Workspace Settings"
  </Step>

  <Step title="Access Security and Privacy Settings">
    * In the Workspace Settings sidebar, click on "Security and Privacy"
  </Step>

  <Step title="Manage Directory Sync">
    * Click on "Manage" under Directory Sync. This will open a page that guides
      you through setting up Directory Sync with your IdP provider.
  </Step>

  <Step title="Complete the Configuration">
    * Back on the Security Settings page, click on "Configure" - Map your IdP
      groups to Openlayer roles. Ensure that at least one group has Admin access.
    * If you have been locked out of admin access by enabling Directory Sync for
      your workspace, follow the next section to regain admin access to the
      Workspace.
  </Step>
</Steps>

### Preventing Workspace Lockout

After Directory Sync is set up for a workspace, it is possible to be locked out of
managing it if there are no admin-associated IdP groups pushed to our platform.

In this scenario, it is possible to take advantage of default IdP groups to get back
into the workspace. Simply create a new IdP group with a name from the list below for
the desired role of its members.

By default, Openlayer maps IdP groups to roles as follows:

* Members in IdP groups with the name `openlayer-role-admin` will be assigned admin roles
* Members in IdP groups with the name `openlayer-role-member` will be assigned member roles
* Members in IdP groups with the name `openlayer-role-member-restricted` will be assigned member restricted roles
* Members in IdP groups with the name `openlayer-role-viewer` will be assigned viewer roles (read-only access)

### Group Attribute Configuration

For role mapping to work correctly, your IdP must include group information in the SAML assertion. The exact configuration depends on your IdP:

<Tabs>
  <Tab title="Okta">
    1. In your Okta admin dashboard, go to the Openlayer application settings.

    2. Navigate to the **Sign On** tab and click **Edit** in the SAML Settings.

    3. In the **Group Attribute Statements** section, add:

       * **Name**: `groups`
       * **Filter**: Select the appropriate filter type (e.g., "Matches regex" with
         `.*` to include all groups)

    4. Create groups in Okta with the names
       `openlayer-role-admin`, `openlayer-role-member`,
       `openlayer-role-member-restricted`, and `openlayer-role-viewer`

    5. Assign users to these groups based on their required access level
  </Tab>

  <Tab title="Azure AD">
    1. In the Azure portal, go to your application's **Single sign-on** settings

    2. In the **User Attributes & Claims** section, click **Edit**

    3. Add a new group claim:

       * **Which groups to include in the token**: Choose the
         appropriate option (e.g., "All groups")
       * **Source attribute**: `groups`

    4. Create security groups in Azure AD with the names `openlayer-role-admin`,
       `openlayer-role-member`, `openlayer-role-member-restricted`, and
       `openlayer-role-viewer`

    5. Add users to these groups based on their required
       access level
  </Tab>

  <Tab title="Google Workspace">
    1. In the Google Admin console, go to the Openlayer application settings

    2. Navigate to the **SAML attribute mapping** section

    3. Add a new attribute mapping for groups:

       * **App attribute**: `groups`

       * **Google Directory
         attribute**: `Groups`

    4. Create groups in Google Workspace with the names
       `openlayer-role-admin`, `openlayer-role-member`,
       `openlayer-role-member-restricted`, and `openlayer-role-viewer`

    5. Assign
       users to these groups based on their required access level
  </Tab>
</Tabs>

## Authenticating Bot Users with SAML

Bot users (service accounts) can be authenticated using SAML SSO, allowing for automated processes and integrations while maintaining your security policies.

### Creating Bot Users in Your IdP

<Steps>
  <Step title="Create a Service Account">
    * In your IdP, create a new user account designated for bot/service use
    * Example: `bot-name@yourdomain.com` or `service-integration@yourdomain.com`
  </Step>

  <Step title="Assign Appropriate Groups">
    * Add the bot user to the appropriate IdP groups based on the required access
      level - For admin access: add to the `openlayer-role-admin` group - For member
      access: add to the `openlayer-role-member` group
  </Step>

  <Step title="Configure Authentication Method">
    * Set up authentication credentials for the bot user in your IdP
    * This typically involves creating an app password or API token, depending on your IdP
  </Step>
</Steps>

### Authenticating Bot Users in Openlayer

Bot users can authenticate to Openlayer using API Key Authentication:

<Steps>
  <Step title="Log in as the bot user">
    Log in to Openlayer as the bot user through your IdP
  </Step>

  <Step title="Create an API key">
    Navigate to Settings > Personal API Keys and create a new API key
  </Step>

  <Step title="Use the API key">
    Use this API key for programmatic access to Openlayer

    ```bash theme={null}
    # Example API request using a bot user's API key
    curl -X GET "https://api.openlayer.com/v1/workspaces/{workspaceId}" \
      -H "Authorization: Bearer BOT_USER_API_KEY"
    ```
  </Step>
</Steps>

<Info>
  API Key Authentication is currently the only supported method for bot user
  authentication in Openlayer. This provides a secure way to authenticate
  programmatic access while maintaining your security policies.
</Info>

### Provider-Specific Bot User Examples

<Tabs>
  <Tab title="Okta">
    1. In your Okta admin dashboard, go to **Directory** > **People**

    2. Click **Add Person** and create a new user with:

       * First Name: `Bot`

       * Last Name: `User` (or a descriptive name)

       * Username/Email: `bot-user@yourdomain.com`

       * Select "Set by admin" for password

    3. Go to **Directory** > **Groups**

    4. Add the bot user to the appropriate group (e.g., `openlayer-role-admin`)

    5. For API access, you can use Okta API tokens or create an OAuth service
       application
  </Tab>

  <Tab title="Azure AD">
    1. In the Azure portal, go to **Azure Active Directory** > **Users**

    2. Click **New user** > **Create new user**

    3. Fill in the required information:

       * User name: `bot-user@yourdomain.com`

       * Name: `Bot User` (or a
         descriptive name)

    4. Go to **Azure Active Directory** > **Groups**

    5. Add the bot user to the appropriate group (e.g., `openlayer-role-admin`)

    6. For automated authentication, consider using Azure service principals or managed
       identities
  </Tab>

  <Tab title="Google Workspace">
    1. In the Google Admin console, go to **Directory** > **Users**

    2. Click **Add new user** and create a new user with:

       * First name: `Bot` - Last
         name: `User` (or a descriptive name)

       * Primary email:
         `bot-user@yourdomain.com`

    3. Go to **Directory** > **Groups**

    4. Add the bot
       user to the appropriate group (e.g., `openlayer-role-admin`)

    5. For API
       access, you can use Google service accounts or OAuth 2.0 client credentials
  </Tab>
</Tabs>

## Enforcing SAML-Only Access

For enhanced security, you can configure your workspace to only allow SAML authentication:

<Steps>
  <Step title="Access Security Settings">
    Navigate to Workspace Settings > Security and Privacy
  </Step>

  <Step title="Enable SAML-Only Access">
    Enable the "SAML-Only Access" option
  </Step>

  <Step title="Confirm the Change">
    Review the implications and confirm the change
  </Step>
</Steps>

When SAML-only access is enabled:

* Users can only log in through your IdP
* Email/password authentication is disabled for all users
* API key authentication remains available for programmatic access

<Warning>
  Enabling SAML-only access will prevent users from logging in with
  email/password credentials. Ensure all users have access through your IdP
  before enabling this option.
</Warning>

## Troubleshooting

### Common Issues

<AccordionGroup>
  <Accordion title="Users Cannot Log In">
    If users successfully authenticate with your IdP but receive an error in Openlayer, check the following:

    * Verify the user exists in both your IdP and has been properly synced to Openlayer
    * Check that the email address in the SAML assertion matches exactly with the user's email in Openlayer
    * Ensure the SAML assertion includes all required attributes
  </Accordion>

  <Accordion title="Incorrect Role Assignment">
    If users log in but have incorrect permissions, verify these items: - Check
    the IdP group membership and naming conventions - Verify that group names
    exactly match the expected format (`openlayer-role-admin`, etc.) - Ensure the
    groups attribute is properly configured in your IdP's SAML settings
  </Accordion>

  <Accordion title="Bot User Authentication Failures">
    If a bot user cannot authenticate programmatically, check these common causes:

    * Ensure the bot user has been properly created in your IdP - Verify the bot
      user has logged in to Openlayer at least once manually - Check that the API
      key being used is valid and has not expired - For SAML assertion
      authentication, verify the assertion format is correct
  </Accordion>

  <Accordion title="SAML Configuration Errors">
    If you encounter errors during the SAML configuration process, verify these items:

    * Verify all URLs and entity IDs are entered correctly in your IdP
    * Check that your IdP's metadata is valid and accessible
    * Ensure all required attributes are properly mapped in your IdP
  </Accordion>
</AccordionGroup>

### Debugging SAML Issues

For more advanced troubleshooting, you can:

1. Check your IdP's authentication logs for failed SAML assertions
2. Examine the SAML response from your IdP to ensure it contains the expected attributes
3. Contact Openlayer support with the following information:
   * Screenshots of your IdP configuration
   * Timestamp of failed authentication attempts
   * Any error messages displayed

## Frequently Asked Questions

<AccordionGroup>
  <Accordion title="Which identity providers are supported?">
    Openlayer supports all major SAML 2.0 compatible identity providers, including but not limited to:

    * Okta
    * Azure Active Directory
    * Google Workspace
    * OneLogin
    * Auth0
    * PingIdentity
    * ADFS
  </Accordion>

  <Accordion title="Can I use SAML SSO with the free plan?">
    SAML SSO is available on paid plans only. Please contact our sales team for
    more information about pricing and plan options.
  </Accordion>

  <Accordion title="How do I migrate existing users to SAML SSO?">
    Existing users can continue to use their current login method until you enable
    SAML-only access. We recommend the following migration process: 1. Set up SAML
    SSO for your workspace. 2. Ensure all users are properly configured in your
    IdP. 3. Have users test logging in with SAML before enforcing SAML-only
    access. 4. Once confirmed working for all users, enable SAML-only access.
  </Accordion>

  <Accordion title="Can I use multiple identity providers?">
    Currently, Openlayer supports one identity provider per workspace. If you need
    to support multiple IdPs, please contact our support team to discuss your
    requirements.
  </Accordion>

  <Accordion title="Does SAML SSO support multi-factor authentication (MFA)?">
    Yes, Openlayer respects the authentication policies configured in your
    identity provider, including MFA. Configure MFA in your IdP, and it will be
    enforced during the SAML authentication process.
  </Accordion>

  <Accordion title="What happens if my IdP is temporarily unavailable?">
    If your IdP is unavailable, users will not be able to log in via SAML SSO.
    If you have SAML-only access enabled, this means users will not be able to access Openlayer until your IdP is available again.
    API keys will continue to work for programmatic access.
  </Accordion>
</AccordionGroup>