Skip to main content
SAML SSO Authentication for Openlayer

​
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:
  • Okta
  • Azure AD
  • Google Workspace
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:
  • Okta
  • Azure AD
  • Google Workspace
  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

  • Okta
  • Azure AD
  • Google Workspace
  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

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

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
SAML SSO is available on paid plans only. Please contact our sales team for more information about pricing and plan options.
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.
Currently, Openlayer supports one identity provider per workspace. If you need to support multiple IdPs, please contact our support team to discuss your requirements.
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.
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.

​
Support

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