> For the complete documentation index, see [llms.txt](https://docs.docontrol.io/docontrol-user-guide/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://docs.docontrol.io/docontrol-user-guide/integrations/integrations-okta.md).

# Okta

Okta is an identity management service that allows organizations to manage and secure user authentication for their applications. With Okta, your IT department can manage an employee's access to any application or device.

## Use cases

Integrate Okta with DoControl to capture data about Okta groups and address these use cases:

* **Get inventory visibility** - Discover all assets that are exposed by a specific Okta group.
* **Monitor Okta user events -** View all user events in Okta, and leverage automated security workflows to mitigate exposure. For example, you can remove a terminated employee's personal email from all assets, or remediate sharing with an employee who belongs to a specific group.
* **View access events in Identities** - View all Okta access events for your identities.  
* **Discover SaaS identities** - Monitor your risky internal users to protect your organization from identity threats.

## Prerequisites

To integrate Okta with DoControl, make sure you have fulfilled these prerequisites: 

* You must be an Okta administrator.
* Before starting to integrate, you need to sign up with DoControl. \
  Follow the onboarding steps in [Create first account](/docontrol-user-guide/getting-started/quick-start/set-up-docontrol-basics.md#create-first-account).

{% hint style="warning" %}
If you're already integrated with Okta and you wish to leverage Okta event hooks to monitor events and remediate data exposure, you'll need to:

1. [Disconnect](/docontrol-user-guide/integrations/offboarding.md) DoControl from Okta. Your existing data won't be affected.
2. [Reintegrate](#integration-steps) with Okta by following the instructions below.
   {% endhint %}

## Okta fields for Identities

To view enriched data in Identities, DoControl retrieves data from these fields in Okta's Universal Directory:

* Email
* First name
* Last name
* Secondary email
* Title
* Department
* Hire date
* Start date
* Employment type
* Manager email
* Location
* Termination date (if relevant)

## Integration steps

To integrate Okta with DoControl, complete these steps in order:

1. [Get an API token](#get-an-api-token)
2. [Connect Okta with DoControl](#connect-okta-with-docontrol)
3. [Create an event hook endpoint](#create-an-event-hook-endpoint)

{% hint style="success" %}
To monitor Okta user events, or view access events in Identities, you need to [create event hooks](#create-an-event-hook-endpoint) in Okta.
{% endhint %}

### Get an API token 

{% hint style="info" %}
As a prerequisite to integrating Okta with DoControl, you first need to create an API token.
{% endhint %}

1. Log in to the Okta administration console dashboard:\
   `https://{your_domain}-admin.okta.com/admin/dashboard`
2. From **Security** > **API,** click **Create token**.<br>

   <div align="left"><figure><img src="https://3236294211-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2F-MesrnyDMZGYg1V-tOBo%2Fuploads%2FyrcvXK8QM6smgNSW8n9m%2FOkta%20create%20token.png?alt=media&amp;token=025d3bfb-c60f-4787-9182-16432c8d6b31" alt=""><figcaption></figcaption></figure></div>
3. Enter a token name, such as DoControl.
4. For the origin of the API calls, select the **Any IP** option.
5. Click **Create Token**. A token value appears.&#x20;
6. Copy the token value, and click **OK, got it**.

### Connect Okta with DoControl

1. From the DoControl side menu, click **Integrations**.
2. Under **Okta**, click **Connect**. <br>

   <figure><img src="https://3236294211-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2F-MesrnyDMZGYg1V-tOBo%2Fuploads%2FOrj2Wbbpm1hhpjCkWJeI%2FOkta%20wizard.png?alt=media&amp;token=4e6cc2e7-a27f-4df6-ab17-4e177cc724f5" alt=""><figcaption></figcaption></figure>
3. In **API token**, enter the token you received in [Get an API token](#get-an-api-token).
4. In **Okta login URL**, enter your Okta login URL, with the Okta domain: \
   `.okta.com`
5. Copy these values (for the next step to [create an event hook endpoint](#create-an-event-hook-endpoint)):&#x20;
   * Event hook endpoint URL
   * Authentication field&#x20;
   * Authentication secret&#x20;
6. Do **not** close the Okta integration wizard.

### Create an event hook endpoint

To monitor Okta user events, or view access events in Identities, you need to create event hooks in Okta. These Okta events can trigger automated security workflows to mitigate exposure, for example, by:

* [Removing a terminated employee's personal email from all Google assets](/docontrol-user-guide/risk-management/threat-model-coverage/personal-account-sharing/okta-playbooks-for-personal-account-sharing.md#remediate-terminated-employees-personal-email-access-to-google-drive)
* Remediating sharing with an employee who belongs to a specific group

{% hint style="success" %}
This procedure is **mandatory** if you wish to monitor Okta user events, or view access events in Identities.\
For more information about event hooks, see the [Okta User Guide](https://help.okta.com/en/prod/Content/Topics/automation-hooks/add-event-hooks.htm?cshid=ext-add-event-hooks).
{% endhint %}

1. Login to the Okta administration console event-hooks:\
   `https://{your_domain}-admin.okta.com/admin/workflow/eventhooks`

2. Go to **Workflow** > **Event Hooks** > **Add Event Hook**.

3. Enter **Name**.

4. Under **URL**, **Authentication field** and **Authentication secret**, paste the three values you copied in the [previous step](#connect-okta-with-docontrol).<br>

   <figure><img src="https://3236294211-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2F-MesrnyDMZGYg1V-tOBo%2Fuploads%2FdsSnVS0kgOu50Hjs1g6m%2FOkta%20webhooks.png?alt=media&amp;token=5dfee4e8-4bea-4066-9bde-48d796886385" alt=""><figcaption></figcaption></figure>

5. Under **Requests >** **Subscribe to events**, enter all required Okta events from the list below.
   * [Request to access an app was performed by a user](https://developer.okta.com/docs/reference/api/event-types/?q=app.access_request.request)
   * [Request to access an app was denied after at least one approver denied the request](https://developer.okta.com/docs/reference/api/event-types/?q=app.access_request.deny)
   * [Authentication of user via MFA](https://developer.okta.com/docs/reference/api/event-types/?q=user.authentication.auth_via_mfa) (mandatory for Identities)
   * [Auto-lock user account for Okta](https://developer.okta.com/docs/reference/api/event-types/?q=user.account.lock)
   * [User reported suspicious activity](https://developer.okta.com/docs/reference/api/event-types/?q=user.account.report_suspicious_activity_by_enduser)
   * [All of user's admin privilege revoked](https://developer.okta.com/docs/reference/api/event-types/?q=user.account.privilege.revoke)
   * [Create Okta group](https://developer.okta.com/docs/reference/api/event-types/?q=group.lifecycle.create)
   * [Delete Okta group](https://developer.okta.com/docs/reference/api/event-types/?q=group.lifecycle.deletegroup.lifecycle.create)
   * [User added to group](https://developer.okta.com/docs/reference/api/event-types/?q=group.user_membership.add)
   * [User removed from group](https://developer.okta.com/docs/reference/api/event-types/?q=group.user_membership.remove)
   * [User created](https://developer.okta.com/docs/reference/api/event-types/?q=user.lifecycle.create)
   * [User deleted](https://developer.okta.com/docs/reference/api/event-types/?q=user.lifecycle.delete.initiated)
   * [User activated](https://developer.okta.com/docs/reference/api/event-types/?q=user.lifecycle.activate)
   * [User deactivated ](https://developer.okta.com/docs/reference/api/event-types/?q=user.lifecycle.deactivate)
   * [User reactivated](https://developer.okta.com/docs/reference/api/event-types/?q=user.lifecycle.reactivate)
   * [User suspended](https://developer.okta.com/docs/reference/api/event-types/?q=user.lifecycle.suspend)
   * [User unsuspended](https://developer.okta.com/docs/reference/api/event-types/?q=user.lifecycle.unsuspend)\ <br>

6. In **DoControl**, return to the Okta integration wizard, and click **Connect**. Make sure you get a Success message that you're connected.

7. In **Okta**, in the **Add Event Hook Endpoint** page, click **Save & Continue**. \
   Okta events are now directed to DoControl.

## Troubleshooting

Q. What happens if my Okta token expires?

A. If the person who performed the integration leaves your organization, your Okta token will expire. You need to reconnect to DoControl by performing the [integration procedure](#integration-steps) again.


---

# 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 by asking a question.

Perform an HTTP GET request on the following URL with the `ask` and `goal` query parameters:

```
GET https://docs.docontrol.io/docontrol-user-guide/integrations/integrations-okta.md?ask=<question>&goal=<user_goal>
```

`ask` is the immediate question: it should be specific, self-contained, and written in natural language.
`goal` is what the user is ultimately trying to achieve, the reason they need the answer. Sharing it helps GitBook give you a better, more relevant answer. A goal is most helpful when it describes the outcome the user wants rather than restating the question. For example, with `ask=how do I create an API token`, a goal like `automate deployments from our CI pipeline` lets GitBook tailor the answer to that use case.

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.