Ctrlk
CommunitySupport PortalYouTubeFree trialSign Up!
For the complete documentation index, see llms.txt. This page is also available as Markdown.

IAM Tutorial

Names and descriptions of groups, permissions, resources, access control templates, and role resources are localized.

Looking for more info on localization? Check out Standard practices.

How to create a group of employees with a specific set of access controls

To specify user access level in a particular service resource, you need to create a group of users that share the same access controls. For the purposes of this tutorial, you will create an employee group with manager rights in Catalog API service.

Before you start

Ensure you have a tenant and users created.

To create users, check out the Manage Users tab in the Emporix Developer Portal.

Retrieve a list of available access controls

There's a set of access controls that are predefined and designed to cover all necessary scenarios. It is not possible to change the built-in access controls, but you can create new custom ones. See section How to manage custom scopes.

To assign specific access control level to a group, first you need to retrieve a list of predefined access controls available for your tenant by sending a request to the Retrieving all access controls endpoint.

To test the endpoint, open the API reference or check the example of a curl request.

API Reference
curl -i -X GET 
  'https://api.emporix.io/iam/{tenant}/access-controls?pageNumber=1&pageSize=60&metadataModifiedAt=2022-01-01&roleId=1rl5e52e-6e27-4ac5-9471-2467d3fb7503&resourceId=string&expand=role%2Cresource' 
  -H 'Accept-Language: string' 
  -H 'Authorization: Bearer {{OAUTH2_ACCESS_TOKEN}}' 
  -H 'X-Total-Count: true'

Create an employee group

Employee groups aggregate users that share the same access control within a particular service and resource. Create an employee group and assign access controls to it by sending a request to the Creating a new group endpoint.

The user type in the userType parameter can be specified as CUSTOMER or EMPLOYEE. For the purposes of this tutorial, set the userType parameter as EMPLOYEE.

To test the endpoint, open the API reference or check the example of a curl request.

API Reference

Assign users to an employee group

By assigning a user to a particular employee group, you grant them a specific access control level. Create assignments by calling the Adding a user to a group endpoint.

The user type in the userType parameter can be specified as customer or employee. For the purposes of this tutorial, set the userType parameter as employee.

To test the endpoint, open the API reference or check the example of a curl request.

API Reference

How to manage custom scopes

In addition to the standard authorization model, the IAM Service also supports tenant-specific custom scopes, allowing you to extend access control beyond the default capabilities. Custom access controls can be created as collections of scopes and assigned to groups representing employees, customers, or technical users.

The access controls described earlier in Retrieve a list of available access controls are the predefined, platform-managed access controls shipped by Emporix. Those built-in access controls can be listed and assigned, but tenants cannot create or modify them. This section covers a different capability: tenant-specific custom access controls created through the custom-scope APIs. These custom access controls are collections of scopes and can be assigned to groups representing employees or customers.

When a group is linked to one of these tenant-defined custom access controls, its users automatically inherit both the platform’s default scopes and any tenant-specific scopes included in that custom access control.

Typical flow:

  1. Create or update a custom scope in IAM.

  2. Create or update a tenant-specific custom access control that resolves to this scope.

  3. Assign the custom access control to a user group.

  4. Assign users to the group and request OAuth2 tokens.

  5. Verify the assigned controls and scopes.

1

Create or update a custom scope

To create or update a custom scope, call the Upserting a custom scope endpoint.

2

Create or update an access control that uses custom scopes

Access controls map roles and resources to resolved scopes and are assigned to groups. To create or update an access control, call the Upserting an access control endpoint.

3

Assign access controls through groups

To assign access controls, call the Creating a new group endpoint and include your access control IDs in the payload.

Then call the Adding a user to a group endpoint.

4

Verify resolved scopes for a user

To validate IAM configuration, call the Retrieving all scopes granted to a user endpoint.

To test the endpoint, open the API reference or check the example of a curl request.

API Reference

Custom scopes for custom entities

When you create a custom entity for a tenant, Emporix automatically generates a standard set of custom scopes for this entity. This ensures consistency across APIs and reduces the effort required to design and maintain permission models.

For each custom entity, the platform creates a predefined set of scopes following the reserved naming pattern custom.{lowerCaseType}_{action}:

  • custom.{lowerCaseType}_read

  • custom.{lowerCaseType}_manage

  • custom.{lowerCaseType}_read_own

  • custom.{lowerCaseType}_manage_own

For example, for a Document custom entity, the generated scopes include custom.document_read, custom.document_manage, custom.document_read_own, and custom.document_manage_own.

These scopes are immediately available for use in IAM and can be included in your custom access controls. They are also exposed through OAuth2.

  • For a related Schema Service configuration, see the Schema Service tutorial.

  • For the end-to-end integration flow across IAM and Schema, see Custom scopes in the Tokens and Scopes guide.

PreviousIAM Service
NextAPI Reference

Last updated

Was this helpful?