This article describes what is a Carerix Marketplace, what problems does it solve and how a Carerix partner can integrate their solution to become a Marketplace Feature.

It is a system allowing Carerix customers to augment their setup by activating additional features from a supervised list. A feature might be a middleware service, a web portal, a browser extension or even a combination of those. Currently only customer’s administrators can do a feature activation.

The main purpose of the Marketplace is to standardise and automate the feature lifecycle management with regards to hundreds of customers Carerix has.

· Customer can easily enable more functionality from trusted vendors with just two clicks;

· Carerix has a unified approach to deliver additional features to the customers;

· Vendor can advertise and deliver their own solution to hundreds of Carerix customers by implementing a Marketplace integration.

Manifest is a definition of a component that can be installed into a tenant’s system. It describes what OAuth2Clients have to be created within a tenant, what settings a component has, who developed it and where to deliver feature lifecycle events.

A list of Manifests is supervised and maintained by Carerix.

Feature is an installation of a Manifest for a particular tenant with a certain status and (if defined by a Manifest) settings values. Tenant’s administrator can install a feature and then perform lifecycle actions on it: activate, update, deactivate and uninstall. Carerix Marketplace itself can perform other lifecycle actions: upgrade and cleanup.

Installation is a process of creating OAuth2Client(s) for a Feature within a tenant as well as provisioning all other resources necessary for it to work. If installation succeeds, a Feature moves to deactivated status. This step is where a vendor’s solution must provision all the resources necessary to accommodate a tenant, e.g.: database schema, cache entry, OAuth2Client credentials record etc.

Activation is a process of enabling a Feature for a tenant. Only Features with deactivated status might be activated. If activation succeeds, a Feature moves to activated status. If vendor’s solution is a middleware, it must perform actions with regards to a tenant (e.g. handle API requests, do any business logic) only if a Feature for such tenant is activated.

Deactivation is a process of disabling a Feature for a tenant. Only Features with activated status might be deactivated. If deactivation succeeds, a Feature moves to deactivated status. Consider activation/deactivation as a simple toggle which customer might enable if everything is ready to work or disable if he experiences any issues with a Feature.

Updating is a process of changing setting values for a Feature. Only Features with deactivated or activated statuses might be updated. If a Manifest doesn’t declare any setting, this process will never be called.

Uninstallation is a process of deleting Feature’s OAuth2Clients created within a tenant as well as deleting all tenant’s data related to a Feature from a vendor’s storage. Only Features with deactivated status might be uninstalled. If uninstallation succeeds, a Feature will be deleted, thus it will be possible to install it again.

Upgrading is a process of maintaining a Feature state according to its Manifest. This action is performed by Carerix Marketplace itself if:

· a Manifest of a Feature has a new version released;

· it has detected that an OAuth2Client for a Feature in IAM is broken and thus corresponding repairs were done.

Cleanup is a process of purging tenant’s data when tenant leaves Carerix.

Each component in the marketplace has its own manifest declaring OAuth2Clients to be created during installation, URLs where lifecycle events will be delivered to, settings such component has etc.

Vendors have to provide a manifest YAML file to Carerix for review, which in case of approval will be added to the Marketplace’s manifests registry, thus making a new entry in the installable features list.

Here’s an example of a manifest file:

Specifications for most relevant manifest properties are following:

This is a first step in a lifecycle: when tenant’s administrator decides to install a new feature from the Marketplace.

When “Install” button is clicked, Marketplace will create a new Feature record with installing status, create all OAuth2Clients described in the Manifest and then invoke a management endpoint provided by the vendor.

Given the example of Manifest provided in the previous section, the management endpoint request may look like this:

The request body contains:

1. An event type: "_kind": "FeatureCreateCommand" which indicates that tenant requested feature installation;

2. A URL where to send callbacks in case if vendor goes with the asynchronous implementation;

3. Actual feature installation payload:

1. Feature settings specified by tenant’s administrator during installation, if any;

2. OAuth2Client credentials, i.e. clientId and clientSecret pair, for all confidential clients specified within the manifest;

3. clientId for all public clients specified within the manifest;

1. If manifest contains no public clients, $.payload.publicClients property will be absent.

The marketplace expects that the management endpoint will respond with either 200 OK or 202 Accepted HTTP status code. A response with any other status code will abort installation. Response body is ignored by the Marketplace.

