Skip to main content

Documentation Index

Fetch the complete documentation index at: https://docs.gorules.io/llms.txt

Use this file to discover all available pages before exploring further.

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.
The recommended approach uses standard OIDC with PKCE flow. This method works with any OIDC-compliant identity provider and has been tested with Microsoft Entra ID, Okta, Keycloak, and PingOne.

​
Step 1: Create an OIDC application

Create a new OIDC/OAuth application in your identity provider. Configure it as a public client (SPA) with PKCE enabled. Set the redirect URI to: 
{YOUR_APP_URL}/_callback
For provider-specific instructions:

​
Step 2: Configure BRMS

Set these environment variables with values from your OIDC application: 
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
Always set SSO_OAUTH2_JWKS_URI in production. Without it, BRMS cannot validate token signatures.

​
Provider examples

SSO_OAUTH2_PROVIDER=oidc
SSO_OAUTH2_CLIENT_ID=0oaycgerypftkPwxE697
SSO_OAUTH2_ISSUER=https://your-domain.okta.com/oauth2/default
SSO_OAUTH2_JWKS_URI=https://your-domain.okta.com/oauth2/default/v1/keys

​
Additional options

VariableDescriptionDefault
SSO_OAUTH2_SCOPESOAuth2 scopes to requestopenid email profile
SSO_OAUTH2_REDIRECT_URICallback path/_callback
SSO_OAUTH2_AUTHORITY_URLAuthority URL (if different from issuer)-
SSO_OAUTH2_IDENTITY_TOKEN_SOURCEToken for identity claimsaccess_token
SSO_OAUTH2_CUSTOM_CLAIM_NAMEJWT claim containing groupsgroups

​
Azure AD (legacy)

This is a legacy integration that uses internal sessions. For new deployments, use OIDC PKCE with Microsoft Entra ID instead.

​
1. Create an Enterprise Application

  1. Log in to the Azure Portal and navigate to Entra ID
  2. Select Enterprise applications → New application
  3. Click Create your own application
  4. Choose Register an application to integrate with Microsoft Entra ID
  5. Name the application (e.g., GoRules BRMS)
  6. Select Accounts in this organizational directory only (single tenant)
  7. Set Redirect URI to Web and enter https://your-brms-url/oauth/azure
  8. After creation, navigate to Single sign-on → Go to application
  9. Copy the Application (client) ID

​
2. Add group claims (optional)

  1. In App registrations, open Token configuration
  2. Click Add group claim
  3. Configure claims according to your requirements
  4. For Access and ID tokens, select sAMAccountName
  5. Save

​
3. Create credentials

  1. Open Certificates & secrets
  2. Under Client secrets, click New client secret
  3. Add description, set expiry, click Add
  4. Copy the secret value immediately (not visible after leaving the page)

​
4. Copy endpoints

  1. In the Overview section, click Endpoints
  2. Copy:
    • OAuth 2.0 authorization endpoint (v2)
    • OAuth 2.0 token endpoint (v2)
    • Authority URL: https://login.microsoftonline.com/TENANT_ID

​
5. Configure BRMS

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 (legacy)

This is a legacy integration that uses internal sessions. For new deployments, use OIDC PKCE with Okta instead.

​
1. Create an application

  1. Log in to your Okta Admin dashboard
  2. Navigate to Applications → Create App Integration
  3. Select OIDC - OpenID Connect and Web Application
  4. Name the application (e.g., GoRules BRMS)
  5. Set grant type to Authorization Code
  6. Set Sign-in redirect URI to https://your-brms-url/oauth/okta
  7. Leave Sign-out redirect URIs empty
  8. Assign to necessary user groups
  9. Save
If Federation Broker Mode is shown, disable it.

​
2. Add group claims (optional)

  1. In the application, open Sign On tab
  2. In OpenID Connect ID Token, click Edit
  3. Set Group Claim Type to Filter
  4. Enter groups, select Matches regex, enter .*
  5. Save

​
3. Copy credentials

From the General tab, copy:
  • Client ID
  • Client Secret

​
4. Configure BRMS

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
See Okta documentation for composing your base URL.

​
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
Users not in any mapped group receive member permissions.

​
Provider-specific formats

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
Okta uses group names: 
SSO_OAUTH2_SCOPES=openid email profile groups
SSO_OAUTH2_GROUPS_MAPPING=Admins->admin,Developers->author,Users->member
Keycloak uses nested claims: 
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
Then configure roles through the BRMS UI:
  1. Navigate to Settings → Users & Roles → Roles
  2. Create or edit a role
  3. Configure:
    • Role Name: Custom identifier
    • IDP Groups: Map SSO groups to this role
    • Project Access: Assign specific projects
    • Permissions: Define granular permissions

​
Comparison

FeatureGlobal mappingPer-project mapping
ConfigurationEnvironment variablesBRMS UI
GranularitySystem-widePer-project
Use caseSimple admin/member splitComplex multi-project permissions
Required variableSSO_OAUTH2_GROUPS_MAPPINGSSO_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:
  • OIDC PKCE (recommended): https://your-brms-url/_callback
  • Azure (legacy): https://your-brms-url/oauth/azure
  • Okta (legacy): https://your-brms-url/oauth/okta

​
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