Pre-requisites

Not all identity providers support the OAuth 2.0 Client Credentials Grant flow. Before implementing this guide, consult your identity provider’s documentation to verify compatibility.

Setup

1

Obtain an Access Token

Usually to obtain an access token you must know the Oauth2 Authorization Server URL. This configuration may differ depending on your identity provider.

The example below shows how to obtain an access token from the Azure Microsoft Entra ID Identity Provider

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

A success response generates the following payload:

{
    "token_type": "Bearer",
    "expires_in": 3599,
    "access_token": "eyJ0eXAiOiJKV1QiLCJhbGciOiJSUzI1Ni..."
}

The access_token attribute value is used to communicate with the Hoop Gateway API.

In order to obtain always a valid access token programatically you must automate the issuing of this process in your automation workflow.

2

Create the Service Account

This step creates the service account resource by establishing an association with the sub claim that is returned when the access token is issued.

This information typically corresponds to the client_id attribute in your OAuth 2.0 credentials. For detailed instructions specific to your identity provider, refer to our getting started section documentation.

If you’re having trouble locating this information, consult your identity provider’s configuration guide.

It creates an administrator user with access to all resources in the API.

hoop admin create serviceaccount <access-token-identifier> \
    --groups admin \
    --name 'Admin Api User Programmatic Access'
3

Use the Access Token

Configure your client application to use this token to access the Hoop API. An example using curl (http client) would be:

curl --verbose -H "Authorization: Bearer $HOOP_TOKEN" \
    https://hoop-gateway-url/api/userinfo

It should respond with HTTP status code 200 and return a JSON payload with the user information.

Revoking Access

The command below disable the service account by invalidating any request being sent to the gateway.

hoop admin create serviceaccount api-user \
    --groups admin \
    --name 'Admin Api User Programmatic Access' \
    --disable

It’s important to note that the access token has an expiration time as well. The Hoop Gateway API provides additional mechanisms to deny access for this service account through its association with the subject identifier in the token.