Configure internal accounts for services inside the yuuvis® Momentum cluster that will be authorized for cross-tenant requests.

Table of Contents

Introduction

Within your yuuvis® Momentum cluster, you might want to operate a service for asynchronous background processing that is working on all the data in your system independently of the tenant they belong to. Such services need to access the data of all tenants. In order to enhance their performance, they can use an internal service account (as of version 2021 Autumn) that allows for cross-tenant requests and thus avoid high numbers of requests to individual tenants. To configure internal service accounts, read this article carefully and make sure you do not skip any of the described configuration steps in order to ensure and secure the tenant separation.

General Remarks

The concept of service accounts is designed for the operation of background processes within the yuuvis® Momentum cluster.

The permissions for the service accounts are specified by the assignment of roles. We recommend to assign only roles that are available in all tenants.
The authentication with service accounts is accepted only within the yuuvis® Momentum cluster. External login attempts using service accounts are always rejected.
Note: To ensure this access blocking, service accounts need to be explicitly specified in the yuuvis® Momentum configuration.
Only selected endpoints of the API gateway can be called with service accounts.
In the identity provider, service accounts are associated with a tenant per definition. However, considering the permissions via their roles, they have access to resources of all tenants, e.g., objects including their binary content files and renditions.

Safety Note

The AUTHENTICATION service manages the cross-tenant requests of service accounts via a separate port. This port must be accessible only within the yuuvis® Momentum cluster to ensure strict separation of tenants for users. Never expose this internal port for public access!

Available Endpoints

Every endpoint matching one of the following wildcard patterns can be called via service accounts. For some of them, only particular HTTP request methods are enabled. If not specified (n/a), all HTTP request methods supported by the core API are available.

Pattern	Limited to HTTP Request Methods
`/api/dms/objects/tags*`	n/a
`/api/dms/objects/search*`	POST
`/api/dms/objects//tags//state/*`	n/a
`/api/dms/objects//tags`	GET
`/api/dms/objects//contents/file`	n/a
`/api/dms/objects//contents/renditions/text`	POST
As of 2022 Summer: `/api/dms/objects/*`	PATCH

Available Metadata Properties

A service account can operate on objects belonging to any tenant of the system. For each individual object, metadata properties can be accessed that are either system properties or defined in a schema that is available for the service account's tenant:

system properties
properties defined in the global schema
properties defined in the tenant schema for the service account's tenant
properties defined in an app schema that is available in all tenants
properties defined in an app schema that is available for the service account's tenant

Those properties can be managed as usual and used in search queries.

Properties defined in the tenant schema of a different tenant or in an app schema that is not available within the service account's tenant are not accessible. They cannot be retrieved, searched or modified.

Handling Cross-Tenant Requests

Each authorized request is enriched with an internal JSON Web Token (JWT) containing the service account's tenant, among other information. If the request calls an operation on an object of a different tenant, the corresponding object's system:tenant in the request body will have a different value. It is important to keep this difference in mind, especially for the definition of system hooks.

An operation on an object performed via a service account will trigger the creation of a new entry in the audit trail as usual. Since the executor was the service account, its account ID as defined in the identity provider will be referenced.
Note: If you are using yuuvis® client as reference implementation, the service account's ID will also appear in the object history view as soon as the corresponding object has been processed via the service account.

Roles of a Service Account

The permissions of a service account are defined via its roles. Assign as few roles as possible, i.e., only the roles that are required for proper operation of your background process. We recommend to assign only roles that are available in all tenants:

roles defined in the global role set or
roles defined in an app-specific role set for a system-wide available app.

With roles defined in a tenant-specific role set or in an app-specific role set that is not available for all tenants, the service account will consequently have the corresponding permissions only within the corresponding tenant(s).

Configuring Service Accounts

Create a user account and assign roles in your identity provider.

Choose the tenant for the service account. As described above, tenant-specific properties of this tenant will be available for the service account.
Assign roles to the account that allow for the specific operations your background process needs to perform in cross-tenant manner. Do not assign more roles than necessary for your specific purpose. Avoid tenant-specific roles.
Extract the ID of the account for the configuration in yuuvis® Momentum.

Specify the service account in the yuuvis® Momentum AUTHENTICATION Service configuration.

In the configuration file authentication-prod.yml, add a new entry to the authorization.serviceAccounts list with the syntax <tenant>\<account-id>.
Example with two service accounts:
```
authorization.serviceAccounts:
  - account: 'services-tenant\ddffd2d5-5dc5-494a-b706-2250cefee60a'
  - account: 'services-tenant\fbbe75cf-008e-4de2-bced-f71e402b4369'
```
Restart the AUTHENTICATION service.

Read on

Accessing External Services via AUTHENTICATION Service

Manage the access to an external service via the AUTHENTICATION service of yuuvis® Momentum. Keep reading

API

Organization and description of the yuuvis® Momentum ReST API endpoints is found here. Consider using our yuuvis® Postman Collections for convenient testing. Keep reading

Maintenance and Testing

Guidelines and information regarding maintenance and testing of a running yuuvis® Momentum core system. Keep reading

Browser not supported