How to make requests in a multi-tenant environment

Prerequisites

• Orchestrate running with multi-tenancy enabled.

Setting the tenant ID and username

When using multi-tenancy, all client requests require an authorization token (JWT) used to identify and authorize the caller.

In production, the custom claim used to generate the JWT is provided by an identity provider such as Auth0. The custom claim specifies a tenant_ID, a value indicating the authorized tenant, and a username, an optional value specifying individual users.

The value for tenant_ID can be:

• The string _, which grants access only to resources available to all tenants (public resources).

• A specific tenant name, which grants access to the tenant identities and keys, plus the public resources belonging to tenant _.

• The string *, which grants access to all resources regardless of restriction (this is like root access, so be careful using it).

When receiving a request, once the server has successfully performed standard checks on the JWT, it extracts the tenant_ID and a X-Tenant-ID header that is optionally set by the client indicating the tenant to impersonate. The combination of these two values determines to whose resources access is granted, as shown in the following table (using foo and bar as example tenant names):

tenant_ID	X-Tenant-ID	Read access	Write access
foo	empty	foo, _	foo
foo	bar (invalid)	n/a	n/a
foo	foo	foo	foo
foo	_	_	_
foo	* (invalid)	n/a	n/a
*	empty	all tenants, _	_
*	foo	foo	foo
*	_	_	_
*	*	all tenants, _	_

Defining access

You can define more advanced access levels by using nested tenants in combination with username to restrict access to resources by group and individual privileges. Resources you can restrict include chains, accounts, and transactions.

Use : to identify each additional level of access with tenant_ID and the optional X-Tenant-ID. Each nested level gives access to the resources of itself and the previously listed level. The following table shows examples for three levels of nesting.

tenant_ID	Level of access
tenantOne	tenantOne resources only
tenantOne:groupOne	tenantOne and tenantOne:groupOne resources
tenantOne:groupOne:departmentOne	tenantOne, tenantOne:groupOne, and tenantOne:groupOne:departmentOne resources

A user with tenant_ID=tenantOne:groupOne and username=userOne claims has access to tenantOne, tenantOne:groupOne, and userOne resources.

Make a request

Simply pass the Bearer token as part of the Authorization header when doing an HTTP call or fill the authToken parameter when using the JS SDK.

REST Request

curl --location --request GET 'https://orchestrate.consensys.net/chains' \
--header 'Authorization: Bearer eyJh...JoVg'

JavaScript (SDK)

const authToken = "eyJhb...JoVg";
const chain = await chainRegistry.registerChain(chainRequest, authToken);

tip

The Quorum Developer Quickstart showcases usage of the multi-tenancy.