> ## Documentation Index
> Fetch the complete documentation index at: https://hoopdev-feat-new-runbook-parameters.mintlify.site/llms.txt
> Use this file to discover all available pages before exploring further.

# Okta

## Requirements

* An [account in OKTA](https://developer.okta.com)
* `API_URL` is the public DNS name of the hoop gateway instance

Contact the administrator of the hoop gateway instance to retrieve the `API_URL` address.

## Identity Provider Configuration

<Steps titleSize="h3">
  <Step title="Create an Application">
    * Go to `Applications > Applications` and click on the Create App Integration button
    * In Sign-in Method, select OIDC - OpenID Connect
    * In Application type, select Web Application
  </Step>

  <Step title="Configure the Redirect URIs">
    * Signin redirect URIs: `{API_URL}/api/callback`
    * Signout redirect URIs: `{API_URL}/api/logout`

    <img src="https://mintcdn.com/hoopdev-feat-new-runbook-parameters/jEgq0bFD0hXYK9XM/images/idp/okta-1.jpeg?fit=max&auto=format&n=jEgq0bFD0hXYK9XM&q=85&s=cb19005522c6cda795efc7c0e61fc037" width="1600" height="1590" data-path="images/idp/okta-1.jpeg" />
  </Step>

  <Step title="Collect the Credentials">
    * In the Application Home copy the **Client ID** and **Client Secret**

    <img src="https://mintcdn.com/hoopdev-feat-new-runbook-parameters/jEgq0bFD0hXYK9XM/images/idp/okta-2.jpeg?fit=max&auto=format&n=jEgq0bFD0hXYK9XM&q=85&s=d3801d2c441765c8da3bfb0fd0d0e467" width="1600" height="1670" data-path="images/idp/okta-2.jpeg" />
  </Step>

  <Step title="Collect Issuer Information">
    * The Issuer URI depends on the authorization server being used. Refer to [this documentation](https://developer.okta.com/docs/concepts/auth-servers/#available-authorization-server-types).

    <Info>
      If Okta does not allow external applications to validate access tokens, add the query string option `_userinfo=1` when configuring the Gateway. It indicates to use the user info endpoint.
      The \_userinfo value is removed when used to exchange information with the identity provider.
    </Info>
  </Step>
</Steps>

## Configuring Groups

Explains how to configure groups claim to propagate when users sign in.

<Info>
  Refer to [Okta's Documentation](https://developer.okta.com/docs/guides/customize-tokens-groups-claim/main/#add-a-groups-claim-for-the-org-authorization-server) for more information.
</Info>

<Steps titleSize="h3">
  <Step title="Add Groups Claims">
    * Go to `Security > API > {authorization server} > Claims`
    * Click on `Add Claims` button

    Add the `groups` claim for the ID Token to any scope (image below)

    <Frame>
      <img src="https://mintcdn.com/hoopdev-feat-new-runbook-parameters/jEgq0bFD0hXYK9XM/images/configure/identity-providers/add-claim-groups-okta.png?fit=max&auto=format&n=jEgq0bFD0hXYK9XM&q=85&s=78fc617c4e4b0a9a04d7cb14024583a1" width="1412" height="1124" data-path="images/configure/identity-providers/add-claim-groups-okta.png" />
    </Frame>
  </Step>

  <Step title="Token Preview Test">
    This step validate if the configuration is returning the `groups` claim properly

    * Go to `Token Preview` tab
    * Select the Hoop Application
    * Select the Grant Type as `Authorization Code`
    * Select a user associated with this application
    * Add the scope `openid`

    The payload must appear with a claim named `groups` containing the groups associated with your application (image below)

    <Frame>
      <img src="https://mintcdn.com/hoopdev-feat-new-runbook-parameters/jEgq0bFD0hXYK9XM/images/configure/identity-providers/okta-token-preview-test.png?fit=max&auto=format&n=jEgq0bFD0hXYK9XM&q=85&s=35d8a2ea93b8cc3ab60bd815e60ccfa0" width="1850" height="1656" data-path="images/configure/identity-providers/okta-token-preview-test.png" />
    </Frame>

    <Warning>
      Please note that the `groups` claim **will not be present when a user has no group assignments**.
      Hoop synchronizes group information only when this attribute is configured.
      To prevent potential issues, ensure each user is assigned to at least one default group.
    </Warning>
  </Step>

  <Step title="Configure Hoop Gateway">
    The Hoop gateway requires proper configuration to correctly map claim names for synchronization.
    For detailed instructions, please consult the [OAuth2/OIDC Authentication Documentation](/setup/configuration/env-vars)
  </Step>
</Steps>