Skip to main content

@axinom/mosaic-id-link-be

The mosaic-id-link-be package provides utilities for various tasks related to the Identity Service that are used by other backend services. Some of the utilities are specific to the developer workflow, while some are intended to be used directly in the application code.

Functions​

The following section describes the functions that are exported through this library and their usage.

devSetupServiceAccountWithPermissions​

This function can be used to set up a new Service Account in Mosaic with the desired permission structure. There is an optional parameter that can be used to validate the permission structure that is passed. It returns a ServiceAccountResult object.

If an existing Service Account name is provided, the function replaces it without raising any errors.

Caution

This function can only be used in a developmental workflow.

Usage​

The function signature is given below.

devSetupServiceAccountWithPermissions = async (
  authEndpoint: string,
  accessToken: string,
  serviceAccountName: string,
  permissions: PermissionStructure[],
  enforceValidPermissionStructure = true,
): Promise<ServiceAccountResult>

The table below describes the arguments in the function signature.

ParameterDescription
authEndpointThe Identity Service authentication endpoint (e.g., https://id.service.eu.axinom.net).
accessTokenA JWT with the permission DEV_SETUP_SERVICE_ACCOUNT_WITH_PERMISSIONS.
serviceAccountNameThe name of a Service Account to create.
permissionsAn array of PermissionStructure objects defining the permissions that must be granted for the service account.
enforceValidPermissionStructureA boolean to indicate whether the passed permissions should be validated. When set to true and there are any non-existent permissions (permissions that are not registered in the Identity Service), the method throws an error.

devDeleteServiceAccount​

This function deletes an existing Service Account by its Client ID.

Caution

This function can only be used in a developmental workflow.

Usage​

devDeleteServiceAccount = async (
  authEndpoint: string,
  accessToken: string,
  clientId: string,
): Promise<boolean>
ParameterDescription
authEndpointThe Identity Service authentication endpoint (e.g., https://id.service.eu.axinom.net).
accessTokenA JWT with the permission DEV_SETUP_SERVICE_ACCOUNT_WITH_PERMISSIONS.
clientIdThe Client ID of the Service Account to delete.

devGenerateUserAccessTokenWithPermissions​

This function may be used to acquire a user access token for a given user with the desired set of permissions. The function provides options to set the token expiration period and validate the passed permission set. A TokenResult is returned, which contains the newly generated JWT.

Caution

This function can only be used in a developmental workflow.

Usage​

The function signature is shown below.

const devGenerateUserAccessTokenWithPermissions = async (
  authEndpoint: string,
  accessToken: string,
  permissions: PermissionStructure[],
  email?: string,
  tokenExpirationInSeconds?: number,
  enforceValidPermissionStructure = true,
): Promise<TokenResult>

The table below describes the arguments in the devGenerateUserAccessTokenWithPermissions function.

ParameterDescription
authEndpointThe Identity Service authentication endpoint (e.g., https://id.service.eu.axinom.net).
accessTokenA JWT with the permission DEV_GENERATE_USER_ACCESS_TOKEN_WITH_PERMISSIONS.
permissionsAn array of PermissionStructure objects defining the permissions to embed in the user access token.
emailEmail address for which the user token is generated. If this is provided, it must be connected to an existing user. If unspecified, a pseudo-user with the following metadata is used to generate the token: name: DEV email: dev@domain.local id: 00000000-0000-0000-0000-000000000000
tokenExpirationInSecondsToken expiration time in seconds. If not given, defaults to 2,592,000 seconds (30 days).
enforceValidPermissionStructureA boolean to indicate whether the passed permissions should be validated. When set to true and there are any non-existent permissions, the method throws an error.

updateServiceAccount​

This function updates the name of an existing Service Account.

Usage​

updateServiceAccount = async (
  name: string,
  authEndpoint: string,
  accessToken: string,
  clientId: string,
): Promise<boolean>
ParameterDescription
nameThe new name for the Service Account.
authEndpointThe Identity Service authentication endpoint (e.g., https://id.service.eu.axinom.net).
accessTokenA valid JWT with permission to update service accounts.
clientIdThe Client ID of the Service Account to update.

synchronizePermissions​

The synchronizePermissions function is used by other services to synchronize their defined permissions with the Identity Service. It adds any new permissions that are currently missing from the Identity Service, and removes any permissions that are not present in the permissionDefinition argument. It returns a SynchronizePermissionsResult which contains a list of the added and removed permissions.

This must be done at the service start-up of every service. This is how the ID Service gets the knowledge of service-related permission sets, which are used subsequently for authorization purposes. This list of synchronized permissions is available in the Management System to be assigned for user roles and service accounts.

Usage​

The function signature of synchronizePermissions is shown below.

const synchronizePermissions = async (
  authEndpoint: string,
  serviceAccountToken: string,
  serviceId: string,
  permissionDefinition: PermissionDefinition,
): Promise<SynchronizePermissionsResult>

The table below describes the arguments of the synchronizePermissions function signature.

ParameterDescription
authEndpointThe Identity Service authentication endpoint (e.g., https://id.service.eu.axinom.net).
serviceAccountTokenA JWT token with the SYNCHRONIZE_PERMISSIONS permission.
serviceIdThe service id of the service sending permissions (can be set by the service itself, but must be unique among all services in a specific Mosaic environment).
permissionDefinitionA PermissionDefinition object describing the permissions and the operations they are mapped to. An example of PermissionDefinition object can be seen below.

This function is called at the service start-up, typically from the index.ts of the service.

The following shows an example on how to call this function (error handling is omitted for clarity):

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

const permissionDefinition = {
  permissions: [
    {
      key: "read",
      title: "Access to read-only operations"
    },
    {
      key: "contribute",
      title: "Create and modify objects"
    },
    {
      key: "admin",
      title: "Administrative operations",
      usageScope: "SERVICE"  // hidden from user role assignment UI
    }
  ]
}

// this Service Account must have a permission `SYNCHRONIZE_PERMISSIONS`
const token = await getServiceAccountToken(
  config.idServiceAuthEndpointUrl,
  config.serviceAccountClientId,
  config.serviceAccountClientSecret,
);

const result = await synchronizePermissions(
  config.idServiceAuthEndpointUrl,
  token.accessToken,
  config.serviceId,
  permissionDefinition,
);

// result.permissionsStored is a list of added permissions and result.permissionsRemoved is a list of removed ones.

purgePermissions​

The purgePermissions function removes all permissions for a given service from the Identity Service. This is the inverse of synchronizePermissions and is typically used during service decommissioning or cleanup.

It returns a PurgePermissionsResult containing the list of purged permissions.

Usage​

const purgePermissions = async (
  authEndpoint: string,
  serviceAccountToken: string,
  serviceId: string,
): Promise<PurgePermissionsResult>
ParameterDescription
authEndpointThe Identity Service authentication endpoint (e.g., https://id.service.eu.axinom.net).
serviceAccountTokenA JWT token with the SYNCHRONIZE_PERMISSIONS permission.
serviceIdThe service ID whose permissions should be purged. Service IDs prefixed with ax- cannot be purged and will result in an error.

getServiceAccountToken​

This function authenticates the specified Service Account and returns its token as a TokenResult structure.

Usage​

The signature of the function is shown below.

getServiceAccountToken = async (
  authEndpoint: string,
  clientId: string,
  clientSecret: string,
): Promise<TokenResult>

The table below describes the arguments in the function.

ParameterDescription
authEndpointThe Identity Service authentication endpoint (e.g., https://id.service.eu.axinom.net).
clientIdThe Client ID of the Service Account
clientSecretThe Client secret of the Service Account

generateLongLivedToken​

This function provides the means of extending a user account token's validity period. A Service Account token must be passed with the relevant permissions. There is no change in the permissions that are connected to the user token. Only the validity period is revised. This returns a TokenResult object.

Usage​

The function signature for generateLongLivedToken is shown below.

generateLongLivedToken = async (
  authEndpoint: string,
  serviceAccountToken: string,
  userAccessToken: string,
  validityDurationInSeconds?: number,
): Promise<TokenResult>

The table below describes the arguments in the function signature.

ParameterDescription
authEndpointThe Identity Service authentication endpoint (e.g., https://id.service.eu.axinom.net).
serviceAccountTokenA service account token with the GENERATE_LONG_LIVED_TOKEN permission
userAccessTokenThe user access token which must be revised with the new validity period
validityDurationInSecondsThe validity period of the new token in seconds. This is an optional parameter. If this is missing, the validity is set to 2,592,000 seconds (30 days).

getWellKnownEndpoints​

This function retrieves the well-known endpoints of the Identity Service. These endpoints are used internally by most functions in this library to resolve the correct GraphQL endpoint for each operation.

Usage​

getWellKnownEndpoints = async (
  authEndpoint: string,
): Promise<WellKnownEndpoints>
ParameterDescription
authEndpointThe Identity Service authentication endpoint (e.g., https://id.service.eu.axinom.net).

Interfaces​

This section describes the interfaces exported by mosaic-id-link-be. These interfaces are used to enforce the data structures required in the library.

Permission​

This interface represents a single permission entry within a PermissionDefinition.

interface Permission {
  key: string;
  title: string;
  usedByManagedServiceOnly?: boolean;
  usedForDevelopment?: boolean;
  usageScope?: 'ANY' | 'SERVICE';
  gqlOperations?: readonly string[];
}
PropertyDescription
keyA unique identifier for the permission within the service.
titleA human-readable label for the permission.
usedByManagedServiceOnlyWhen true, this permission is only applicable in managed service environments.
usedForDevelopmentWhen true, this permission is intended for development use only.
usageScopeControls where this permission appears in assignment flows. ANY (default) makes it available in all flows including the user role assignment UI. SERVICE indicates the permission is intended for service accounts and it is hidden from the user role assignment UI. This is a UI-level hint only and does not enforce server-side assignment restrictions.
gqlOperationsA list of GraphQL operation names that this permission authorizes.

PermissionDefinition​

This interface defines the full permission structure passed to synchronizePermissions.

interface PermissionDefinition {
  permissions: readonly Permission[];
  gqlOptions?: {
    anonymousGqlOperations?: string[];
    ignoredGqlOperations?: string[];
  };
}
PropertyDescription
permissionsThe list of Permission entries to synchronize with the Identity Service.
gqlOptions.anonymousGqlOperationsGraphQL operations listed here are ignored during authorization checks - they are treated as publicly accessible.
gqlOptions.ignoredGqlOperationsGraphQL operations listed here are excluded from "disabled operations" logging. Use this for operations that are intentionally not mapped to any permission.

ServiceAccountResult​

This interface represents the result after creating a new service account.

interface ServiceAccountResult {
  clientId: string;
  clientSecret: string;
}

PermissionStructure​

This interface represents a set of permissions to assign to a service account or user token, grouped by service. The strings in the permissions array correspond to the key field of the Permission interface as registered via synchronizePermissions.

interface PermissionStructure {
  serviceId: string;
  permissions: string[];
}

TokenResult​

This interface represents the result returned by token generation functions, such as getServiceAccountToken.

interface TokenResult {
  accessToken: string;
  expiresInSeconds: number;
  tokenType: string;
}

SynchronizePermissionsResult​

This interface represents the object that is returned after the synchronizePermissions function is executed. It contains a list of newly added and removed permissions.

interface SynchronizePermissionsResult {
  permissionsStored: string[];
  permissionsRemoved: string[];
}

PurgePermissionsResult​

This interface represents the object returned after the purgePermissions function is executed.

interface PurgePermissionsResult {
  permissionsPurged: string[];
}

WellKnownEndpoints​

This interface represents the well-known endpoints returned by the Identity Service, as used by getWellKnownEndpoints.

interface WellKnownEndpoints {
  jwksEndpoint: string;
  accessManagementGraphQlEndpoint: string;
  authGraphQlEndpoint: string;
  axinomAuthBaseUrl: string;
  axAuthManagementGraphQlEndpoint: string;
}

Was this page helpful?