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, use: {API_URL}/api/callback. Change this later to the right domain.

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) Add ‘https://app.hoop.dev/groups’ claim to ID Token (optional)

Go to App registration > {AppName} > Token configuration

Click in the button Add groups claim

Select the group types that you see fit

Assign to the ID Token and Save

Rename the claim groups to https://app.hoop.dev/groups at:

Overview > ManagedApplication {AppName} > Single sign-on > Attributes & Claims > Edit
In Additional claims, click at the groups record and add the namespace: “https://app.hoop.dev”

3) Collect the required information

IDP_CLIENT_ID & IDP_CLIENT_SECRET

Go to App registration > {AppName}

Take note on the Application (client) ID. This is the IDP_CLIENT_ID
Click on “Client credentials” and create a new secret. This is IDP_CLIENT_SECRET

IDP_ISSUER & IDP_CUSTOM_SCOPES

IDP_CUSTOM_SCOPES

Fixed value: “{IDP_CLIENT_ID}/.default”

IDP_ISSUER:

Go to App registration > {AppName} > Overview > Endpoints

Open the “OpenID Connect metadata document” URL in the browser. It will look like https://login.microsoftonline.com/{tenant_id}/v2.0/.well-known/openid-configuration
In the JSON file in the browser, search for the key “issuer”. It will look like https://login.microsoftonline.com/{tenant_id}/v2.0

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)