Skip to main content

How to Authenticate a Service Account

What is a Service Account?​

Software components interacting with Mosaic Services use Service Accounts. A Service Account is similar to a User Account, but to authenticate it you will use an ID and a Secret (both are long random numbers) against Mosaic Identity Service and not any Identity Provider. Service Accounts can be assigned permissions (same permissions as regular users get). However, it is not possible to assign a Role to a Service Account.

It is recommended to create a separate Service Account for every integration purpose and grant them only those permissions that they really need (least privilege principle).

See also:

How to create a Service Account?​

You use the Mosaic Admin Portal to create and manage Service Accounts.

  1. Go to your Environment and select "Service Accounts"

  2. Click "New" to add a new Service Account

  3. Give a name to your Service Account and proceed

    1. Client ID & a randomly generated Client Secret will visible on the screen upon creation, and allow the possibility to copy it to the clipboard.

      New Service Account in the Mosaic Admin Portal

      New Service Account

      Caution

      Store the secret securely, as you will never see it in the Admin Portal again (only its hash is stored, hence it is impossible to recover it). You can reset the secret anytime to a new value.

  4. Grant permissions to the Service account by clicking "Permissions"

    Service Account Properties in the Mosaic Admin Portal

    Service Account Properties

tip

Use the Client Secret action to re-generate the Service Account secret if needed.

How to Authenticate a Service Account ...​

Mosaic Identity Service provides a GraphQL API endpoint to authenticate Service Accounts. You have to provide the Client ID and Client Secret, and you will get in exchange a JWT, that you can use to access any Mosaic services.

The lifetime of this JWT is by default 1 hour, but you can configure it per Environment in the Mosaic Admin Portal under Service Configuration > Identity Service. The setting applies to all Service Accounts of the given Environment.

... using GUI?​

If you just need a JWT for test purpose, you can generate it in the Mosaic Admin Portal on the page Service Account Properties by clicking "Generate Access Token".

Generate Service Account Access Token in the Mosaic Admin Portal

Generate Service Account Access Token

... using API?​

Send the following GraphQL mutation to https://id.service.eu.axinom.net/graphql

mutation GetServiceAccountToken {
  authenticateServiceAccount(
    input: {
      clientId: "YOUR_CLIENT_ID"
      clientSecret: "YOUR_CLIENT_SECRET"
    }
  ) {
    accessToken
    expiresInSeconds
    tokenType
  }
}

... using Mosaic Libraries?​

If you develop your own service using TypeScript, you can use a wrapper for the above call implemented in the library @axinom/mosaic-id-link-be:

    import { getServiceAccountToken } from '@axinom/mosaic-id-link-be'

Call the method getServiceAccountToken providing

The Response will be an object of TokenResult containing the following properties:

  • accessToken
  • expiresInSeconds
  • tokenType