> ## Documentation Index
> Fetch the complete documentation index at: https://mintlify.hoop.dev/docs/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/lXR_b8zeId-35Lup/images/idp/okta-1.jpeg?fit=max&auto=format&n=lXR_b8zeId-35Lup&q=85&s=e383696560da09be9b39251fef0496a6" 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/lXR_b8zeId-35Lup/images/idp/okta-2.jpeg?fit=max&auto=format&n=lXR_b8zeId-35Lup&q=85&s=d3a86f636b1d205d75acae1238f4922a" 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/xN9lO1ptlFiDB0Em/images/configure/identity-providers/add-claim-groups-okta.png?fit=max&auto=format&n=xN9lO1ptlFiDB0Em&q=85&s=c134cc87f507e310fee5665a1bc3140c" 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/xN9lO1ptlFiDB0Em/images/configure/identity-providers/okta-token-preview-test.png?fit=max&auto=format&n=xN9lO1ptlFiDB0Em&q=85&s=f0235593403e0dc9aaf05aa02628a5b6" 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>