Developers
GitHubBook a DemoGet Started

Okta OIDC

Connect Okta SSO with GoRules BRMS.

1. Create a New Okta Application

  1. Log in to your Okta Admin dashboard.
  2. Navigate to Applications and click Create App Integration.
  3. Choose OIDC - OpenID Connect as the sign-in method and select Web Application as the application type.
  4. Fill in the application name (e.g., GoRules BRMS DEV).
  5. Grant type should be set to Authorization Code as it is the only type supported by GoRules.
  6. For the Sign-in redirect URI enter app_url/oauth/okta where app_url is URL where your self-hosted BRMS is hosted for example at https://gorules-dev.your-company.com and the final URI would be https://gorules-dev.your-company.com/oauth/okta.
  7. Leave Sign-out redirect URIs and Trusted origin empty.
  8. Assign the application to the necessary Okta user groups for testing and press Save.
  • In case Federation Broker Mode is presented, disable it.

📘

app_url is URL where your self-hosted BRMS is hosted for example https://gorules-dev.your-company.com

2. (Optional) Add Group Claims

  1. In the application dashboard open Sign On tab.
  2. In the section OpenID Connect ID Token click on Edit.
  3. For Group Claim Type select Filter.
  4. In the Group Claim Filter enter groups (if empty), from dropdown select Matches regex and enter .* in the last field.
  5. Press Save.

3. Copy variables and secrets

  1. In the application dashboard General tabs copy and save:
    1. Client ID
    2. Client Secret (by generating new secret or coping existing)

4. Configure GoRules BRMS Environment Variables

To configure Okta AD SSO you will need to add Environment Variables for the BRMS. Table below represents environment variable mapping.

BRMS Environment VariableOkta SSO Mapping
SSO_OAUTH2_PROVIDERokta
SSO_OAUTH2_CLIENT_IDCLIENT_ID from Step 3.1.1.
SSO_OAUTH2_CLIENT_SECRETCLIENT_SECRET from Step 3.1.2.
SSO_OAUTH2_SCOPESopenid email profile
SSO_OAUTH2_AUTH_URL{{baseUrl}}/v1/authorize
SSO_OAUTH2_TOKEN_URL{{baseUrl}}/v1/token
APP_URL_app_url_ for example https://gorules-dev.your-company.com
EMAIL_ENABLEDfalse

📘

Learn more on how to compose baseUrl by reading Okta documentation: https://developer.okta.com/docs/reference/api/oidc/#composing-your-base-url

📘

Upon setting configuration you will need to restart BRMS for changes to take effect.

6. Optional Environment Variables

To configure group mapping use SSO_OAUTH2_GROUPS_MAPPING variable and add groups into scopes.

BRMS Environment VariableOkta SSO Mapping
SSO_OAUTH2_GROUPS_MAPPINGgroup1->admin,group2->admin,group3->member
SSO_OAUTH2_SCOPESopenid email profile groups

Mapping is represented as {{okta_group_name}}->{{brms_role}} comma , separated with the next mapping.

There are 4 global roles: owner, admin, author, and member.

📘

Multiple groups can map to the same role.

📘

Group name is Okta group name. If variable is not set, permissions will be managed from inside BRMS.
If variable is set and existing user is not found in the mapping string, user will be added to the member group.