Authenticating as a Service Account

This guide shows you how to obtain an access token as a service account, in either credential mode, and use it to call the Platform Manager API.

Type

How-to guide

Goal

Obtain a token with the OAuth2 Client Credentials grant and call the Platform Manager API from a workload.

Audience

An engineer configuring automation (Terraform, a CI/CD pipeline, or a script) that holds a service account’s credential.

When to use

Use this guide after a tenant admin has created a service account for your workload.

A tenant admin creates the account first: see Managing Service Accounts for a client secret, or Federated Service Accounts for a federated identity.

Contents

The sections below cover each task in this guide:

Prerequisites

Before you start, gather the following.

Access and permissions

  • A service account created by a tenant admin.

  • For client-secret mode: its client id and the secret you were given at creation or rotation.

  • For federated mode: access to the identity provider (IdP) that issues the account’s assertion, and the account’s audience and resource from the federation options.

Tools and versions

  • curl, or any HTTP client, for the examples below.

Resources that must exist first

  • The realm name, which is your tenant short name.

  • The management and Keycloak domains for your installation.

Identify the endpoints

Use the endpoints below for your installation.

Service Endpoint Purpose

Platform Manager

https://<MGMT_DOMAIN>/api

The API you call to manage resources.

Keycloak token

https://<MGMT_KEYCLOAK_DOMAIN>/auth/realms/<REALM>/protocol/openid-connect/token

The authorisation server that issues the access token.
Values in angle brackets, such as <MGMT_DOMAIN>, are placeholders. Replace each with your own value before running a command.
On Axual Cloud (SaaS), the domains are fixed: the API is https://axual.cloud/api and the token endpoint is https://axual.cloud/auth/realms/<REALM>/protocol/openid-connect/token. <REALM> is still your tenant short name.

Obtain a token with a client secret

In client-secret mode, present the account’s client id and secret to the Client Credentials grant.

curl --request POST \
 --url https://<MGMT_KEYCLOAK_DOMAIN>/auth/realms/<REALM>/protocol/openid-connect/token \
 --header 'Content-Type: application/x-www-form-urlencoded' \
 --data grant_type=client_credentials \
 --data client_id=<CLIENT_ID> \
 --data client_secret=<CLIENT_SECRET>
If the host uses self-signed certificates or certificates from an untrusted authority, add --insecure.

You get back a 200 OK response with the access_token inside.

{
  "access_token": "eyJh...",
  "expires_in": 300,
  "token_type": "Bearer"
}

Obtain a token with a federated identity

In federated mode, present an assertion signed by the account’s identity provider instead of a secret. There is no client id and no secret in the request.

First, obtain the signed assertion from your identity provider for the resource shown in the account’s federation options. With Microsoft Entra, a workload requests a token for api://<AUDIENCE>, for example with a managed identity or MSAL. This step happens in your identity provider, not in Axual.

Then exchange the assertion for an Axual token.

curl --request POST \
 --url https://<MGMT_KEYCLOAK_DOMAIN>/auth/realms/<REALM>/protocol/openid-connect/token \
 --header 'Content-Type: application/x-www-form-urlencoded' \
 --data grant_type=client_credentials \
 --data client_assertion_type=urn:ietf:params:oauth:client-assertion-type:jwt-bearer \
 --data client_assertion=<IDP_SIGNED_ASSERTION>

The response is the same shape as in client-secret mode, and the token it returns is identical to a client-secret account’s. For the audience and resource values, see Service Account and Federation Reference.

Call the Platform Manager API

Send the token as a bearer token, with the realm header set to your tenant short name.

curl --request GET \
 --url 'https://<MGMT_DOMAIN>/api/user' \
 --header 'Authorization: Bearer <ACCESS_TOKEN>' \
 --header 'realm: <REALM>'

You get back a 200 OK response describing the service account.

{
  "firstName": "<NAME>",
  "lastName": "Service Account",
  "emailAddress": {
    "email": "<CLIENT_ID>@sa.axual.io"
  },
  "roles": [
    { "name": "APPLICATION_AUTHOR" }
  ],
  "uid": "xyz"
}

To confirm that the call worked, check that the response is 200 OK and its email matches the account’s client id. You can now call any endpoint the account’s roles and groups permit. For the full API, see the Platform Manager API documentation.