> ## 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

![SAML SSO Authentication for Openlayer](https://mintcdn.com/openlayer-44/jN8MTVdaEnRVD4sY/images/documentation/security.png?fit=max\&auto=format\&n=jN8MTVdaEnRVD4sY\&q=85\&s=d50a0685c063cce66d4bba7a5449d9e1)

## 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

**1. Access Workspace Settings**

* Navigate to your workspace
* Click on the workspace name in the upper left corner
* Select "Workspace Settings"

**2. Access Security and Privacy Settings**

* In the Workspace Settings sidebar, click on "Security and Privacy"

**3. Configure SAML SSO**

* Click on the "Configure" button in the SAML SSO section - You'll be guided
  through a configuration flow

**4. 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) |

**5. 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

## Identity Provider Setup Instructions

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

> [card] [Identity Provider Guides](https://workos.com/docs/integrations)
>
> Setup instructions for Okta, Google Workspace, Azure AD and more.

## 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](https://docs.openlayer.com/security/roles-and-permissions.md).

When Directory Sync is set up for a workspace, it controls role assignment for members in that directory.

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

> [!NOTE]
>
> When Directory Sync manages a workspace, email invites are disabled. To grant
> access, add the person to an IdP group mapped to the workspace under
> **Workspace Settings → Security and Privacy**, then have them sign in with
> SSO.

### Prerequisites

* Set up SAML SSO for the Workspace

### Setting Up Directory Sync

**1. Access Workspace Settings**

* Navigate to your workspace - Click on the workspace name in the upper left
  corner - Select "Workspace Settings"

**2. Access Security and Privacy Settings**

* In the Workspace Settings sidebar, click on "Security and Privacy"

**3. 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.

**4. 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.

### Mapping a group to No access

Alongside Admin, Member, Member Restricted and Viewer, a group can be mapped to **No access**. The
configuration screen separates the groups you have given a role from the ones set to No access, so
you can see at a glance who the sync actually grants access to.

Use it for groups that your IdP pushes to Openlayer but that should not be able to use the
workspace, such as a company-wide group that exists only so directory sync can see everyone. Members
of a No access group keep a membership, so they stay visible and can be promoted later by moving
their group to a real role, but they hold no permissions and the workspace does not appear in their
workspace switcher. See [Roles and permissions](https://docs.openlayer.com/security/roles-and-permissions.md#the-no-access-role).

At least one group must still be mapped to Admin.

### What reconciliation keeps in sync

Directory sync does not only add members. It reconciles the workspace against your IdP on an ongoing
basis, so it also:

* **Corrects role drift.** A member whose role no longer matches their group mapping is moved back to
  the mapped role.
* **Removes members who left.** A user deleted in your directory, or who no longer belongs to any
  mapped group, loses their membership.
* **Leaves other members in place.** Members who are not in your directory, such as people who joined
  with a password, Google sign-in, or an invite, are not removed by reconciliation.

Changes made by reconciliation are recorded and can be reviewed in the workspace
[audit trail](https://docs.openlayer.com/security.md#audit-trail).

### 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:

> [tab] 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] 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] 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

## 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

**1. 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`

**2. 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

**3. 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

### Authenticating Bot Users in Openlayer

Bot users can authenticate to Openlayer using API Key Authentication:

**1. Log in as the bot user**

Log in to Openlayer as the bot user through your IdP

**2. Create an API key**

Navigate to Settings > Personal API Keys and create a new API key

**3. 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"
```

> [!NOTE]
>
> 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.

### Provider-Specific Bot User Examples

> [tab] 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] 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] 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

## Enforcing SAML-Only Access

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

**1. Access Security Settings**

Navigate to Workspace Settings > Security and Privacy

**2. Enable SAML-Only Access**

Enable the "SAML-Only Access" option

**3. Confirm the Change**

Review the implications and confirm the change

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.

## Troubleshooting

### Common Issues

> [accordion] 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] 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] 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] 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

### 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

> [accordion] 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] 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] 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] 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] 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] 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.


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.