​
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 NameDescription
emailUser’s email address (required)
firstNameUser’s first name (optional)
lastNameUser’s last name (optional)
groupsUser’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

Choose your identity provider below for specific configuration instructions:

1

Create a SAML Application

  1. In your Okta admin dashboard, go to Applications > Applications
  2. Click Create App Integration
  3. Select SAML 2.0 as the sign-on method and click Next
2

Configure Basic Settings

  1. Name your application (e.g., “Openlayer”)
  2. Add an optional logo
  3. Click Next
3

Configure SAML Settings

In the SAML Settings section, enter:

  • Single sign-on URL: https://api.openlayer.com/auth/saml/callback
  • Audience URI (SP Entity ID): https://api.openlayer.com/auth/saml
  • Default RelayState: Leave empty
  • Name ID format: EmailAddress
  • Application username: Email
4

Configure Attribute Statements

In the Attribute Statements section, add:

  • email = user.email
  • firstName = user.firstName
  • lastName = user.lastName

In the Group Attribute Statements section, add:

  • groups = Matches regex .* (to include all groups)
5

Finish Setup

  1. Complete the setup and click Finish
  2. Assign the application to the appropriate users and groups

​
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.

​
Default Role Mapping

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

  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, and openlayer-role-viewer
  5. Assign users to these groups based on their required access level

Full directory sync configuration through the UI is currently in development. For advanced directory sync options, please contact support.

​
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

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

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

  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

​
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

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

​
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

​
Support

If you encounter any issues with SAML SSO configuration or bot user authentication, please contact our support team at support@openlayer.com.