# Okta

Firstly, we need to obtain credentials such as

* `Client ID`
* `Client secret`

If you already have them, please skip to [#configuring-okta-as-external-oidc-in-defguard](#configuring-okta-as-external-oidc-in-defguard "mention")

## Obtaining basic credentials

1. First, navigate in your Okta dashboard to "Applications" and create a new app integration here:

<figure><img src="/files/FykeJhaC8aDlksi38BRb" alt=""><figcaption></figcaption></figure>

2. Next, select following options like so:

<figure><img src="/files/vU3Q8P6MlfqGbYxj97MB" alt=""><figcaption></figcaption></figure>

3. On the next page, configure the application. Make sure to set the correct Sign-in URIs, those will take the form of `<DEFGUARD_URL>/auth/callback` (dashboard login) and `<DEFGUARD_PUBLIC_URL>/openid/callback` (if you want to perform new user enrollment using Okta). Replace `<DEFGUARD_URL>` and `<DEFGUARD_PUBLIC_URL>` with the URLs of your Defguard dashboard and enrollment page (proxy) accordingly. If you access your Defguard dashboard at e.g., `https://defguard.example.net` your redirect URI will be `https://defguard.example.net/auth/callback`. If you want to use Okta as the MFA provider, also add `<DEFGUARD_PUBLIC_URL>/openid/mfa/callback` to the redirect URIs.

<figure><img src="/files/YRJIRq0VnS6wEoos64F7" alt=""><figcaption></figcaption></figure>

4. Next, select the assignment according to your needs, we will select the option that allows every directory member to login:

<figure><img src="/files/iULkQIYVjvm3XVZndoHP" alt=""><figcaption></figcaption></figure>

5. Now, copy your client ID and secret, as you will need to paste it in your Defguard's settings.

<figure><img src="/files/7BgEAk9sTHyvL9AZWmX9" alt=""><figcaption></figcaption></figure>

## Obtaining Directory Synchronization credentials

{% hint style="warning" %}
This feature is currently technically limited to 10000 members or groups. High user or group counts may still trigger your provider API limits even below this threshold. If you have many users (200+), we recommend you test this feature first before you decide to turn on automatic user deletion.
{% endhint %}

1. Go to the Okta admin dashboard and navigate to the Applications menu

   <figure><img src="/files/lrtbk9jN1SaXSeGM0neT" alt=""><figcaption></figcaption></figure>
2. Make a completely new app integration by clicking "Create App Integration". This app will be solely responsible for communicating with Okta API.
3. Select "API services"

   <figure><img src="/files/pKSye8OF61l9bCXZsexr" alt=""><figcaption></figcaption></figure>
4. Name your app integration, e.g. "Defguard directory sync"
5. Go to your newly created app integration settings and change the client authentication to "Public key / Private key"

   <figure><img src="/files/uiObxjyNx9yN95D72vMD" alt=""><figcaption></figcaption></figure>
6. Next, click "Add key" and generate a new key pair.
7. Copy the generated private key in the JSON format to your clipboard
8. Paste the copied key in the Defguard Okta directory sync settings in the "Directory Sync Private Key" field.
9. Go back to Okta again. Save your new Okta configuration along with the newly generated keys. Now, copy the app integration's client ID. Paste it in the "Directory Sync Client ID" field in Defguard Okta directory sync settings. Save your Defguard settings.
10. Return to Okta and under "General settings" turn off the "Require Demonstrating Proof of Possession (DPoP) header in token requests" option. Save your changes.

    <figure><img src="/files/sXcoZAPXIEjC1qUGCAmT" alt=""><figcaption></figcaption></figure>
11. Now, navigate to the Okta API scopes tab.

    <figure><img src="/files/2LcAzmlVRqynX7Fcflkv" alt=""><figcaption></figcaption></figure>
12. Grant the `okta.groups.read` and `okta.users.read` scopes.
13. Everything should be set now. Try testing your provider connection in Defguard directory synchronization settings.

## Configuring Okta as external OIDC in Defguard

1. Go to **Settings → External identity providers**

<figure><img src="/files/6b7ImsaJoEZtichzWvel" alt=""><figcaption></figcaption></figure>

2. Click "**Connect**" in row with **Okta**

<figure><img src="/files/ZB64BvrNUtUTB2ftyLqY" alt=""><figcaption></figcaption></figure>

3. Fill **Base URL**, **Client ID** and **Client secret** (Check [#obtaining-basic-credentials](#obtaining-basic-credentials "mention")). The base URL will be based on your Okta domain. To verify if your Base URL is correct, you can navigate to `<YOUR_OKTA_DOMAIN>/.well-known/openid-configuration`. The issuer field here should be the same as the Base URL.

<figure><img src="/files/XT1oSRAu48EcZUGXOg9U" alt=""><figcaption></figcaption></figure>

4. Confirm credentials by clicking "**Continue**"
5. If you want to use "**Directory Synchronization**", enable it, and fill out fields\
   (Check [#obtaining-directory-synchronization-credentials](#obtaining-directory-synchronization-credentials "mention"))

{% hint style="info" %}
**Directory Sync Client ID:** The client ID of the Okta directory synchronization app

**Directory Sync Client Private Key:** The private key of the Okta directory synchronization app
{% endhint %}

<figure><img src="/files/yV9Nw2U0Lb5JtQML4v8r" alt=""><figcaption></figcaption></figure>

6. Proceed by clicking "**Continue"**

<figure><img src="/files/PTKh3VPUtY08mbFzT9xW" alt=""><figcaption></figcaption></figure>

If no errors occurred during configuration, you will see a message indicating that your OIDC provider has been successfully added.

7. Click "**Finish**".


---

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

```
GET https://docs.defguard.net/features/external-openid-providers/okta.md?ask=<question>
```

The question should be specific, self-contained, and written in natural language.
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.