@axinom/mosaic-id-link-be

Table of Contents

Interfaces
Functions

The mosaic-id-link-be package provides a utility for various tasks related to the ID and Admin service that are used by other back-end services. Some of the utilities are specific to the developer workflow, while some are intended to be used directly in the code.

Interfaces

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

ServiceAccountResult

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

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

PermissionStructure

This interface represents the permission structure in a well-known format to be read by the Identity Service.

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

TokenResult

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

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 {
  added: Maybe<string>[] | null;
  removed: Maybe<string>[] | null;
}

Functions

The following section describes the functions that are exported through this library as well as their usages.

devServiceAccountSetupWithPermissions

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.

Usage

The function signature is given below.

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

The table below describes the arguments in the function signature.

Parameter Description

Parameter	Description
`authEndpoint`	The Identity Service authentication endpoint.
`accessToken`	A JWT with the permission `DevServiceAccountSetupWithPermissions`.
`serviceAccountName`	The name of the newly created Service Account.
`permissions`	A `PermissionStructure` object defining the permissions that must be granted for the service account.
`enforceValidPermissionStructure`	A 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.

authEndpoint

The Identity Service authentication endpoint.

accessToken

A JWT with the permission DevServiceAccountSetupWithPermissions.

serviceAccountName

The name of the newly created Service Account.

permissions

A PermissionStructure object defining the permissions that must be granted for the service account.

enforceValidPermissionStructure

A 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.

If an existing service account name is given, the function replaces it without raising any errors.

devAccessTokenGeneratedWithPermissions

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.

Usage

The function signature is shown below.

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

The table below describes the arguments in the devAccessTokenGeneratedWithPermissions function.

Argument Description

Argument	Description
`authEndpoint`	The Identity Service authentication endpoint.
`accessToken`	A JWT with the permission `DevAccessTokenGeneratedWithPermissions`.
`permissions`	A `PermissionStructure` object defining the permissions that must be granted for the service account.
`email`	Email address for which the user token is generated for. 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. email: `dev@domain.local` id: `00000000-0000-0000-0000-000000000000`

authEndpoint

The Identity Service authentication endpoint.

accessToken

A JWT with the permission DevAccessTokenGeneratedWithPermissions.

permissions

A PermissionStructure object defining the permissions that must be granted for the service account.

email

Email address for which the user token is generated for. 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.

email: dev@domain.local id: 00000000-0000-0000-0000-000000000000

synchronizePermissions

The synchronizePermissions function is used by other services to synchronize 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. The same list of synchronized permissions is available in the management portal 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.

Argument Description

Argument	Description
`authEndpint`	The Identity Service authentication endpoint.
`serviceAccountToken`	A JWT token with the `SynchronizePermissions` permission.
`serviceId`	The service id for which the permissions are synchronized for.
`permissionDefinition`	An `PermissionDefinition` object describing the permissions and the operations they are mapped to. An example of `PermissionDefinition` object can be seen in below.

authEndpint

The Identity Service authentication endpoint.

serviceAccountToken

A JWT token with the SynchronizePermissions permission.

serviceId

The service id for which the permissions are synchronized for.

permissionDefinition

An PermissionDefinition object describing the permissions and the operations they are mapped to. An example of PermissionDefinition object can be seen in 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.

In security/sendPermissions.ts:

import { synchronizePermissions, getServiceAccountToken } from '@axinom/mosaic-id-link-be';
import { Config } from '../common';
import { Logger } from '@axinom/mosaic-service-common';
import { permissionDefinition } from '../permission-definition';

export const sendPermissions = async (
  config: Config,
  logger: Logger,
): Promise<void> => {
  const token = await getServiceAccountToken(
    config.idServiceAuthEndpointUrl,
    config.serviceAccountClientId,
    config.serviceAccountClientSecret,
  );

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

  logger.debug({
    ...result,
    message: 'Permissions successfully synchronized.',
  });
};

In index.ts:

await sendPermissions(config, logger),

getServiceAccountToken

This function returns a TokenResult for a given clientId and clientSecret of a service account.

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.

Argument Description

Argument	Description
`authEndpint`	The Identity Service authentication endpoint.
`clientId`	The Client ID of the Service Account.
`clientSecret`	The Client secret of the Service Account.

authEndpint

The Identity Service authentication endpoint.

clientId

The Client ID of the Service Account.

clientSecret

The 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.

Argument Description

Argument	Description
`authEndpoint`	The Identity Service authentication endpoint.
`serviceAccountToken`	A service account token with the `GenerateLongLivedToken` permission.
`userAccessToken`	The user access token which must be revised with the new validity period.
`validityDurationInSeconds`	The validity period of the new token in seconds. This is an optional parameter. If this is missing, the validity is set to 2,700,000 seconds (30 days).

authEndpoint

The Identity Service authentication endpoint.

serviceAccountToken

A service account token with the GenerateLongLivedToken permission.

userAccessToken

The user access token which must be revised with the new validity period.

validityDurationInSeconds

The validity period of the new token in seconds. This is an optional parameter. If this is missing, the validity is set to 2,700,000 seconds (30 days).