OpenID Connect
How to configure Bindplane to use OpenID Connect for Authentication
This feature is only available for Bindplane Enterprise, Google Enterprise and Google Editions.
Changing the Authentication type on the Bindplane server will automatically remove all existing users and permissions. The first user to log in after the change will become an Organization Admin and owner of all existing Projects. Subsequent users will need to be re-invited to their respective projects or provisioned properly via custom claims.
1. Prerequisites
Before beginning, ensure you have the following:
An OpenID Connect (OIDC) provider configured and available.
OAuth2 Client ID and Client Secret from your OIDC provider.
2. Identity Provider Configuration
Each Identity Provider will have different steps for configuring an OIDC application. Below are details commonly needed for most configurations.
Bindplane uses an Authorization Code flow
Redirect URI: <remoteURL/webURL>/oidc/redirect
3. Bindplane Server Configuration
Configuration Steps
Open the Bindplane configuration file (by default at
/etc/bindplane/config.yaml).Add or modify the following OIDC configuration settings:
auth:
type: oidc
oidc:
issuer: "https://your-oidc-provider.com"
oauth2ClientID: "your-client-id"
oauth2ClientSecret: "your-client-secret"
scopes:
- openid
- profile
- emailReplace the placeholder values:
issuer: Your OIDC provider's URLoauth2ClientID: OAuth2 client ID from your OIDC provideroauth2ClientSecret: OAuth2 client Secret from your OIDC provider
Optional: Just-In-Time Provisioning with Custom Claims
Enable disableInvitations to require users to have valid custom claims for provisioning. This enables just-in-time (JIT) provisioning without requiring manual invitations.
When disableInvitations is enabled, users must provide valid custom claims in their OIDC token to be provisioned. When disabled (default), users can log in with an invitation code even without custom claims. See Custom Claims Mapping below.
Restart Bindplane to apply the changes:
Environment Variables
The same settings can also be provided using environment vairables:
4. Custom Claims Mapping
Custom claims in your OIDC token enable automatic role assignment and project access provisioning during login. Bindplane supports two approaches: IdP groups/roles and direct token claims.
Supported Custom Claims
bindplane_default_role
string
Default role for users when no project-specific role is set. Values: admin, user, viewer
"admin"
bindplane_org_admin
string
Whether the user is an organization administrator. Values: "true", "false"
"true"
bindplane_projects
string
Comma-separated list of project/project IDs with optional per-project roles
"project1,project2" or "admin:project1,user:project2"
groups or group_ids
array/string
IdP groups for role inference
["bindplane-admin", "bindplane-projects-<Project-1>"]
roles
array/string
IdP roles for role inference
["bindplane-user"]
Approach 1: Direct Token Claims
Direct token claims provide explicit role assignments via custom claims in the OIDC token.
Example token payload:
Claims Behavior:
bindplane_default_role: Sets the default role for projects without a project-specific role. Defaults to
viewerif not set.bindplane_org_admin: When
"true", the user becomes an organization administrator withadminrole on all projects. Organization admins ignorebindplane_projectsandbindplane_default_roleclaims as the user will gain admin access to all projects within the organization.bindplane_projects: Comma-separated list of project IDs. Two formats are supported:
Project IDs only (e.g.,
"<Project-ID-1,Project-ID-2>"): User gets the role frombindplane_default_role, orviewerif not set.Per-project roles (e.g.,
"admin:<Project-ID-1>,user:<Project-ID-2>,viewer:<Project-ID-3>"): User gets the specified role for each projects, overridingbindplane_default_role.
When bindplane_projects is set, the user only has access to listed projects. Existing access to unlisted projects are revoked.
Approach 2: Groups-Based Role Inference
If your OIDC provider doesn't support custom claims, you can use IdP groups or roles for role inference.
Recognized group/role names (case-insensitive):
bindplane-admin→adminrolebindplane-user→userrolebindplane-viewer→viewerroleadmin,user,viewer→ corresponding role
Project membership via groups: Use the prefix bindplane-projects-<Project-ID> to grant access to specific projects:
Groups behavior:
The first matching role name (case-insensitive) in groups sets the default role
If
bindplane-org-admingroup is present, the user becomes an organization admin and project admin across all the projects.Groups matching
bindplane-projects-<Project-ID>grant access to those projects
Example token payload:
Result: User gets admin role access to <PROJECT-1> and <PROJECT-2>.
Role Assignment Priority
When both approaches are present:
Explicit
bindplane_default_roleclaim → Uses this role (ignores groups/roles)Groups/roles inference → Infers role from IdP groups (if
bindplane_default_rolenot set)Per-project roles in
bindplane_projects→ Uses specified role for each project
Example with mixed claims:
Result:
User gets
adminrole for<PROJECT-ID-1>(explicit claim overrides everything)Groups are ignored (because
bindplane_default_roleis set)For any other project, user gets
admin(frombindplane_default_role, not from groups)
Least Privileged User (LPU) Principle
When a user has multiple explicit role assignments across different projects (via role:projectId format), Bindplane applies the least privileged principle.
Role hierarchy (most to least privileged):
LPU behavior: The minimum privilege from explicit assignments becomes the fallback role for projects without explicit role assignment. This ensures users don't inadvertently gain unintended access.
Example:
User gets
adminonProject 1User gets
vieweronProject 2
Organization Admin vs Project Access
Organization Admins (bindplane_org_admin: "true"):
User becomes an organization administrator
User gets
adminrole on all projects in the organizationbindplane_projectsandbindplane_default_roleclaims are ignored
Project-Level Access (bindplane_org_admin unset or "false"):
User gets access based on
bindplane_projectsandbindplane_default_roleAccess is scoped to projects listed in
bindplane_projectsRole defaults to
viewerif not specified
Conflicting Claims Resolution
If a user's token contains conflicting information, Bindplane resolves it as follows:
Multiple role assignments: LPU principle applies; the least privileged role is used as the fallback
Organization admin + project access: Organization admin takes precedence; project claims are ignored
Invalid role names: Unrecognized role values default to
viewerMalformed project IDs: Invalid entries in
bindplane_projectsare skipped
Note: If the token/claims are incorrect or not parsed correctly then no provisioning changes are made and their logins retain their pre-existing permissions.
5. User Enrollment
After configuration, users will be redirected to your OIDC provider for authentication when accessing Bindplane.
The first user that logs in after configuration will be automatically created as the Organization Admin. Subsequent users will need to be invited or manually added to a Project before they are able to login using OIDC. For more details on adding additional users see:
When disableInvitations is enabled, user role and project access are synced on every login, ensuring changes to IdP claims are reflected immediately in Bindplane.
6. Token claim name customizations
Starting in Bindplane version v1.100.2, within the server configuration you can modify the default names of bindplane_default_role , bindplane_org_admin, bindplane_projects to fit whatever schema/organizational naming policy limitations. Configure these under auth.oidc.customClaims .
Below are the fields that you can use to customize where Bindplane looks in the token to provision users.
auth.oidc.customClaims.groups
groups
auth.oidc.customClaims.groupIds
group_ids
auth.oidc.customClaims.roles
roles
auth.oidc.customClaims.organizationAdmin
bindplane_org_admin
auth.oidc.customClaims.projects
bindplane_projects
auth.oidc.customClaims.defaultRole
bindplane_default_role
Use these to change the IdP group/role membership strings Bindplane matches (not JWT claim names). They apply to values in the groups claims configured above.
auth.oidc.customClaims.orgAdminGroupName
bindplane-org-admin
auth.oidc.customClaims.projectsGroupPrefix
bindplane-projects-
auth.oidc.customClaims.adminGroupName
bindplane-admin
auth.oidc.customClaims.userGroupName
bindplane-user
auth.oidc.customClaims.viewerGroupName
bindplane-viewer
Last updated
Was this helpful?