Azure

This guide explains how to configure Azure with Hoop.

Requirements

An account in Azure

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 a new application

Go to Microsoft Entra ID > Add > App Registration.

Pick a name, and select the Supported account types as you see fit

In Redirect URI, select Web and add type the callback uri to {API_URL}/api/callback.

💡

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).

Make sure the application has the default delegated permissions of Microsoft Graph:

User.Read - Sign in and read user profiles

email - View user's email address

💡

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

2) Create 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) Obtain the Issuer URL and Custom Scopes

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

Custom Scopes

Use the Client ID to compose the Custom Scopes value

{CLIENT_ID}/.default

Groups Claim Configuration (Optional)

With Microsoft Entra ID it's possible to configure a claim to propagate as groups to Hoop. This configuration will ensure to sync the groups when a user authenticates on Hoop.

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

⚠️

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

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

json
  (...)
  "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 in 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

shell
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

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>

Generate an access token

shell
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

copy the access token returned in the json payload

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

shell
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)