Access Control Tutorial

In this tutorial, you will learn how to use organizations, roles, and IAM configurations to create a flexible and secure setup that reflects real-world government and business operations.

info

This tutorial demonstrates the complete access control system using a government scenario. For conceptual explanations, see Organizations and Permissions.

You will learn

• How to create organizations to reflect institutional divisions
• How to create system roles to reflect the functional roles of your institution
• How to map roles to organizations to reflect how people work across divisional boundaries
• How the intersection of these elements produces security through granular control of permissions

Scenario

You are the IT administrator for a national government that has decided to implement a digital credential system across multiple ministries. Your task is to configure the system to support three key government departments that will use credentials in different ways:

• Ministry of Construction & Infrastructure - Issues building permits and construction licenses to contractors and developers. They also verify these permits during on-site inspections to ensure compliance with national building codes.

• Regulatory Compliance Authority - Holds various ISO certifications and quality standards credentials that demonstrate the government's compliance with EU regulations. They need to present these credentials to auditors and international bodies.

• Ministry of Public Administration - Handles hiring for civil service positions, which requires verifying educational credentials, professional certifications, and conducting background checks on potential employees and contractors. This office also issues employment verification credentials for all national civil servants.

Each ministry operates independently but occasionally needs to collaborate. For example, Public Administration might need to verify a contractor's building permits when hiring for infrastructure projects, or Construction might need to check a vendor's quality certifications before approving them for major projects.

Your job is to set up the system so that:

• Each ministry can perform their core functions securely
• Staff have appropriate access levels based on their roles
• Cross-ministry collaboration is possible when needed
• Sensitive operations remain restricted to authorized personnel

1

Create organizations

Organizations provide fundamental isolation of assets and operations. You will want to create an organization for each entity that needs to own and operate its own cryptographic keys, X.509 certificates, credentials, and related data. Since each of the three ministries needs to operate independently, you will create one organization for each ministry.

When you create an organization you will provide:

• Its name
• The organizational roles it can perform
• An optional logo and description

All of these can be updated later. Guidance on choosing organizational roles follows.

Assigning organizational roles

Each organization is assigned some subset of the following roles:

1. Issuer

2. Verifier

3. Holder

4. Wallet provider

Organizational roles define a permission ceiling—the maximum set of operations possible within that organization. When users request tokens for an organization, the STS filters their permissions to only include those allowed by the organization's role.

For example, an organization with the "Issuer" role allows credential issuance operations. Even if a user has verification permissions in their IAM token, they won't receive those permissions when accessing an issuer-only organization.

You will want to assign the roles that correspond to the needs of each ministry:

• Ministry of Construction & Infrastructure - Since this office issues and verifies building permits, you will want to assign "Issuer" and "Verifier".
• Regulatory Compliance Authority - Since this office holds credentials and presents these credentials when needed, you will want to assign "Holder".
• Ministry of Public Administration - Since this office verifies credentials for the hiring process and issues employment verification credentials for government workers, you will want to assign "Verifier" and "Issuer".

Organizational roles set the outer boundaries of what anyone within the organization can do. For example, with the assignments above, the Ministry of Construction & Infrastructure cannot hold credentials. That means even if a user has a system role that includes holder permissions, and has that role mapped to the Ministry's organization, they would not be able to hold credentials since the organization itself is not assigned the "Holder" role.

Three new organizations

Your final organizations will look like this:

1. Ministry of Construction & Infrastructure

• Roles: "Issuer", "Verifier"
• Description: "Responsible for building permits."

2. Regulatory Compliance Authority

• Roles: "Holder"
• Description: "Responsible for maintaining ISO certifications."

3. Ministry of Public Administration

• Roles: "Verifier", "Issuer"
• Description: "Responsible for human resources."

Using the API?

Your call to create an organization will look like this:

{
"roles": [
    "ISSUER",
    "VERIFIER"
],
"logo": "data:image/jpeg;base64,/9j/4AAQSkZJRgABAQAAA...",
"description": "Responsible for building permits.",
"name": "Ministry of Construction & Infrastructure"
}

With the creation of these organizations you have set up the system to reflect the basic divisions of your institution. Each ministry can create assets that can only be accessed within the organization, allowing each to operate independently.

2

Create system roles

System roles provide a way to group permissions into functional job categories common across your institution. You will want to create system roles that contain the minimum permissions needed to perform a specific function. Consider the tasks that will need to be performed across the institution. Someone will need to:

With the creation of these system roles you have defined reusable permission sets that can be applied across your institution. Each system role bundles specific permissions together, allowing you to grant consistent access levels to staff members regardless of which ministry they work in.

Defining permissions

To create a system role, define the list of permissions for that role. For example, for the "Identity Manager" role, you will want to enable the following permissions:

• Identifiers
  • Create
  • Delete
  • Detail
  • List
• Keys
  • Create
  • Detail
  • List
  • Generate CSR (for certificates)
• DIDs
  • Create
  • Deactivate
  • Detail
  • List
  • Resolve

These permissions enable administrative control over important identity assets.

Using the API?

Permissions take the form {{RESOURCE}}_{{ACTION}}, for example:

• CREDENTIAL_LIST enables the GET method on /api/credential/v1
• KEY_CREATE enables the POST method on /api/key/v1

Your call to create the "Identity Manager" role will look like this:

