> For the complete documentation index, see [llms.txt](https://docs.groundcover.com/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://docs.groundcover.com/architecture/security-considerations/okta-sso-onboarding/okta-roles-integration.md).

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

{% hint style="info" %}
This guide requires an existing Okta connection to [app.groundcover.com](http://app.groundcover.com) using **OIDC**.
{% endhint %}

## Integration

{% hint style="danger" %}
Before continuing, prevent potential lockout. Go to Settings -> Workspace and set the Default Policy to "groundcover Admin".
{% endhint %}

#### Step 1: Create custom groundcover policies:

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

<div data-with-frame="true"><figure><img src="/files/dfCAzWQcjHkqkIWSva3D" alt="" width="375"><figcaption></figcaption></figure></div>

{% hint style="warning" %}
You can’t use the default groundcover policies here, but you can utilize your existing custom policies
{% endhint %}

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:

<div data-with-frame="true"><figure><img src="/files/cAgBILnajy9LpZnyLCzI" alt="" width="375"><figcaption></figcaption></figure></div>

#### Step 2: Set application profile

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

<div data-with-frame="true"><figure><img src="/files/20WMsZMNNX1u50NSD9YV" alt="" width="563"><figcaption></figcaption></figure></div>

Click **Add Attribute** to get the following pop-up:

<div data-with-frame="true"><figure><img src="/files/fu4ZRb1uxUyNATG3aV4y" alt="" width="563"><figcaption></figcaption></figure></div>

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

<div data-with-frame="true"><figure><img src="/files/3UByDYfOIC1yRZP00CMC" alt="" width="563"><figcaption></figcaption></figure></div>

* **Display name**: Use a descriptive name for internal reference.
* **Value**: Must exactly match the **SSO Role Claim** from the groundcover policy in Step 1

{% hint style="danger" %}
**Important:** Use the **SSO Role Claim** value from the groundcover policy. Do not use the policy name.
{% endhint %}

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

<div data-with-frame="true"><figure><img src="/files/EOCHOxEVylgfcY9spb0K" alt="" width="563"><figcaption></figcaption></figure></div>

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

{% hint style="info" icon="lightbulb-on" %}
If you checked “Enum”, the screen should have checkboxes instead of free text so you can multi-select the relevant predefined roles
{% endhint %}

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

<div data-with-frame="true"><figure><img src="/files/DS9YOyP16Glb2eDqkEIn" alt="" width="242"><figcaption></figcaption></figure></div>

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

<div data-with-frame="true"><figure><img src="/files/Hq9rX0wVjYWSQZ1bWWK3" alt="" width="375"><figcaption></figcaption></figure></div>


---

# Agent Instructions
This documentation is published with GitBook. GitBook is the documentation platform designed so that both humans and AI agents can read, navigate, and reason over technical content effectively. Learn more at gitbook.com.

## Querying This Documentation
If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question.

Perform an HTTP GET request on the current page URL with the `ask` query parameter, and the optional `goal` query parameter:

```
GET https://docs.groundcover.com/architecture/security-considerations/okta-sso-onboarding/okta-roles-integration.md?ask=<question>&goal=<endgoal>
```

`ask` is the immediate question: it should be specific, self-contained, and written in natural language.
`goal` is optional and describes the broader end goal you are ultimately trying to accomplish on behalf of the user. GitBook uses it to tailor the answer towards what is most useful for that goal.

The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.