Make a Service Mosaic-Compatible

Table of Contents

Architecture
Design
Implementation
- Synchronize permission
- Verify JWT

Imagine, you have an existing service (backend), developed with any technology, and you want to make this service "Mosaic-compatible". What should you do?

Architecture

A minimal level of Mosaic-compatibility means: users can access your service using the same authentication and authorization scheme as the other Mosaic services. In particular it means:

Service has a name
Service defines a list of permissions
Mosaic Identity Service knows the service and the permissions defined by the service
Service API endpoints use JWT as its authentication technique and accept the JWT issued by Mosaic Identity Service (for users and service accounts)
Service authorizes requests based on the user permissions submitted as a part of JWT
Multiple deployments of a Service can exist, each bound to a specific Mosaic environment.

Design

Here are some design steps to take for your service. Additional implementation details are provided further down.

Define a name for your service. It can be any string, describing the purpose of the service, and unique among all services registered in the same environment.
Design your permissions structure and define a set of permissions. Mosaic services have a flexible permissions structure, you may decide on what permissions shall guard the endpoints/operations exposed by your service. But for a start, you can use even a single permission (e.g. admin) granting access to all functions or a short list of permissions, e.g., read, contribute, manage.
On service start you have to synchronize a list of permissions to Mosaic Identity Service. If your service is based on TypeScript/JavaScript, you can use a Mosaic library @axinom\mosaic-id-link-be. Otherwise, you can use an API of the Identity Service directly.
Once the Identity Service is aware of your service and its permissions, you can design user roles and assign your permissions to the roles. Once a user with such a role logs in, their JWT contains your service' permissions in its permissions list.
When you call your service, make your users first log in using Mosaic Identity Service. If your frontend is a Mosaic microfrontend and runs inside Mosaic Management System, it is already granted. You only have to forward JWT to your service when calling your API.
For integration scenarios, you can use Mosaic Service Accounts. Such an account can be assigned permissions directly (also, your service' permissions). Once you authenticate a service account, you can use its JWT to send requests to your service.
Your service endpoints shall accept JWT:
```
Authorization: Bearer <JWT-as-base64>
```
Before you process a request, you should verify the JWT. If your service is based on TypeScript/JavaScript, you can use a Mosaic library @axinom\mosaic-id-guard. Otherwise, you can implement such verification yourself easily, as JWT is an open standard and has extensive support in all technologies.
Once you decide to trust the JWT, extract the list of permissions from it and check, if it contains those permissions that you require. This is something that can be done at your service’s API operation level based on your choice of permissions that you decide necessary to authorize access to them. This is as simple as an array manipulation.

Implementation

Most of the tasks described above are pretty straight-forward.

Synchronizing permissions and verifying JWT require more attention.

Synchronize permission

We recommend using Mosaic library @axinom\mosaic-id-link-be.

What you have to do on application start:

Pre-requisite: Create a service account with a synchronizePermissions permission (see Service Accounts for additional instructions).
Authenticate this service account using getServiceAccountToken method.
Prepare a list of your permissions as a PermissionStructure
Call synchronizePermissions method.

If you can’t use the library, the procedure is the same, just call a respective API endpoint in the Identity Service instead.

Verify JWT

We recommend using Mosaic library @axinom\mosaic-id-guard.

What you have to do to process every request:

Extract the JWT from the request
Verify the token using getAuthenticatedManagementSubject method (you always do this in a context of a specific Mosaic environment).
Compare the list of returned permissions from JWT against the permissions you require.

If you can’t use the library, the idea remains the same, but you have to implement the steps on your own or use the libraries available in your technology.

The following shall be validated:

JWT signature is valid
Token is not expired
Token is for the same Tenant and Environment as configured in the service.

Certificate for signing JWT is environment-specific and can be acquired at: https://id.service.eu.axinom.net/$tenantId/$environmentId/.well-known/jwks.json. The certificate has a long but still limited validity and shall be periodically refreshed. We encourage you to cache the certificate and not request it on each request to your service.

Note	Axinom Portal JWT-tool can be used to check the content of the token.

Example of a Mosaic JWT:

{
  "tenantId": "13d99de7-b726-45f8-a03d-7935e116b111",
  "environmentId": "22202f00-19e2-462b-885a-da5948eb50cb",
  "name": "myUserName",
  "permissions": {
    "myService": [
      "read",
      "contribute"
    ]
  },
  "subjectType": "ServiceAccount",
  "iat": 1671462868,
  "exp": 1671466468,
  "aud": "*",
  "iss": "ax-id-service",
  "sub": "69cb7e46-69d4-4323-a935-404444100d48"
}