Okta Roles Integration

Introduction

This guide provides instructions for integrating groundcover with Okta to enable advanced user role management capabilities. It is designed for administrators seeking to leverage Okta as their Identity Provider (IdP) for centralized identity and access management within groundcover. The guide outlines the process for setting up the authorization (user roles) integration, facilitating streamlined access control and user management aligned with organizational roles and permissions.

This guide requires an existing Okta connection to app.groundcover.com using OIDC.

Integration

Before continuing, prevent potential lockout. Go to Settings -> Workspace and set the Default Policy to "groundcover Admin".

Step 1: Create custom groundcover policies:

In groundcover app navigate to Settings -> Policies and click Create Policy or edit an existing custom policy.

You can’t use the default groundcover policies here, but you can utilize your existing custom policies

Configure the required permissions level and data scope.

Use the automatically generated SSO Role Claim values later in Okta. You can also define your own values:

Step 2: Set application profile

In Okta go to Directory -> Profile Editor and select groundcover app.

Click Add Attribute to get the following pop-up:

Set:

• Data type: string array (This value must not be changed)

• Display name: e.g. groundocover Roles

• Variable name: userRoles (This value must not be changed)

Additional Options:

• Enum: Set this to pre-define list of possible roles

• Attribute required: Set to define this attribute as mandatory

• Scope: Set to User personal if you prefer to manage roles per user

• Group Priority:

  • Use Group Priority: Select this option to use the defined group priority to determine which individual attributes should be honored when a user belongs to more than one group.

  • Combine values across groups: Select this option to prioritize which individual attributes should be honored when a user belongs to more than one group.

Step 3: Pre-set the roles (when “Enum” is selected)

In the same menu, under the Attribute members section define the role mapping, e.g.:

• Display name: Use a descriptive name for internal reference.

• Value: Must exactly match the SSO Role Claim from the groundcover policy in Step 1

Important: Use the SSO Role Claim value from the groundcover policy. Do not use the policy name.

Step 4: Assign roles to members/groups:

Navigate to Directory -> Groups and select the relevant group to edit. Under applications, select groundcover application and click edit.You should get a screen like this:

In this menu, define the relevant groundcover roles for this group.

If you checked “Enum”, the screen should have checkboxes instead of free text so you can multi-select the relevant predefined roles

Step 5: Verify the integration is working

Sign out of the groundcover application. Then sign in with your email address. Do not use the Google or Microsoft sign-in buttons.

Navigate to Settings -> Users and ensure you see "SSO Driven" and assigned policy next to your name:

Step 6: Set the Default Policy

In Settings -> Workspace, set the Default Policy for users without an Okta group.

This setting only applies when the Teammates can automatically join toggle is enabled: