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_idandclient_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_idandclient_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:
POST https://auth.au01.mattr.global/oauth/token/oauth/tokenIf you created your tenant in a different environment you might need to use a different authentication server. Please contact us if you are unsure.
{
"client_id": "F5qae*******************************",
"client_secret": "Wzc8J**********************************************************",
"audience": "access-control-tenant.vii.au01.mattr.global",
"grant_type": "client_credentials"
}client_id: Replace with theclientIdvalue obtained in the previous step.client_secret: Replace with theclientSecretvalue obtained in the previous step.audience: Replace with thesubdomainobtained when you created the tenant.grant_type: Useclient_credentialsas per the example above.
Response
{
"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:
POST https://access-control-tenant.vii.au01.mattr.global/v1/ecosystems{
"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?
Last updated on