Azure

Requirements

• Azure account
• API_URL 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

   Login with your account at https://portal.azure.com/

   • Go to Microsoft Entra ID > App Registration.
   • Pick a name, and select the Supported account types as you see fit
   • Register the application with {API_URL}/api/callback as the redirect URI.

   We recommend using the option single tenant option for Supported account types. This will allow selecting exactly what groups to propagate to this application. This option is also required to propagate cloud-only groups as names (see more details below).

   Ensure default delegated permissions: User.Read for sign in and read user profiles and email to view user’s email address.

   These attributes are typically created by default. If errors occur, ensure these options are set correctly.

2. Create the Client Credentials

   • Go to App Registration > {AppName}
   • In the overview page, copy the Application (client) ID value. This is the Client ID.
   • Go to Certificate & Secrets > Client Secrets > New Client Secret
   • Copy the Secret Value. This is the Client Secret

   A gateway on Kubernetes does not need a client secret. See Sign in without a client secret.

3. Collect Issuer and Custom Scopes Information

   The Issuer URL

   • Go to App registration > {AppName} > Overview
   • Copy the tenant ID and use as the value below
   • https://login.microsoftonline.com/{tenant_id}/v2.0

   The Custom Scopes

   • Use the Client ID to compose the Custom Scopes value
   • {CLIENT_ID}/.default

Sign in without a client secret

Available on version 1.260.0+

A gateway that runs on Kubernetes can authenticate to Entra ID with a federated credential in place of a client secret. Kubernetes gives the gateway a short-lived service account token, and Entra ID trusts it. There is no secret to expire or rotate.

1. Get the OIDC issuer of the cluster

   On AKS, turn on the OIDC issuer and copy its URL:

   az aks update -g <resource-group> -n <cluster> --enable-oidc-issuer
   az aks show -g <resource-group> -n <cluster> --query oidcIssuerProfile.issuerUrl -o tsv
   

   Other clusters need a public OIDC issuer. See Azure Workload Identity: self-managed clusters.

2. Add a federated credential to the application

   Go to App Registration > {AppName} > Certificates & secrets > Federated credentials > Add credential, select Kubernetes accessing Azure resources, and set:

   • Cluster issuer URL: the URL from the previous step, exactly as printed, with the final /.
   • Namespace: the namespace of the gateway.
   • Service account: hoopgateway for the gateway chart. For the control plane chart, its service account: <release>-hoopcontrolplane by default.
   • Audience: api://AzureADTokenExchange.

   Or with the Azure CLI:

   az ad app federated-credential create --id <client-id> --parameters '{
     "name": "hoop-gateway",
     "issuer": "<cluster issuer URL>",
     "subject": "system:serviceaccount:<namespace>:hoopgateway",
     "audiences": ["api://AzureADTokenExchange"]
   }'
   
3. Mount the token in the gateway

   Set these helm values:

   idpFederatedToken:
     enabled: true
   serviceAccount:
     create: true
   

   The chart mounts the token at /var/run/secrets/hoop/idp/token. Kubernetes renews it, and the gateway reads it again on each request to Entra ID, so no restart is needed.

4. Configure the provider

   In the Web App, go to Integrations > Authentication. In the OIDC form, select Federated token under Client Authentication and keep the path /var/run/secrets/hoop/idp/token. The gateway accepts only the path in IDP_CLIENT_ASSERTION_FILE, which idpFederatedToken.enabled sets. Fill the Client ID, the Issuer URL and the Custom Scopes as in the steps above.

   With the deprecated IDP_* variables, set them without IDP_CLIENT_SECRET. idpFederatedToken.enabled sets IDP_CLIENT_ASSERTION_FILE for you.

   config:
     IDP_ISSUER: 'https://login.microsoftonline.com/<tenant-id>/v2.0'
     IDP_CLIENT_ID: '<client-id>'
     IDP_CUSTOM_SCOPES: '<client-id>/.default'
   

   The gateway refuses a client secret and a token file together.

Error in the gateway logs	What to check
AADSTS700213 or AADSTS700211: No matching federated identity record	The issuer, subject or audience of the token does not match the federated credential. The issuer must match exactly.
AADSTS7000218: the request body must contain client_assertion or client_secret	The gateway has no token. Check idpFederatedToken.enabled and the token file path.
client assertion file ... is empty or failed reading client assertion file	The path does not point to the mounted token.

