Learn how to setup role based access control for your MATTR VII tenant

Overview

MATTR VII uses Role-Based Access Control (RBAC) to manage permissions and access within a tenant. Each role grants access to specific capabilities, ensuring that users or clients only have access to the functionalities they need. Refer to Access control in the Docs section for more information.

In this tutorial you will learn how to manage access control for your tenants by assigning roles to clients.

Prerequisites

You will need client credentials (client_id and client_secret) to use the Management API.

These are not the same client_id and client_secret you were provided for accessing the MATTR VII Platform API, but rather unique credentials for accessing the Management API. If you have not received these credentials or have any questions, please contact us before proceeding.

Tutorial steps

Obtain a Management API access token: The access token will be used to make a request to create a new tenant.
Create a new tenant: This tenant will be used to trial the RBAC configuration.
Create a new client: We will create a new client for our new tenant, and assign a specific set of permissions to the client.
Test client permissions: Finally we will use the new client credentials to obtain an access token and make requests to different endpoints. This should ensure the client permissions were properly configured.

Obtain a Management API access token

Request

Make a request of the following structure to obtain a Management API access token:

Request

POST https://auth.manage.mattr.global/oauth/token

Request body

Request Body

{
    "client_id": "F5qae*************************",
    "client_secret": "Wzc8J**********************************************************",
    "audience": "https://manage.mattr.global",
    "grant_type": "client_credentials"
}

client_id : Replace with the client_id value from your Management API client credentials.
client_secret : Replace with the client_secret value from your Management API client credentials.
audience : Use https://manage.mattr.global as per the example above.
grant_type : Use client_credentials as per the example above.

Response

Response

{
    "access_token": "eyJhb********************************************************************",
    "expires_in": 14400,
    "token_type": "Bearer"
}

The returned access_token must be used as a bearer token for all requests to the Management API in the next steps.

Create a new tenant

Now that you have an access token, you can use it to create a new tenant we can trial our access control features with.

Request

Make a request of the following structure to create a new tenant:

Request

POST https://manage.mattr.global/v1/tenants

Request body

Request body

{
    "name": "Access Control Tutorial Tenant",
    "subdomain": "access-control-tenant",
    "environmentId": "fa605282-0223-4ae0-831d-af368bc39a55"
}

name : The name that will be used to identify this tenant.
subdomain : The subdomain that will be used to access this tenant.
environmentId : The unique identifier of the environment where the new tenant will be created. You can make a request to retrieve all environments you have access to and use the id value from the response as the environmentId.

Response

Response

{
    "id": "6facbcef-66cd-4a06-89e3-e44a4fc12000",
    "name": "Access Control Tutorial Tenant",
    "subdomain": "access-control-tenant.vii.au01.mattr.global",
    "environment": {
        "id": "fa605282-0223-4ae0-831d-af368bc39a55",
        "name": "Public Australia Sydney",
        "domain": "vii.a01.mattr.global",
        "deploymentModel": "public",
        "authorizationServerDomain": "auth.manage.mattr.global",
        "region": {
            "id": "0fd6ce12-a983-41d0-aca8-03e1bb6f6000",
            "name": "au01",
            "displayName": "Sydney, Australia"
        }
    },
    "client": {
        "clientId": "MjQx108p***************FlwJQjy",
        "clientSecret": "NanfSkVr**********************PfD3zJ"
    }
}

id : Globally unique tenant identifier.
name : As provided in the request.
subdomain : The tenant URL, constructed with the subdomain value provided in the request.
environment : Indicates data for the environment in which the new tenant was created.
client : Indicates the clientId and clientSecret for the default client created for this tenant. This client is assigned an Admin role by default, meaning it has access to all endpoints in the tenant.

We now have a tenant and a default admin client. Next we will create a client that will have an Issuer role, enabling them to only access a subset of the tenant endpoints and capabilities.

Create a new client

Request

Make a request of the following structure to create a new tenant client:

Request

POST https://manage.mattr.global/v1/tenants/{tenantId}/clients

tenantId : Replace with the id identifying the tenant, obtained from the previous step’s response. This creates the client in the context of a specific tenant.

Request body

Request Body

{
    "name": "Tutorial Issuer client",
    "roles": ["issuer"]
}

name : Name of the client associated with this tenant.
roles : An array of roles assigned to this client based on the capabilities it needs to access. In our example we are assigning it the role of an Issuer.

Response

Response

{
    "clientId": "suC7I*******************************",
    "clientSecret": "Qn_43J****************************************************",
    "name": "Example client",
    "permissions": ["permission_1", "permission_2", "permission_3"],
    "roles": ["issuer"]
}

clientId : Client identifier for retrieving a tenant access token.
clientSecret : Client secret for retrieving a tenant access token.
name : As provided in the request.
permissions : An array of permissions assigned to the client based on the defined roles.
roles : As provided in the request.

Test client permissions

You have successfully created a new client with a limited set of permissions relevant to credential issuance. We can now test these permissions work as expected.

Step 1: Obtain access token

Use the new client’s clientId and clientSecret obtained in the previous step to obtain an access token for accessing the tenant:

Request

POST https://auth.au01.mattr.global/oauth/token/oauth/token

If you created your tenant in a different environment you might need to use a different authentication server. Please contact us if you are unsure.

Request body

{
    "client_id": "F5qae*******************************",
    "client_secret": "Wzc8J**********************************************************",
    "audience": "access-control-tenant.vii.au01.mattr.global",
    "grant_type": "client_credentials"
}

client_id : Replace with the clientId value obtained in the previous step.
client_secret : Replace with the clientSecret value obtained in the previous step.
audience : Replace with the subdomain obtained when you created the tenant.
grant_type : Use client_credentials as per the example above.

Response

JSON

{
    "access_token": "eyJhb********************************************************************",
    "expires_in": 14400,
    "token_type": "Bearer"
}

The returned access_token will enable accessing endpoints as per the Issuer role assigned to the client. Let’s test this works as expected.

Step 2: Make a request to an endpoint the client should have access to

Use the access_token obtained in the previous step and make a request of the following structure to create a new IACA:

POST https://access-control-tenant.vii.au01.mattr.global/v2/credentials/mobile/iacas

{
    "commonName": "Example IACA",
    "country": "US",
    "stateOrProvinceName": "US-AL",
    "notBefore": "2024-09-26",
    "notAfter": "2034-09-26",
    "active": true
}

As a client with an Issuer role is expected to have access to this endpoint (used to create new IACA certificates), you should receive a successful 201 response.

Step 3: Make a request to an endpoint the client should not have access to

Use the access_token obtained in the previous step and make a request of the following structure to create a new Ecosystem:

Request

POST https://access-control-tenant.vii.au01.mattr.global/v1/ecosystems

Request body

{
    "name": "My Ecosystem"
}

As a client with an Issuer role is not expected to have access to this endpoint (used to create new Ecosystems), you should receive a 403 (Forbidden) error.

Summary

In this tutorial you’ve learnt how to manage access control for your tenants by assigning roles to clients.

You can now use a similar approach to assign different roles to different tenant clients as per your implementation requirements and security practices.

Publish an Ecosystem policy Identifiers