> ## Documentation Index
> Fetch the complete documentation index at: https://hoopdev-docs-improve-idp-sso-pages.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-docs-improve-idp-sso-pages/quDT6RZSG6Ua5zfL/images/idp/okta-1.jpeg?fit=max&auto=format&n=quDT6RZSG6Ua5zfL&q=85&s=627076bcd2ad0d220638ffb22e362a02" 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-docs-improve-idp-sso-pages/quDT6RZSG6Ua5zfL/images/idp/okta-2.jpeg?fit=max&auto=format&n=quDT6RZSG6Ua5zfL&q=85&s=7e74b52674ab656634a83cb3aa0e5433" 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, append `?_userinfo=1` to the Issuer URL (e.g., `https://your-org.okta.com/oauth2/default?_userinfo=1`). This tells the gateway to authenticate using the userinfo endpoint instead of validating the token directly.
    </Info>
  </Step>
</Steps>

## Configure Hoop Gateway

<Tabs>
  <Tab title="Web App">
    Go to **Integrations** > **Authentication** and fill in:

    * **Auth Method**: OIDC
    * **Issuer URL**: your Okta authorization server URI
    * **Client ID**: the Client ID from above
    * **Client Secret**: the Client Secret from above
    * **Groups Claim**: `groups`
  </Tab>

  <Tab title="API">
    ```sh theme={null}
    curl -X PUT {API_URL}/api/serverconfig/auth \
      -H "Api-Key: {API_KEY}" \
      -H "Content-Type: application/json" \
      -d '{
        "auth_method": "oidc",
        "provider_name": "okta",
        "oidc_config": {
          "issuer_url": "https://{YOUR_OKTA_DOMAIN}/oauth2/default",
          "client_id": "{CLIENT_ID}",
          "client_secret": "{CLIENT_SECRET}",
          "groups_claim": "groups"
        },
        "webapp_users_management_status": "active"
      }'
    ```
  </Tab>
</Tabs>

## 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-docs-improve-idp-sso-pages/8zJSOfXzen5fPoBJ/images/configure/identity-providers/add-claim-groups-okta.png?fit=max&auto=format&n=8zJSOfXzen5fPoBJ&q=85&s=bce1d68a3656032ab394d3ee99bf5381" 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-docs-improve-idp-sso-pages/8zJSOfXzen5fPoBJ/images/configure/identity-providers/okta-token-preview-test.png?fit=max&auto=format&n=8zJSOfXzen5fPoBJ&q=85&s=3e9f8c2b06b5db357c4466602f4be014" 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="Verify Groups Claim in Hoop Gateway">
    Ensure the **Groups Claim** field in **Integrations** > **Authentication** is set to `groups` to match the claim name configured above. This is the default value and usually requires no change.
  </Step>
</Steps>