SSO Authentication via OIDC PKCE

BRMS supports Single Sign-On (SSO) authentication using the OpenID Connect (OIDC) protocol with PKCE (Proof Key for Code Exchange). This provides a secure, standards-based authentication flow that works with any OIDC-compliant identity provider.

Verified Identity Providers

While BRMS should work with any standards-compliant OIDC provider, it has been verified with:

• Okta
• Microsoft Entra ID (Azure AD)
• Keycloak
• PingID

1. Minimal Configuration

To enable OIDC SSO, configure the following required environment variables:

Example:

SSO_OAUTH2_PROVIDER=oidc
SSO_OAUTH2_CLIENT_ID=your-client-id
SSO_OAUTH2_ISSUER=https://your-idp.example.com
SSO_OAUTH2_JWKS_URI=https://your-idp.example.com/protocol/openid-connect/certs

❗️

When the provider is set to oidc and SSO_OAUTH2_JWKS_URI is not configured, BRMS will not validate the token signature. ALWAYS set the JWKS URI in production environments. You should only remove this variable if you know what you are doing, for example you are hosting BRMS API behind API Gateway with Authorizers configured.

📘

Upon setting configuration you will need to re-deploy BRMS for changes to take effect.

2. Additional Configuration Options

📘

You should configure your application to redirect to /_callback as this is the URL that handles callbacks.

3. SSO Permissions and Role Mapping

BRMS supports two levels of permissions with two different mapping approaches:

Permission Levels

1. Global Permissions (Configured via Environment Variables)

   • admin - Full system access and administrative capabilities
   • member - Standard user access

2. Per Project/Repository Permissions (Configured inside BRMS)

   • Fine-grained access control for individual projects and repositories
   • Configurable through the BRMS UI with automatic IDP group mapping

Method 1: Global User Type Mapping (Environment Variables)

Automatically map SSO groups/roles to global permission levels using environment variables.

Required Environment Variables

SSO_OAUTH2_CUSTOM_CLAIM_NAME=groups
SSO_OAUTH2_GROUPS_MAPPING=<group-mappings>

Configuration Examples

Example 1: Keycloak Role Mapping

For Keycloak, roles are typically nested under resource_access.account.roles. Configure as follows:

SSO_OAUTH2_CUSTOM_CLAIM_NAME=resource_access.account.roles
SSO_OAUTH2_GROUPS_MAPPING=Infra_architect->admin,tech_manager->admin,developers->member

Example 2: Standard Groups Claim

For identity providers that use a simple groups claim:

SSO_OAUTH2_CUSTOM_CLAIM_NAME=groups
SSO_OAUTH2_GROUPS_MAPPING=AdminGroup->admin,ManagerGroup->admin,UserGroup->member

How Global Mapping Works

1. Extract Groups from Token: BRMS reads the claim specified in SSO_OAUTH2_CUSTOM_CLAIM_NAME from the JWT token
2. Match Against Mapping: Compares user's groups against the mappings defined in SSO_OAUTH2_GROUPS_MAPPING
3. Assign Permission:
   • If user belongs to a mapped group → Assign the specified permission (admin or member)
   • If user doesn't belong to any mapped group → Assign default member permission

Mapping Format

<sso-group-name>->admin,<another-group>->admin,<third-group>->member

• Comma-separated list of mappings
• Each mapping: <SSO_GROUP_NAME>-><PERMISSION_LEVEL>
• Permission levels: admin or member

Method 2: Fine-Grained Per-Project Role Mapping (BRMS UI)

For more granular control, BRMS allows you to define custom roles with specific permissions per project and automatically map them to IDP groups.

Enable Fine-Grained Role Mapping

Add the following environment variable:

SSO_OAUTH2_ROLES_MAPPING_ENABLED=true

Configure Roles in BRMS

Once enabled, administrators can configure roles through the BRMS interface:

1. Navigate to Settings > Users & Roles > Roles
2. Create a new role or update an existing one
3. Configure the following:
   • Role Name: Custom role identifier
   • IDP Groups: Tag-based selector to map SSO/IDP groups to this role
   • Project Access: Assign access to specific projects
   • Permissions: Define granular permissions for this role

How Per-Project Mapping Works

1. User logs in with SSO credentials
2. BRMS extracts groups from the user's token (using SSO_OAUTH2_CUSTOM_CLAIM_NAME)
3. BRMS matches token groups against the idpGroups field in defined roles
4. User is automatically assigned to matching roles with their configured permissions
5. Permissions are applied on a per-project basis

4. Summary

💡

Best Practice: Use both methods together—environment variable mapping for global admins, and per-project mapping for fine-grained control. Global admins have access to every project.