{
    "name": "Identity Manager",
    "permissions": [
        "IDENTIFIER_CREATE",
        "IDENTIFIER_DELETE",
        "IDENTIFIER_DETAIL",
        "IDENTIFIER_LIST",
        "KEY_LIST",
        "KEY_DETAIL",
        "KEY_CREATE",
        "KEY_GENERATE_CSR",
        "DID_CREATE",
        "DID_DETAIL",
        "DID_DEACTIVATE",
        "DID_LIST",
        "DID_RESOLVE"
    ]
}

For the complete list of permissions, see the permissions entry of your configuration.

With the creation of these system roles you have defined reusable permission sets that can be applied across your institution. Each role bundles specific permissions together, allowing you to grant consistent access levels to staff members regardless of which ministry they work in.

3

Create IAM roles

IAM roles provide the mapping between users and their permissions across organizations. You will want to create an IAM role for each distinct combination of job function and organizational access that exists in your institution.

When you create an IAM role you will provide:

• Its name
• Which system roles are permitted in which organizations
• An optional description of the role

For example, the Regulatory Compliance Authority has a position called "Compliance Manager". This position needs to manage identity assets for the Regulatory Compliance Authority, as well as handle the ministry's organizational wallet. They also run internal audits across all other ministries. You will want to create the IAM role with the following assignments:

• Regulatory Compliance Authority
  • Identity Manager
  • Wallet Admin
• Ministry of Construction & Infrastructure
  • Auditor
• Ministry of Public Administration
  • Auditor

Any user assigned the "Compliance Manager" IAM role will be granted the above organization-role authorizations.

Using the API?

Your call to create an IAM role will look like this:

{
  "name": "RCA Compliance Manager",
  "organisationRoles": {
    "{{RCA-ORG-ID}}": ["{{IDENTITY-MANAGER-ID}}", "{{WALLET-ADMIN-ID}}"],
    "{{MCI-ORG-ID}}": ["{{AUDITOR-ID}}"],
    "{{MPA-ORG-ID}}": ["{{AUDITOR-ID}}"]
  },
  "description": "Manages the RCA and audits other ministries." // Optional
}

Other IAM roles for the institution could include:

• "HR Specialist"
  • "Verification Specialist" and "Identity Manager" system roles for the Ministry of Public Administration
• "Quality Controller"
  • "Auditor" system role across all organizations
• "Permit Admin"
  • "Schema Admin", "Credential Operator", and "Verification Specialist" system roles for the Ministry of Construction & Infrastructure

With the creation of these IAM roles you have mapped your system roles to specific organizations, defining exactly where each permission set can be applied. Each IAM role represents a unique combination of job function and ministerial access, allowing staff to have different permission levels depending on which ministry they are currently working with.

IAM tokens

Once your IAM roles are configured in the system, you will need to configure your institutional identity provider to issue tokens that include each user's assigned IAM roles. This integration ensures that when users authenticate, the system knows which permissions they have across which organizations and can issue the appropriate app token. The specific steps for this integration depend on your identity partner and will be covered in dedicated integration documentation.

How these fit together

Now that you have set up organizations, system roles, and IAM roles, it is important to understand how these layers work together to determine what any individual user can do in the system. A user's effective permissions are determined by the intersection of the following elements:

• Organizational roles set the outer boundaries. If the Ministry of Construction has the "Issuer" and "Verifier" roles only, no user in that organization can perform "Holder" actions, regardless of their other role assignments.
• System roles define the specific permissions a user has been granted. Even if the organization supports credential issuance, a user with only the "Auditor" system role cannot issue credentials — they can only read existing data.
• IAM roles determine where those system role permissions can be applied. A user might have "Schema Admin" permissions for the Ministry of Construction but only "Auditor" permissions for the Regulatory Compliance Authority.
• Active organization provides the final context. Users can only exercise permissions within their currently selected organization. To get access to a different organization the user must get a new token.

In the API

Here is an overview of what happens when a user "Maria" logs in to the system:

1. Maria logs in using the integrated identity provider (IAM).

2. The IAM provider issues a token that includes a list of Maria's IAM roles.

3. The Enterprise Backend's Secure Token Service (STS) takes this token, looks up the IAM roles and system roles you created in the earlier steps, and issues an application token that includes Maria's effective permissions for each organization she has access to.

4. When Maria selects an organization to work with, she receives a token scoped to that organization. As she takes actions, Core checks that each action is permitted for her active organization.

Example

For example, suppose Maria has the "Compliance Manager" IAM role with the following organization and role mappings:

• Regulatory Compliance Authority
  • "Identity Manager"
  • "Wallet Admin"
• Ministry of Construction & Infrastructure
  • "Auditor"
• Ministry of Public Administration
  • "Auditor"

When Maria logs into the Ministry of Construction and tries to issue a building permit, the system checks her app token for:

"permissions": {
    "CREDENTIAL_ISSUE": ["{{MINISTRY-OF-CONSTRUCTION-ID}}"],
  }

Since she is only an "Auditor" for the Ministry of Construction, she does not have permission to issue credentials and her attempt is blocked.

Next steps

With your multi-layered authorization structure in place, you are ready to move from configuration to implementation. Here are the key steps to make this system operational:

• Configure identity provider integration: your institutional IAM system (Active Directory, Okta, or similar) needs to be configured to include IAM role assignments in user authentication tokens. This integration ensures that when users log in, the system knows their permission levels across all ministries. The specific configuration steps depend on your IAM provider.
• Assign IAM roles to users: work with your institutional administrators to assign the IAM roles you have created to actual staff members.