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 for more information.

In this tutorial you will learn how to manage access control for your tenants by assigning roles to clients, either using the MATTR Portal or the Management API.

This tutorial covers managing access controls for clients.

If you want to manage access for users, see the Inviting a user to a tenant guide. That guide also explains how to assign roles to users.

Once a user logs into the Portal and selects a tenant, they will only have access to the capabilities associated with their assigned roles.

Prerequisites

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

Tutorial steps

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.

Create a new tenant

Start off by creating a new tenant, either using the MATTR Portal or the Management API.

Select the Create/switch tenant button on the top-right side of the screen.
The All tenants panel is displayed, listing any existing tenants.
Select the Create new button.
The New tenant form is displayed.
Use the Region dropdown list to select the region your tenant will be hosted in.
Use the Tenant subdomain text box to insert a subdomain for your tenant (e.g. access-control-tenant).
Use the Tenant name text box to insert a meaningful and friendly name for your tenant (e.g. Access Control Tutorial Tenant).
Select the Create button to create the new tenant.
Copy the displayed tenant information and record it somewhere safe for future reference.

Create a new client

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.

Open Platform Management in the left navigation panel and select Tenant.
The tenant management screen appears.
Click Create/Switch Tenant at the top-right.
The All Tenants window opens.
Click Switch next to the tenant created in the previous step.
Under Platform Management, select Users, clients & roles.
Go to the Clients tab and click Create new.
Enter a name to identify the client in the Name field (e.g. Tutorial Issuer client).
Select the Issuer checkbox in the Tenant access section.
Click Create to create the client
Make note of the displayed client credentials (auth_url, tenant_url, client_id and client_secret) as you will need them in the next step.

The client_secret is only displayed immediately after the client is created. Once you navigate away from this screen, the client secret will be masked and cannot be retrieved again. Ensure you save it securely at this point.

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.

Regardless of whether you created the client using the MATTR Portal or the Management API, you should have the clientId and clientSecret values available to you. You will need these to obtain an access token for the new client.

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

Response body

{
  "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"
}

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, either using the MATTR Portal or the Management API.

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

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