Single Sign-On (Cloud)

This feature is currently available only for Enterprise, Enterprise (Google Edition), and Honeycomb customers in Bindplane Cloud.

Bindplane Cloud offers a Single Sign-On (SSO) feature, allowing organization admins to set up access controls using common identity providers (IdPs) like Okta, Microsoft Entra, or custom OIDC/SAML implementations.

Prerequisites

Before setting up SSO, ensure you have:

1. An Enterprise or Enterprise (Google Edition) plan

2. Admin privileges in your Bindplane organization

3. Access to your identity provider's admin console

4. A basic understanding of SAML/OIDC protocols

Important Notes

User Management

• Your email is the primary identifier for your account. The OIDC/SAML response must include the email scope for proper user role transition upon login.

• User permissions are managed via Bindplane's Role-Based Access Control (RBAC) system.

• New users logging in through SSO will automatically become organization members with Project Viewer access to all projects.

• Organization Admins can modify user roles after their first login.

Custom Claim Mapping

You can automatically assign roles and project access to users by configuring custom claims in your identity provider. This feature enables fine-grained access control during SSO login without requiring manual role adjustments.

If your identity provider does not support custom claims, you can alternatively use group or role naming conventions that Bindplane will recognize during login.

Supported Custom Claims:

• bindplane_org_admin (boolean) - Grants organization admin privileges to the user

  • When true: Admin for all projects and admin for the org

  • When false or unset: Standard role-based access applies

• bindplane_role (string) - Sets the default role for the user across projects

  • Accepted values: admin, user, viewer

  • Overridden by project-specific role mappings (see bindplane_projects below)

  • If unset and bindplane_projects is not specified: User receives viewer role

• bindplane_projects (comma-separated string) - Specifies which projects the user can access

  • Format 1: Project IDs only — project-id-1,project-id-2,project-id-3 (all use bindplane_role)

  • Format 2: With per-project roles — admin:project-id-1,user:project-id-2,viewer:project-id-3

  • Supported role prefixes: admin, user, viewer

  • When not specified: User receives access (either the bindplane_role or viewer if unspecified) to all projects in the organization

  • Existing project access is automatically removed if the project is not in this list

  • You may find the Project ID by going to https://app.bindplane.com/p/{project-id}/support

Custom Claim Examples:

{
  "bindplane_org_admin": true
}

This user becomes an organization admin with Project Admin access to all projects.

{
  "bindplane_role": "admin",
  "bindplane_projects": "project-1,project-2"
}

This user gets Admin role on project-1 and project-2, and loses access to other projects.

{
  "bindplane_role": "viewer",
  "bindplane_projects": "admin:project-prod,viewer:project-staging"
}

This user gets Admin access to project-prod and Viewer access to project-staging.

Please ensure your claim mappings are correctly configured before completing SSO setup.

Role Sync Behavior

When using custom claims for role mapping, it's important to understand how Bindplane syncs roles between your identity provider and the application.

How sync works:

• Role assignments from your IdP are applied each time a user logs in.

• If an org admin changes a user's role in Bindplane, that change takes effect immediately.

• However, the next time that user logs in, their role will sync back to whatever the IdP specifies.

What this means in practice:

• Only admins can modify user roles directly in Bindplane. Those changes take effect immediately but are temporary. The next login will re-sync the user's role from the IdP.

Using groups or roles instead of custom claims

If your identity provider does not easily support custom claims, you can populate the user's groups or roles fields with specific naming formats, and Bindplane will extract the role and project information during login:

• Default role: Use bindplane-admin, bindplane-user, or bindplane-viewer in groups/roles

• Organization admin: Use bindplane-org-admin in groups/roles

• Project access: Use bindplane-projects-{project-id} or bindplane-projects-{role}:{project-id} in groups/roles

  • Without role prefix: bindplane-projects-prod-cluster applies the default role to the project

  • With role prefix: bindplane-projects-admin:01KSOMEPROJECTID assigns a specific role to that project

Example: If a user has groups:

groups: [
    "bindplane-admin",
    "bindplane-projects-admin:{project-id-1}",
    "bindplane-projects-viewer:{project-id-2}",
    "bindplane-org-admin"
]

They will be assigned the Admin default role, admin access to the first project, viewer access to the second project, and organization admin privileges.

Authentication Methods

• Once an IdP is connected, social logins (Google) and username/password authentication are no longer available as authentication methods. Existing users are not removed. As long as the email address in the SSO response matches their existing Bindplane account (case-sensitive), they will continue to have access and simply authenticate through SSO going forward.

• If you delete the last IdP connection, traditional authentication methods will be re-enabled.

• In case of IdP unavailability, users with existing sessions will continue to work, but new logins will be blocked until the IdP is restored.

Security Best Practices

1. IdP Configuration

   • Enable MFA in your IdP

   • Configure appropriate session timeouts

   • Set up proper user provisioning/deprovisioning workflows

2. Access Management

   • Regularly audit user access

   • Implement least-privilege access principles

   • Monitor SSO login attempts and failures

Setup Guide

1. Access Organization Settings

As an organization admin, log in to your Bindplane organization and navigate to the organization page. Locate the Single Sign-On section.

2. Configure Connection

• Select "Add Identity Provider" to configure a new IdP connection.

• Provide a friendly display name for the connection. This name will be visible to users during login.

