Requirements

  • An account in OKTA
  • 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

1

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
2

Configure the Redirect URIs

  • Signin redirect URIs: {API_URL}/api/callback
  • Signout redirect URIs: {API_URL}/api/logout
3

Collect the Credentials

  • In the Application Home copy the Client ID and Client Secret
4

Collect Issuer Information

  • The Issuer URI depends on the authorization server being used. Refer to this documentation.

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.

5

Configure Groups Claims

  • Go to Security > API > {authorization server} > Claims
  • Add https://app.hoop.dev/groups in the ID Token

If the above instructions are not applicable to your Okta setup, configure it by adding a group claim to the organization’s authorization server. Refer to this documentation.

Known Issues

User groups are not synchronized no groups are assigned

When a user is not assigned to any group, Hoop will not synchronize the group information for that user. This issue occurs because Hoop only synchronizes users who have the groups claim. However, if a user does not belong to any group, this information is not propagated.

To prevent this issue, ensure that every user is associated with a default group. This will help avoid synchronization problems in your installation.