Information about tenant who requested the installation is included into an access token from the Authorization header: tenant claim contains a unique tenant identifier and iss claim contains a URL of OpenID Connect endpoint for a tenant.

iss claim of an access token actually is a prefix for IAM token endpoint - one used to obtain tokens by confidential clients, so it has to be kept along with tenant identifier and feature status. Since Carerix tenants are hosted at different identity servers, a vendor cannot just hardcode token endpoint.

To prevent unauthorized access to management endpoint, vendor has to check that provided access token satisfies these conditions:

· iss claim contains a valid tenant URL: matches https://id<identity-server>.carerix.io/auth/realms/<tenant> template;

· azp claim is equal to features.apps.carerix.io;

· Signature is valid;

· Is not expired.

An up-to-date list of valid Carerix identity server hosts is available here.

Now, the HTTP response code affects the way in which installation will finish.

Responding with 200 OK means that a request was processed synchronously by feature vendor and the Marketplace has just to complete the installation by changing the feature status to deactivated immediately.

If a vendor expects provisioning of tenant resources to take a long time (more than 10 seconds), then installation implementation must take the asynchronous approach.

Responding with 202 Accepted means that feature vendor needs some time to handle the request (e.g. provision a database schema, call some other APIs etc), thus installation is done in an asynchronous way. A vendor has to eventually call the Marketplace’s callback endpoint to deliver the result of installation in this case.

