> ## 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.

# Single sign-on

> Authenticate to GoRules BRMS using any OIDC provider.

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.

<Note>
  SSO is available on Business plan and above.
</Note>

## OIDC PKCE (recommended)

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:

* [Microsoft Entra ID](https://learn.microsoft.com/en-us/entra/identity-platform/quickstart-register-app)
* [Okta](https://developer.okta.com/docs/guides/implement-grant-type/authcodepkce/main/#set-up-your-app)
* [Keycloak](https://www.keycloak.org/docs/latest/server_admin/#_oidc_clients)
* [PingOne](https://docs.pingidentity.com/pingone/applications/p1_applications_add_applications.html)

### Step 2: Configure BRMS

Set these environment variables with values from your OIDC application:

```shell theme={null}
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
```

<Warning>
  Always set `SSO_OAUTH2_JWKS_URI` in production. Without it, BRMS cannot validate token signatures.
</Warning>

### Provider examples

<CodeGroup>
  ```shell Okta theme={null}
  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
  ```

  ```shell Keycloak theme={null}
  SSO_OAUTH2_PROVIDER=oidc
  SSO_OAUTH2_CLIENT_ID=brms
  SSO_OAUTH2_ISSUER=https://keycloak.example.com/realms/your-realm
  SSO_OAUTH2_JWKS_URI=https://keycloak.example.com/realms/your-realm/protocol/openid-connect/certs
  ```

  ```shell Microsoft Entra ID theme={null}
  SSO_OAUTH2_PROVIDER=oidc
  SSO_OAUTH2_CLIENT_ID=your-application-client-id
  SSO_OAUTH2_ISSUER=https://login.microsoftonline.com/YOUR_TENANT_ID/v2.0
  SSO_OAUTH2_JWKS_URI=https://login.microsoftonline.com/YOUR_TENANT_ID/discovery/v2.0/keys
  ```

  ```shell PingOne theme={null}
  SSO_OAUTH2_PROVIDER=oidc
  SSO_OAUTH2_CLIENT_ID=your-application-client-id
  SSO_OAUTH2_ISSUER=https://auth.pingone.eu/YOUR_ENVIRONMENT_ID/as
  SSO_OAUTH2_JWKS_URI=https://auth.pingone.eu/YOUR_ENVIRONMENT_ID/as/jwks
  ```
</CodeGroup>

### 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`               |

## Azure AD (legacy)

<Warning>
  This is a legacy integration that uses internal sessions. For new deployments, use [OIDC PKCE](#oidc-pkce-recommended) with Microsoft Entra ID instead.
</Warning>

### 1. Create an Enterprise Application

1. Log in to the [Azure Portal](https://portal.azure.com) 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

```shell theme={null}
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)

<Warning>
  This is a legacy integration that uses internal sessions. For new deployments, use [OIDC PKCE](#oidc-pkce-recommended) with Okta instead.
</Warning>

### 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

```shell theme={null}
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](https://developer.okta.com/docs/reference/api/oidc/#composing-your-base-url) 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`.

```shell theme={null}
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:

```shell theme={null}
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:

```shell theme={null}
SSO_OAUTH2_SCOPES=openid email profile groups
SSO_OAUTH2_GROUPS_MAPPING=Admins->admin,Developers->author,Users->member
```

**Keycloak** uses nested claims:

```shell theme={null}
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:

```shell theme={null}
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

| 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` |

<Tip>
  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.
</Tip>

## 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