light-mode-image
Learn

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 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

  1. Create a new tenant: This tenant will be used to trial the RBAC configuration.
  2. Create a new client: We will create a new client for our new tenant, and assign a specific set of permissions to the client.
  3. 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.

  1. Select the Create/switch tenant button on the top-right side of the screen.
    The All tenants panel is displayed, listing any existing tenants.
  2. Select the Create new button.
    The New tenant form is displayed.
  3. Use the Region dropdown list to select the region your tenant will be hosted in.
  4. Use the Tenant subdomain text box to insert a subdomain for your tenant (e.g. access-control-tenant).
  5. Use the Tenant name text box to insert a meaningful and friendly name for your tenant (e.g. Access Control Tutorial Tenant).
  6. Select the Create button to create the new tenant.
  7. Copy the displayed tenant information and record it somewhere safe for future reference.
  1. Make a request of the following structure to obtain a Management API access token:
Request
POST https://auth.manage.au01.mattr.global/oauth/token
Request Body
{
  "client_id": "F5qae*************************",
  "client_secret": "Wzc8J**********************************************************",
  "audience": "https://manage.au01.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.au01.mattr.global as per the example above.
  • grant_type : Use client_credentials as per the example above.

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.

Response

Response body
{
  "access_token": "eyJhb********************************************************************", 
  "expires_in": 14400,
  "token_type": "Bearer"
}
  1. Use the returned access_token must be used as a bearer token for all requests to the Management API in the next steps to make a request of the following structure to create a new tenant:
Request
POST https://manage.au01.mattr.global/v1/tenants
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 body
{
  "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.au01.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.

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.

  1. Open Platform Management in the left navigation panel and select Tenant.
    The tenant management screen appears.
  2. Click Create/Switch Tenant at the top-right.
    The All Tenants window opens.
  3. Click Switch next to the tenant created in the previous step.
  4. Under Platform Management, select Users, clients & roles.
  5. Go to the Clients tab and click Create new.
  6. Enter a name to identify the client in the Name field (e.g. Tutorial Issuer client).
  7. Select the Issuer checkbox in the Tenant access section.
  8. Click Create to create the client
  9. 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.

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

Request
POST https://manage.au01.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
{
  "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 body
{
  "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.

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.

How would you rate this page?

Roles and permissions

Previous Page

Create a client

Next Page

On this page

OverviewPrerequisitesTutorial stepsCreate a new tenantCreate a new clientTest client permissionsSummary