GoRules BRMS supports single sign-on (SSO) through OIDC providers, allowing users to authenticate with existing corporate credentials. SSO also supports mapping identity provider groups to BRMS permissions.
SSO is available on Business plan and above.
Supported providers
| Provider | Status |
|---|
| Any OIDC provider | Recommended |
| Microsoft Entra ID (Azure AD) | Supported |
| Okta | Supported |
| Keycloak | Verified |
| PingID | Verified |
OIDC PKCE (recommended)
The recommended approach using standard OIDC with PKCE. Works with any OIDC-compliant identity provider.
Minimal configuration
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/.well-known/jwks.json
When SSO_OAUTH2_JWKS_URI is not configured, BRMS will not validate the token signature. Always set the JWKS URI in production environments.
Additional options
| Variable | Description | Default |
|---|
SSO_OAUTH2_SCOPES | OAuth2 scopes to request | openid email profile |
SSO_OAUTH2_REDIRECT_URI | Callback path | /_callback |
SSO_OAUTH2_AUTHORITY_URL | Authority URL (if different from issuer) | - |
SSO_OAUTH2_IDENTITY_TOKEN_SOURCE | Token for identity claims | access_token |
SSO_OAUTH2_CUSTOM_CLAIM_NAME | JWT claim containing groups | groups |
Configure your identity provider to redirect to /_callback as this is the URL that handles OAuth callbacks.
Azure AD
1. Create an Enterprise Application
- Log in to the Azure Portal and navigate to Entra ID
- Select Enterprise applications → New application
- Click Create your own application
- Choose Register an application to integrate with Microsoft Entra ID
- Name the application (e.g.,
GoRules BRMS)
- Select Accounts in this organizational directory only (single tenant)
- Set Redirect URI to Web and enter
https://your-brms-url/oauth/azure
- After creation, navigate to Single sign-on → Go to application
- Copy the Application (client) ID
2. Add group claims (optional)
- In App registrations, open Token configuration
- Click Add group claim
- Configure claims according to your requirements
- For Access and ID tokens, select sAMAccountName
- Save
3. Create credentials
- Open Certificates & secrets
- Under Client secrets, click New client secret
- Add description, set expiry, click Add
- Copy the secret value immediately (not visible after leaving the page)
4. Copy endpoints
- In the Overview section, click Endpoints
- Copy:
- OAuth 2.0 authorization endpoint (v2)
- OAuth 2.0 token endpoint (v2)
- Authority URL:
https://login.microsoftonline.com/TENANT_ID
SSO_OAUTH2_PROVIDER=azure
SSO_OAUTH2_CLIENT_ID=<client-id>
SSO_OAUTH2_CLIENT_SECRET=<client-secret>
SSO_OAUTH2_SCOPES=openid email profile
SSO_OAUTH2_AUTH_URL=<auth-endpoint>
SSO_OAUTH2_TOKEN_URL=<token-endpoint>
SSO_OAUTH2_AUTHORITY_URL=https://login.microsoftonline.com/TENANT_ID
APP_URL=https://your-brms-url
EMAIL_ENABLED=false
Okta
1. Create an application
- Log in to your Okta Admin dashboard
- Navigate to Applications → Create App Integration
- Select OIDC - OpenID Connect and Web Application
- Name the application (e.g.,
GoRules BRMS)
- Set grant type to Authorization Code
- Set Sign-in redirect URI to
https://your-brms-url/oauth/okta
- Leave Sign-out redirect URIs empty
- Assign to necessary user groups
- Save
If Federation Broker Mode is shown, disable it.
2. Add group claims (optional)
- In the application, open Sign On tab
- In OpenID Connect ID Token, click Edit
- Set Group Claim Type to Filter
- Enter
groups, select Matches regex, enter .*
- Save
3. Copy credentials
From the General tab, copy:
SSO_OAUTH2_PROVIDER=okta
SSO_OAUTH2_CLIENT_ID=<client-id>
SSO_OAUTH2_CLIENT_SECRET=<client-secret>
SSO_OAUTH2_SCOPES=openid email profile
SSO_OAUTH2_AUTH_URL=https://your-domain.okta.com/oauth2/v1/authorize
SSO_OAUTH2_TOKEN_URL=https://your-domain.okta.com/oauth2/v1/token
APP_URL=https://your-brms-url
EMAIL_ENABLED=false
Group mapping
Map identity provider groups to BRMS roles using SSO_OAUTH2_GROUPS_MAPPING. The format is {group}->{role} comma-separated.
Global roles
Four global roles are available: owner, admin, author, and member.
SSO_OAUTH2_CUSTOM_CLAIM_NAME=groups
SSO_OAUTH2_GROUPS_MAPPING=Admins->admin,Developers->author,Users->member
member permissions.
Azure AD uses group UUIDs:
SSO_OAUTH2_SCOPES=openid email profile groups
SSO_OAUTH2_GROUPS_MAPPING=77777777-7777-7777-7777-777777777777->admin,88888888-8888-8888-8888-888888888888->author
SSO_OAUTH2_SCOPES=openid email profile groups
SSO_OAUTH2_GROUPS_MAPPING=Admins->admin,Developers->author,Users->member
SSO_OAUTH2_CUSTOM_CLAIM_NAME=resource_access.account.roles
SSO_OAUTH2_GROUPS_MAPPING=admin_role->admin,user_role->member
Fine-grained per-project mapping
For granular control per project, enable role mapping in BRMS:
SSO_OAUTH2_ROLES_MAPPING_ENABLED=true
- Navigate to Settings → Users & Roles → Roles
- Create or edit a role
- Configure:
- Role Name: Custom identifier
- IDP Groups: Map SSO groups to this role
- Project Access: Assign specific projects
- Permissions: Define granular permissions
Comparison
| Feature | Global mapping | Per-project mapping |
|---|
| Configuration | Environment variables | BRMS UI |
| Granularity | System-wide | Per-project |
| Use case | Simple admin/member split | Complex multi-project permissions |
| Required variable | SSO_OAUTH2_GROUPS_MAPPING | SSO_OAUTH2_ROLES_MAPPING_ENABLED=true |
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.
Troubleshooting
Invalid redirect URI
The redirect URI must exactly match the one registered with your IdP:
- Azure:
https://your-brms-url/oauth/azure
- Okta:
https://your-brms-url/oauth/okta
- OIDC:
https://your-brms-url/_callback
Groups not syncing
- Verify groups claim is included in tokens
- Check
SSO_OAUTH2_CUSTOM_CLAIM_NAME matches your IdP’s claim name
- Ensure users are assigned to the mapped groups in your IdP
