> ## Documentation Index
> Fetch the complete documentation index at: https://hoopdev-fix-add-missing-mechanic-for-session-download-button.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-fix-add-missing-mechanic-for-session-download-button/CSN3Tfze1AaWBPxZ/images/idp/okta-1.jpeg?fit=max&auto=format&n=CSN3Tfze1AaWBPxZ&q=85&s=a2c73533a38b45dafe2bba88a8b83ddb" 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-fix-add-missing-mechanic-for-session-download-button/CSN3Tfze1AaWBPxZ/images/idp/okta-2.jpeg?fit=max&auto=format&n=CSN3Tfze1AaWBPxZ&q=85&s=fa945571d8aeba377ba0cab8605a7b73" 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-fix-add-missing-mechanic-for-session-download-button/JA0PdC0o4BPvOEZ9/images/configure/identity-providers/add-claim-groups-okta.png?fit=max&auto=format&n=JA0PdC0o4BPvOEZ9&q=85&s=3bb263a0db5a5613b833d2be5e26c817" 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-fix-add-missing-mechanic-for-session-download-button/JA0PdC0o4BPvOEZ9/images/configure/identity-providers/okta-token-preview-test.png?fit=max&auto=format&n=JA0PdC0o4BPvOEZ9&q=85&s=2b51781be045d03d8f4b55a21081b266" 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>