Configuring Groups Claims

The integration relies on groups propagated in the id_token. By default, Azure Entra ID propagates them in the groups claims.

The gateway needs to be configured to match the claim name of the groups. This configuration will ensure to sync the groups when a user authenticates on Hoop.

It’s possible to inspect the name of the claim that’s being propagated by viewing the logs of the gateway when a user sign in.

By default the gateway uses the claim name groups. To change it, go to Integrations > Authentication and include a distinct group.

By default, groups are propagate with their object ids. It may be cumbersome to manage groups as UUIDs on Hoop. See the section below to propagate them with their display name instead.

When you configure groups to sync, you’ll lose the admin access on the next sign in. To prevent this issue, set the configuration ADMIN_USERNAME on your gateway to change the role of the admin user with a group associated with your application. The name of the admin group depends on whether you propagate the groups as object IDs or as group names (see below).

Propagating Groups as Names

It’s possible to propagate groups with their display names for cloud groups.

• Click on Manifest
• Edit the item groups under optionalClaims.idToken and optionalClaims.accessToken attributes and add the name cloud_displayname
• Make sure that groupMembershipClaims is set to ApplicationGroup

(...)
  "groupMembershipClaims": "ApplicationGroup",
  (...)
  "optionalClaims": {
    "idToken": [
      {
        "name": "groups",
        "source": null,
        "essential": false,
        "additionalProperties": [
          "cloud_displayname"
        ]
      }
    ],
    "accessToken": [
      {
        "name": "groups",
        "source": null,
        "essential": false,
        "additionalProperties": [
          "cloud_displayname"
        ]
      }
    ],
    (...)

• Click on Save

This option only works when group groupMembershipClaims is set to ApplicationGroup. and after assigning the groups to this application.

Be aware that names are not unique and this may cause conflict when propagating groups. Object IDs are a more safer approach to avoid such problems.

For other kind of groups it’s possible to append additional properties as sam_account_name, dns_domain_and_sam_account_name or netbios_domain_and_sam_account_name.

Assign Groups to Application

• Go to Enterprise Application > {AppName} > User and Groups > Add user/group
• Select the desired groups and click on Select
• Click on Assign

This option requires an AD subscription that allows assigning groups to application.

References:

• Configure Optional Claims
• Configure group claims for applications

Machine to Machine Access (M2M)

Available on version 1.17.14+

It is possible to access hoop by issuing access tokens using the Oauth2 Client Credentials Flow. The gateway validates and authenticates any access token generated by the app registered in Azure, provided that a service account is active on hoop. The only requirement is that the service account has the same Object ID as the application, which serves as its main identifier.

Authentication only occurs when a token is issued by the identity provider. The service account resource simply maps the subject to identify who is accessing the API.

Creating a Service Account

hoop admin create serviceaccount <azure-app-object-id> \
  --name "My Service Account" \
  --groups admin

To obtain the Object ID of the application navigate to: Azure Portal > Microsoft Entra ID > Enterprise Applications

Creating an Access Token

1. Go to App Registrations > Certificate & Secrets > New Client Secret

Copy the secret value and use in the command below as the attribute for <APP_CLIENT_SECRET>

2. Generate an access token

curl -XPOST -H "Content-Type: application/x-www-form-urlencoded" \
	-d client_id=<APP_CLIENT_ID> \
	-d scope=<APP_CLIENT_ID>/.default \
	-d client_secret=<APP_CLIENT_SECRET> \
	-d grant_type=client_credentials \
	https://login.microsoftonline.com/<TENANT_ID>/oauth2/v2.0/token

• APP_CLIENT_ID: the client id of the application
• APP_CLIENT_SECRET: the client secret generated in the step 1
• TENANT_ID: the tenant id of you app instance

For more information, see this guide.

Access the API

export HOOP_TOKEN=eyJ0eXAiOiJKV1QiLCJhb...5Z3Be-kkXkAnAA-zIweYuqEUDA
hoop admin get userinfo

In case of receiving access denied (401), make sure that the subject of the access token matches the subject provided when creating the service account (usually matches the object id of the application)