When everything is provisioned for a new feature on vendor’s side, a POST request has to be sent to the URL specified in callbackUrl property of the original installation request (e.g. https://api.carerix.io/features/v1/callback). Such request doesn’t need a request body, but has to:

1. Include an Authorization header with a Bearer <token> value, where a <token> is a JWT obtained for one of the confidential OAuth2Clients declared in a feature manifest, for a given tenant;

2. Include featureId query parameter being equal to id property of the original Manifest, e.g. partner from the example above;

3. Include type query parameter being equal to FeatureCreateCommand;

4. Include status query parameter being equal to SUCCESS, FAILED or IN_PROGRESS;

1. SUCCESS completes the installation, setting feature status to deactivated;

2. FAILED aborts the installation;

3. IN_PROGRESS currently has no effect.

Callback endpoint of the Marketplace will respond with 200 OK if request is valid.

Activation occurs when tenant’s administrator decides to enable an already installed feature for tenant’s users.

When “Activate” button is clicked, Marketplace will change a Feature status from deactivated to activating and then invoke a management endpoint provided by the vendor.

The management endpoint request is the same comparing to installation one, except for different _kind and an empty payload:

The request body contains:

1. An event type: "_kind": "FeatureActivateCommand" which indicates that tenant requested feature activation;

2. A URL where to send callbacks in case if vendor goes with the asynchronous implementation;

3. An empty feature activation payload.

The expected response is the same as for installation: either 200 OK or 202 Accepted HTTP status code. Despite this, Carerix encourages using a synchronous way of feature activation handling, i.e. responding with 200 OK.

To prevent unauthorized access to management endpoint, vendor has to check an access token. The rules are the same as with feature installation, please refer to corresponding article section.

Responding with 200 OK means that a request was processed synchronously by feature vendor and the Marketplace has just to complete the activation by changing the feature status to activated immediately.

Since a component has all resources to support a tenant provisioned at the installation step, there’s no need to do any long-running operations during activation. Therefore a vendor is strongly advised to go with synchronous approach.

Deactivation occurs when tenant’s administrator decides to disable an active feature for tenant’s users. This might happen if a feature has to be additionally configured before being used, if customer wants to uninstall a feature and so on.

When “Deactivate” button is clicked, Marketplace will change a Feature status from activated to deactivating and then invoke a management endpoint provided by the vendor.

The management endpoint request is the same comparing to the activation one, except for different _kind:

The request body contains:

1. An event type: "_kind": "FeatureDeactivateCommand" which indicates that tenant requested feature deactivation;

2. A URL where to send callbacks in case if vendor goes with the asynchronous implementation;

3. An empty feature deactivation payload.

The expected response is the same as for installation: either 200 OK or 202 Accepted HTTP status code. Despite this, Carerix encourages using a synchronous way of feature deactivation handling, i.e. responding with 200 OK.

To prevent unauthorized access to management endpoint, vendor has to check an access token. The rules are the same as with feature installation, please refer to corresponding article section.

Responding with 200 OK means that a request was processed synchronously by feature vendor and the Marketplace has just to complete the deactivation by changing the feature status to deactivated immediately.

Deactivation doesn’t imply deleting of tenant’s data. On the contrary, tenant might want to re-activate a feature again after the issue caused the deactivation is solved. So from vendor’s point of view, this has to be just a status change, after which a feature keeps the tenant’s data stored, but doesn’t process tenant’s requests.

Therefore a vendor is strongly advised to go with synchronous approach.

Updating occurs when tenant’s administrator decides to update feature’s settings. If there are no settings declared in a manifest, this lifecycle event will never happen.

When “Save” button is clicked, Marketplace will validate the supplied values, change a Feature status from activated or deactivated to updating and then invoke a management endpoint provided by the vendor.

Storing of feature setting values is responsibility of a vendor. Carerix Marketplace processes, but doesn’t store setting values.

Given the example of Manifest provided in the respective section, the management endpoint request may look like this:

The request body contains:

1. An event type: "_kind": "FeatureUpdateCommand" which indicates that tenant requested feature settings update;

2. A URL where to send callbacks in case if vendor goes with the asynchronous implementation;

3. Actual feature settings update payload:

1. Feature settings specified by tenant’s administrator, grouped by serviceId.

The expected response is 200 OK HTTP status code, then settings are considered to be updated.

At the moment asynchronous feature settings update is not available.

To prevent unauthorized access to management endpoint, vendor has to check an access token. The rules are the same as with feature installation, please refer to corresponding article section.

Responding with 200 OK means that a request was processed synchronously by feature vendor and the Marketplace has just to complete the update by changing the feature status back to activated or deactivated immediately.

It is possible for vendor to intentionally reject the settings update request, for example if a setting value does not pass some custom validation. In that case, vendor has to return a response with:

1. 4xx HTTP status;

2. Content-Type: application/problem+json HTTP header;

3. JSON response body like { "status": <status>, "detail": "<message>" }, where:

1. <status> is the same as in p.1;

2. <message> is a hint that will be shown to the tenant’s administrator.

As a result, instead of generic error message, tenant’s administrator will see the message from the vendor, like on screenshot below.

This is a last step in a lifecycle: when tenant’s administrator decides to uninstall a deactivated feature.

When “Uninstall” button is clicked, Marketplace will change a Feature status from deactivated to uninstalling, invoke a management endpoint provided by the vendor and then delete all OAuth2Clients created for a Feature.

The management endpoint request is the same comparing to activation and deactivation ones, except for different _kind:

The request body contains:

1. An event type: "_kind": "FeatureDeleteCommand" which indicates that tenant requested feature uninstallation;

2. A URL where to send callbacks in case if vendor goes with the asynchronous implementation;

3. An empty feature uninstallation payload.

The marketplace expects that the management endpoint will respond with either 200 OK or 202 Accepted HTTP status code. A response with any other status code will abort uninstallation. Response body is ignored by the Marketplace.

To prevent unauthorized access to management endpoint, vendor has to check an access token. The rules are the same as with feature installation, please refer to corresponding article section.

Again, the HTTP response code affects the way in which uninstallation will finish.

Responding with 200 OK means that a request was processed synchronously by feature vendor and the Marketplace has just to complete the uninstallation by deleting a Feature and its OAuth2Clients immediately.

If a vendor expects decommissioning of tenant resources to take a long time (more than 10 seconds), then uninstallation implementation must take the asynchronous approach.

Responding with 202 Accepted means that feature vendor needs some time to handle the request (e.g. drop a database schema, call some other APIs etc), thus uninstallation is done in an asynchronous way. A vendor has to eventually call the Marketplace’s callback endpoint to deliver the result of uninstallation in this case.

When resources provisioned for a feature on vendor’s side are deleted, a POST request has to be sent to the URL specified in callbackUrl property of the original uninstallation request (e.g. https://api.carerix.io/features/v1/callback). Such request doesn’t need a request body, but has to:

1. Include an Authorization header with a Bearer <token> value, where a <token> is a JWT obtained for one of the confidential OAuth2Clients declared in a feature manifest, for a given tenant;

2. Include featureId query parameter being equal to id property of the original Manifest, e.g. partner from the example given in Manifest section;

3. Include type query parameter being equal to FeatureDeleteCommand;

4. Include status query parameter being equal to SUCCESS, FAILED or IN_PROGRESS;

1. SUCCESS completes the uninstallation, deleting a feature and OAuth2 clients created for it;

2. FAILED aborts the uninstallation;

3. IN_PROGRESS currently has no effect.

Callback endpoint of the Marketplace will respond with 200 OK if request is valid.

If Carerix publishes a new version of a manifest provided by the vendor or if Marketplace itself notices an inconsistency in IAM setup, an upgrade operation will be executed for all tenants which have corresponding Feature in activated status.

When triggered, Marketplace will change a Feature status from activated to upgrading, create all missing OAuth2Clients and then invoke a management endpoint provided by the vendor.

The management endpoint request may look like this:

The request body contains:

1. An event type: "_kind": "FeatureUpgradeCommand" which indicates that feature upgrade was triggered;

2. A URL where to send callbacks in case if vendor goes with the asynchronous implementation;

3. Actual feature upgrade payload:

1. oldVersion containing manifest version the Feature had before upgrade was started;

2. newVersion containing manifest version the Feature was upgraded to;

1. Versions can be equal in case if Marketplace noticed and automatically repaired an inconsistency in IAM setup: created a missing OAuth2Client or updated a misconfigured one;

3. OAuth2Client credentials, i.e. clientId and clientSecret pair, for all confidential clients created as part of this operation;

1. If no confidential clients were created during an upgrade, $.payload.clientCredentials will be empty;

4. clientId for all public clients created as part of this operation;

1. If no public clients were created during an upgrade, $.payload.publicClients property will be absent.

The expected response is the same as for installation: either 200 OK or 202 Accepted HTTP status code. Despite this, Carerix encourages using a synchronous way of feature upgrade handling, i.e. responding with 200 OK.

To prevent unauthorized access to management endpoint, vendor has to check an access token. The rules are the same as with feature installation, please refer to corresponding article section.

Responding with 200 OK means that a request was processed synchronously by feature vendor and the Marketplace has just to complete the upgrade by changing the feature status back to activated immediately.

This event occurs when a customer leaves Carerix, his tenant record gets deleted and thus all his features have to be cleaned up as well.

When triggered, Marketplace will invoke a management endpoint provided by the vendor and then delete a Feature record.

The management endpoint request may look like this:

The request body contains:

1. An event type: "_kind": "FeatureCleanupCommand" which indicates that feature cleanup was triggered;

2. A URL where to send callbacks;

3. Actual feature cleanup payload:

1. tenant containing an identifier for a tenant for whom cleanup is being done.

The marketplace expects that the management endpoint will respond with either 200 OK or 202 Accepted HTTP status code. A response with any other status code will abort this cleanup attempt. Response body is ignored by the Marketplace.

Unlike all previous management requests, a cleanup one contains a different access token in Authorization header!

This is due to the fact that tenant doesn’t exist in IAM anymore, thus there’s no way to obtain a token for him. Instead, a token for master realm is used.

Use $.payload.tenant request body property to know which tenant was cleaned up.

To prevent unauthorized access to management endpoint, vendor has to check that provided access token satisfies these conditions:

· iss claim contains a valid tenant URL: https://id.carerix.io/auth/realms/master;

· azp claim is equal to features.apps.carerix.io;

· Signature is valid;

· Is not expired.

Now, disregarding whether 200 OK or 202 Accepted will be returned in a response for cleanup management request, Marketplace will consider cleanup as finished and will delete a Feature.

Responding with 200 OK means that a request was processed synchronously by feature vendor and the Marketplace has just to complete the cleanup by deleting a Feature immediately.

If a vendor expects decommissioning of tenant resources to take a long time (more than 10 seconds), then cleanup implementation must take the asynchronous approach.

Responding with 202 Accepted means that feature vendor needs some time to handle the request (e.g. drop a database schema, call some other APIs etc), thus cleanup is done in an asynchronous way.

A vendor doesn’t have to call the Marketplace’s callback endpoint to deliver the result of cleanup, as there’s no way to obtain a tenant’s token because a tenant is already deleted.

Sometimes, a Feature has to be configurable, allowing tenant administrator to specify how it has to behave or pass some sensitive data such as API key to a vendor. Marketplace offers a concept of settings to handle such cases.

If vendor decides that a Feature has to have one or more settings, then:

· they must be declared in the Manifest;

· implementation for “Update” lifecycle event handling must support update of declared settings;

· settings endpoint specified in the manifest must serve settings values stored for a tenant.

Carerix recommends storing sensitive setting values in a secure storage, such as Hashicorp Vault or AWS Secrets Manager.

Feature settings solve following problems:

· help building a frontend look-and-feel for a user;

· configure a behaviour of Feature’s backend, including sensitive data (e.g. API key).

Thus, besides being stored and used by a service backing a Feature, besides being queried and updated by tenant administrator, settings are also queried by regular tenant users.

After a user is authenticated into Carerix, UI loads a list of manifests and features available for him. But for those features with at least one setting declared, UI will also request the settings values.

Here, Marketplace acts as a proxy between a tenant user and a Feature, validating Feature existence and status as well as user’s permissions. Moreover, Marketplace will filter out from the output all settings with sensitive: true configured, in case if user is not a tenant’s administrator. Thus, sensitive settings are accessible only for tenant’s administrator and a Feature service storing them.

Carerix Marketplace never stores setting values. Rather, it asks a Feature component to get or update them.

Each Feature setting have to be bound to an OAuth2Client declared in the same Manifest - as all settings exist to configure a certain middleware, web application, browser extension etc. Thus, declared settings have to be grouped by serviceId - a map key of an OAuth2Client also declared in a Manifest. Carerix Marketplace supports some common types of settings fields, sensitivity flag and primitive validation.

Here’s an example of settings section of a Manifest describing three setting fields:

Specifications for most relevant settings properties are following:

Here’s a list of supported setting types:

Each feature has to implement a settings endpoint (even if no settings are declared within a Manifest) and its URL has to be specified in $.buildInfo.settingsUri property of a Manifest.

The settings endpoint request will not contain any request body and will look like this:

To prevent unauthorized access to settings endpoint, vendor has to check an access token. The rules are the same as with feature installation request sent to management endpoint, please refer to corresponding article section.

The marketplace expects that the settings endpoint will respond with 200 OK HTTP status code and a valid JSON in a response body. This JSON has to contain a single settings property which hold all Feature settings grouped by serviceId, e.g.:

If a Manifest declares no settings, then settings endpoint has to return an empty settings object in a response body, e.g.: { "settings": {} }.

Sensitive settings have to be returned as well, Marketplace will take care of whether such values will be shown or not.

Given the example of Manifest’s settings section provided above, response body returned by the settings endpoint may look like this:

Vendor should take into an account that settings endpoint will be queried often if there’s at least one setting defined in a Manifest: each time after a user logs into a system if user’s tenant has this Feature activated.

Therefore, settings endpoint should be able to serve a single API request in less than 500ms.

Here are the steps a vendor has to take in order to successfully integrate with Carerix Marketplace:

1. Find out what OAuth2Client(s) an integration will need, what scopes and permissions should they have;

2. Determine whether a feature has to be configurable by tenant’s administrator and if so, how;

3. Estimate what is needed to start supporting a new customer or off-boarding an existing one:

1. Are there any external API calls to be executed?

2. Is there a separate database or a database schema needed for a tenant?

3. Is there any other long-running operation needed to be done?

4. Compose a manifest providing management&settings URIs, OAuth2Clients configuration from p.1, settings from p.2 and general information about the vendor;

5. Implement a management endpoint supporting all types of lifecycle events: installation, activation, deactivation, update, uninstallation, upgrade and cleanup;

1. If answer for any of the p.3 questions is “Yes”, then implementation for installation, uninstallation and cleanup lifecycle events has to take the asynchronous approach;

2. Otherwise, all events have to be handled in synchronous way;

6. Implement a settings endpoint;

1. Even if a feature doesn’t declare any settings, implementation is needed, but in that case it’s enough to just return a JSON object with empty settings property.

Feel free to contact Carerix if any help is needed with Manifest creation or any other part of an integration.

Marketplace has a mechanism allowing to configure a Feature access:

· make it public, so any tenant can install and activate one;

· allow it to be installable only by a selected group of tenants (whitelist);

· allow it to be installable by any tenant except a selected group (blacklist).

This is particularly useful when a Feature is not yet ready to be released, instead undergoes development or testing on selected “dev” or “internal” systems.

Access restriction is controlled by Carerix and not by a Manifest file. Therefore, a tenant whitelist has to be defined before any integration implementation starts.