Requirements
- Azure account
API_URL
of the Hoop gateway instance
Identity Provider Configuration
1
Create an Application
Login with your account at https://portal.azure.com/Ensure default delegated permissions:
- 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).
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
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
- Use the Client ID to compose the Custom Scopes value
{CLIENT_ID}/.default
Configuring Groups Claims
The integration relies on groups propagated in theid_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.
1
Configure the Groups Claim on Hoop
Configure the groups claim environment variable in your gateway
IDP_GROUPS_CLAIM=groups
2
Configure the Groups Claim on Azure
In the Azure Portal
- Go to Microsoft Entra ID > App Registration >
{AppName}
> Token Configuration - Click on Add groups claim
- Client in edit on Attributes & Claims > Add groups claim
- Select Groups assigned to the application
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
- Click on Save
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.
Machine to Machine Access (M2M)
Available on version 1.17.14+
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
To obtain the Object ID of the application navigate to: Azure Portal > Microsoft Entra ID > Enterprise Applications
Creating an Access Token
- Go to App Registrations > Certificate & Secrets > New Client Secret
<APP_CLIENT_SECRET>
- Generate an access 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
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)