Organizations tutorial

Learn how to manage permissions, roles, and organizations for complex institutions

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.

You will learn

• How to create system 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

System organizations provide a fundamental division of ownership of assets. You will want to create a system organization for each entity that needs to own and operate its own assets such as cryptographic keys, X.509 certificates, credentials, and related data. Since each of the three ministries need to operate independently, you will create one system organization for each ministry.

When you create an organization you will provide:

• Its name
• The roles it performs
• An optional logo and description

All of these can be updated later if you change your mind. Guidance in choosing organizational roles follows.

Assigning organizational roles

Each system organization is assigned some subset of the following roles:

1. Issuer

2. Verifier

3. Holder

Each role corresponds to related actions in the system. For example, an organization with the role "Issuer" is permissioned to take all the actions needed to issue credentials, such as creating credential schemas and issuing credentials to wallets.

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 assigned here set the outer boundaries of what anyone within the organization is permitted to do. For example, with the assignments above, the Ministry of Contruction & Infrastructure cannot hold credentials. That means that even if a user is assigned a custom user role that allows permissions to hold credentials, and has that role for the Ministry's organization, they would not be able to hold credentials since the organization itself is not enabled with those permissions.

Three new organizations

Your final system 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 new organizations you have set up the system to reflect the basic divisions of your institution. Each ministry will be able to create new assets that can only be accessed within the organization, allowing each to operate independently.

2

Create custom roles

Roles provide a way to divide system permissions into functions common to your broader institution. You will want to create roles that contain the least number of permissions while still representing a functional role an end user could perform. Consider the tasks that will need to be performed across the institution. Someone will need to:

Clear boundaries can be seen between the roles described: the end user responsible for verifying building permits during site inspections does not need to be responsible for creating and rotating cryptographic keys, and the user who performs departmental audits does not need to issue credentials.

Defining permissions

To create a custom 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 {{ASSET}}_{{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 custom 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. Given the institution's ... :

When you create an IAM role you will provide:

• Its name
• Which 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}}"]
},
"decription": "Manages the RCA and audits other ministries." // Optional
}

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 the creation of these IAM roles you have mapped your custom 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, custom 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 overlap 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.
• Custom roles define the specific permissions a user has been granted. Even if the organization supports credential issuance, a user with only the "Auditor" role cannot issue credentials — they can only read existing data.
• IAM roles determine where those custom 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.

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 Desk takes this token, looks up the IAM roles and custom roles you created in the earlier steps, and issues an app token that includes a list of all permissions Maria has and the organizations in which she has them.

4. This token is stored in Maria's Desk session. As she takes actions, the system 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.