• We recommend that the organization admin enable SSO bypass for themselves before adding the first Identity Provider. This will prevent them from being locked out in the case that the provider was misconfigured or experiencing errors.

• Optionally, you can also provide a custom logo URL, which may be shown to users when they are selecting which IdP to authenticate with (e.g., we can show a Bindplane logo to differentiate a custom OIDC connection from an Okta connection).

• Select your identity provider from the list and follow the provider-specific instructions.

• Configure custom claims (optional): If you want to automatically assign roles and project access using custom claims, configure the following claims in your identity provider:

  • bindplane_org_admin (boolean) - Set to true for organization admins

  • bindplane_role (string) - Set to admin, user, or viewer

  • bindplane_projects (string) - Comma-separated project IDs with optional role prefixes (e.g., admin:proj1,user:proj2)

  • Refer to the Custom Claim Mapping section for detailed formatting and examples.

WARNING

Always test your connection before enabling it. If you enable a connection that is improperly configured, you may lock yourself out of your Bindplane organization. If you need any assistance, please contact support.

3. Test and Enable

• Use the test connection feature to verify your setup.

• Review the ID token returned by your identity provider. Here are examples of what it should contain:

Using Custom Claims:

{
  "sub": "user-id-12345",
  "email": "[email protected]",
  "bindplane_role": "admin",
  "bindplane_org_admin": true,
  "bindplane_projects": "admin:{project-id-1},viewer:{project-id-2}",
  "iat": 1234567890,
  "exp": 1234571490
}

Using Groups/Roles (when custom claims are not supported):

{
  "sub": "user-id-12345",
  "groups": ["bindplane-admin", "bindplane-org-admin", "bindplane-projects-admin:{project-id-1}", "bindplane-projects-viewer:{project-id-2}"],
  "iat": 1234567890,
  "exp": 1234571490
}

• Review the test results carefully. For the best experience with Bindplane:

  • email (recommended): Including this field improves usability significantly. If provided, it must match the exact casing of your Bindplane account email. If it doesn't match your current login credential, you can:

    1. Cancel the SSO enablement workflow

    2. Create a new user within Bindplane with the matching email

    3. Invite them to your projects

    4. Elevate them to organization and project administrator

    5. Restart the SSO workflow from your new organization admin account

  • Role/Project Claims (optional): Include bindplane_role, bindplane_org_admin, or bindplane_projects in custom claims, or populate the groups array with the naming conventions described above, to automatically assign roles and project access. Without these, users receive the default viewer role.

• Enable the connection when ready.

4. Finalize Setup

Complete the setup process in Bindplane:

5. Sign In Using IdP

You can now sign into Bindplane by visiting app.bindplane.com and following the "Continue with SSO" option. Enter your organization's name, then continue to complete your authentication with your configured identity provider.

6. Adding New Users

If you would like to add new users to the organization after SSO is configured, you will first need to add them to the identity provider that was added to Bindplane.

After a new user is added to the IdP and signs into Bindplane for the first time, they will be granted the "Viewer" role to projects within the organization. You may then go into each project and adjust the user's roles or remove them from unneeded projects.

SSO Bypass

To prevent being locked out from your organization in the case of issues with the SSO connection, you can allow individual organization admins to bypass SSO using email and password. Only organization admins can make this change.

Steps to enable SSO bypass for a user:

1. Select Enable SSO Bypass from the dropdown menu for the desired user.

2. They will receive an invitation to create a new account at their provided email address.

3. When they accept the invitation, ensure that they are logged out from their SSO account.

4. Create a new email/password account with the same email address.

5. Verify their email address using the email sent to them.

6. They can now sign in to the organization without SSO using the new email/password account.

Troubleshooting

Login Failures

• Verify the IdP's connection settings

• Check user email mapping

• Ensure proper role assignment

Role Assignment Issues

• Confirm the email scope in your IdP's configuration

• If using custom claims for role mapping, verify that the claims are correctly formatted and sent in the ID token:

  • bindplane_org_admin must be a boolean value

  • bindplane_role must be (admin, user, or viewer)

  • bindplane_projects must be a comma-separated string with optional role prefixes (e.g., admin:proj1,user:proj2)

• Check that the role names in custom claims are spelled correctly and in lowercase

• Verify that project IDs in bindplane_projects match the actual project IDs in Bindplane

• If a user's role was changed in Bindplane but reverted after they logged in again, see Role Sync Behavior for how IdP claims interact with Bindplane role assignments

Custom Claims Not Applied

• Confirm that custom claims are included in the ID token, not just the access token

• Check that claim names are exactly as specified (case-sensitive: bindplane_org_admin, bindplane_role, bindplane_projects)

• Verify that your IdP configuration includes these custom claims in the token response

• If the user's role isn't updated on subsequent logins, ensure the IdP continues to send updated claim values

Access Denied After SSO Login

• If a user loses access to projects after updating bindplane_projects claims, this is expected behavior — projects not listed in the claim are automatically removed.

• To restore access, update the bindplane_projects claim to include the desired projects and role mapping.

Connection Problems

• Validate the IdP's endpoints

• Check network connectivity

• Verify certificate validity

Support

If you encounter any issues not covered here, please contact support with the following information:

• Your organization name

• IdP type and configuration

• Any error messages or logs

• Steps to reproduce the issue