Skip to main content

How Access Control Works

In this tutorial, you will learn how to use organizations, system roles, and IAM role mappings 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 step-by-step setup instructions, see Configure Access Control.

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 your existing IAM roles to system roles and organizations
  • 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

Your institution already has an IAM system with roles assigned to staff. Your task is not to create those roles, but to register them in Procivis One and define what they can do.

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:

  • Issuer
  • Verifier
  • Holder
  • Wallet Provider
  • National Registry
  • Access Certificate Provider
  • Registration Certificate 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, assign "Issuer" and "Verifier".
  • Regulatory Compliance Authority — Since this office holds credentials and presents them when needed, assign "Holder".
  • Ministry of Public Administration — Since this office verifies credentials for the hiring process and issues employment verification credentials, 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. Even if a user has a system role that includes holder permissions mapped to that 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:

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
  • 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 system role bundles specific permissions together, allowing you to grant consistent access levels to staff members regardless of which ministry they work in.

3

Map IAM roles to system roles​

Your institution already has IAM roles assigned to staff in your identity provider. In this step you register those roles in Procivis One and define which system roles they map to in which organizations.

When you register an IAM role you will provide:

  • Its name — this must match the role name exactly as it appears in your identity provider
  • Which system roles apply in which organizations
  • An optional description

For example, your IAM system has a role called compliance-manager, assigned to staff in the Regulatory Compliance Authority who also run audits across other ministries. Register it in Procivis One 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 role in your identity provider will receive these organization and permission assignments when they authenticate.

Using the API?

Your call to register an IAM role uses /api/sts/iam-role/v2 and will look like this:

      {
        "name": "compliance-manager",
        "description": "Manages the RCA and audits other ministries.",
        "roleOrganisations": {
          "{{IDENTITY-MANAGER-ID}}": {
            "isGlobal": false,
            "organisations": ["{{RCA-ORG-ID}}"]
          },
          "{{WALLET-ADMIN-ID}}": {
            "isGlobal": false,
            "organisations": ["{{RCA-ORG-ID}}"]
          },
          "{{AUDITOR-ID}}": {
            "isGlobal": false,
            "organisations": ["{{MCI-ORG-ID}}", "{{MPA-ORG-ID}}"]
          }
        }
      }

Note that isGlobal: true applies a system role across all organizations, including any created in the future. For example, a quality-controller role with the Auditor system role set to isGlobal: true would automatically gain audit access to any new ministry added to the system.

Other IAM roles for the institution could include:

  • hr-specialist — "Verification Specialist" and "Identity Manager" for the Ministry of Public Administration
  • quality-controller — "Auditor" across all organizations
  • permit-admin — "Schema Admin", "Credential Operator", and "Verification Specialist" for the Ministry of Construction & Infrastructure

With these mappings in place, your existing IAM roles are now connected to the appropriate permissions and organizations in Procivis One. When a user authenticates, the system uses their IAM role to determine what they can do and where.

How these fit together​

Now that you have set up organizations, system roles, and IAM role mappings, 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 role mappings 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 access a different organization the user must obtain 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.

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

  3. The Enterprise Backend's Secure Token Service (STS) looks up the IAM role mappings and system roles you configured, and issues an application token containing 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 within her active organization.

Example​

Suppose Maria has the compliance-manager IAM role with the following mappings:

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

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

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

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