User Data Management via SCIM 2.0 and the Application Repository Service

The Application Repository is a data store to which only DirX Access can write. Any changes made by other entities might lead to an indeterministic behavior of the whole system. The Application Repository was originally intended only for policy and configuration data. However, with the rise of importance of user-specific data for DirX Access, the use of this repository has been extended.

The following figure shows data types managed by AppRepoService and their content. Each user (AppRepoEntity) can contain multiple records of other data types, which extends the capabilities of DirX Access, namely when it comes to the descendants of AppRepoAuthnMethod type. In the past, all the parameters contained in these types could be configured only once per single user record, which caused the system to be unable to preserve integrity when multiple authentication methods of the same type were configured. The parameters marked with (N_A) are not part of any audit record.

The respective parameters have the following semantics:

Due to the characteristics of the data managed by the AppRepoService, their caching is very limited. Most of the data are requested just once per SSO session and at this time they must be fresh. As they can be managed via multiple DirX Access Server instances in the same cluster, caching them is impractical.

Currently, the only data type that is cached is the AppRepoDomainName. The bound of the domain name to the entity’s unique name is (typically) permanent, therefore once it is cached, we can count on it not being changed.

To enable the AppRepoService caching, switch on the ‘Application Repository cache enabled’ configuration parameter of the Cluster configuration object. The caching takes place in a space-limited cache with least-recently-used eviction algorithm. The memory space is shared with the UserService cache and its size is configured by the ‘User cache initial size (bytes)’ and ‘User cache maximal size (bytes)’ of the Server configuration object. The record expiration time is configured by the ‘Application Repository expiration time (in seconds)’ configuration attribute of the Cluster configuration object.

The records of the groups saved in the application repository are cached by DXA server for performance reasons. Due to this, changes performed at groups are guaranteed to be applicable only after expiration of the period configured by “Application Repository cache expiration time” in the Cluster configuration. This cache in configure in a way that each record will always expire after the expiration time, and the time is not refreshed with each access. This is because the group record loaded in server also includes relations between the groups.

Auditing in AppRepoService reflects the approach used originally in UserService. There are three kinds of audit events produced by AppRepoService:

The Figure 2 shows the issued events together with the use cases in which they can occur.

For storing of the AppRepoService audit events, the AuditEvent class is used with the eventAttributes field filled with data from the data type class diagram that are not marked with (N_A).

The AppRepoEntity eventAttributes also contains the eventAttributes of all correlated AppRepoData. These are keyed according to the following scheme:

apprepo:entity:[apprepo_resource_id]:[audited_data_original_key]

where [apprepo_resource_id] is equal to the value of apprepo:resource:id of corresponding AppRepoData, and [audited_data_original_key] is the key used by the AppRepoData when standalone.

These are the most common use cases for which the SCIM 2.0 interface of DirX Access might be used:

The SCIM 2.0 endpoint can be found at the DirX Access Services Container, hence, it is protected by the DirX Access PEP. By default, the PEP provides all access rights to the administrators’ roles and prevents access to any other user.

Starting with version 9.1, DirX Access allows storing groups and users along with their roles in the DXA application-repository (as opposed to User Repository not managed by DXA). This feature necessary in deployments without dedicated user repository. The management of groups and their members can be performed through the SCIM 2.0 API. To support this functionality, DirX Access provides extended SCIM endpoints for Groups and Users. By default, the /Groups endpoint and administration of users through the /Users endpoint is disabled and must be enabled in “SCIM application” configuration.

Through the SCIM API it is possible to :

A detailed guide with examples on how to interact with these endpoints is available at: Users and Groups SCIM 2.0 endpoints .

Generally, the names of the groups and roles stored in the application-repository should be unique within the scope of given application-repository (as the groups are identified by their name CN). How the groups are imprinted into the request injections or JWT can be changed using the "`Group format`" configuration.

The records of the groups saved in the application repository are cached by DXA server for performance reasons. Due to this, changes performed at groups are guaranteed to be applicable only after expiration of the period configured by “Application Repository cache expiration time” in the Cluster configuration.

To enable the server to store groups in application repository and to process the membership from those groups for users, some configuration must be done.

First in the SCIM application configuration (Configuration → REST services → SCIM) you should check the option Enable SCIM endpoints (application-repository groups and roles) that enables the new /Groups SCIM endpoint and also the option to create and modify users in application-repository through the SCIM API. When disabled, the server will not permit management of groups and users trough SCIM API. Administrators should themselves define needed politics to protect these endpoints when enabling them.

This is done in Configuration → Servers → Cluster → Application repository service. The options described bellow all affect the inner behavior connected to the Groups and Roles of the users stored in the Application Repository.

When the option to use Groups and Roles from the Application Repository is enabled, these groups and roles will be utilized during any group or role resolution within the server. For instance, if a Request Injection is configured to imprint group assignments using the User Service as a source, the group membership will now also be retrieved from the Groups in the Application Repository.

Roles can be employed similarly, or they can be used to assign roles to users for use in Role-Based Access Control (RBAC) authorization.

DirX Access enables sourcing of groups for authenticated sessions from three different directions:

It is up to the administrator to declare domain relationships between these sources, and by this enable for example recursive resolution starting in one source leading to another source (if they share a domain).

For example if OAuth tokens created by trusted third party identity provider include groups, the administrator can decide if the third-party groups are related to the groups in the application-repository, and use corresponding OAuth authentication method and Subject Template to declare the same domain and format. Contrary, if the third-party IdP is in no relation to the domain managed by DirX Access, this can be reflected by different configured domains.

User roles assigned within the user or application repository serve as foundational elements in Role-Based Access Control (RBAC) policies. While these roles may not inherently possess a specific domain, administrators have the capability to configure a domain for roles received from a trusted Identity Provider (IdP), thereby distinguishing between various roles effectively. Should there be a preference not to directly align roles in the OAuth token with those defined in policies, administrators can opt to configure the domain and format for these roles. This configuration process can be accomplished through the "`Configuration → Authentication → Methods → OAuth`" interface, where both role format and domain can be precisely specified (note that the domain is shared for both groups and roles).

For cases where all user and group records are to be exported and the number of records in the range of thousands and more, some additional settings in LDAP must be performed as the number of possible search results can be limited by LDAP. This is described in LDAP .

Domain names are one of the sub-entries of entity in DirX Access. The domain name can be used to link the user with a specified AppRepoEntity in the application repository during the authentication process. This functionality is available when domain name storage in AppRepo is enabled in the Cluster Authentication configuration

The domain name has a format property that specifies its expected structure. The format must match the actual domain name, or authentication may fail. The formatting is described in Name Resolution document.

When domain name storage is enabled, DirX Access automatically creates a domain name identical to the unique name in the application repository after a successful authentication. This is done to ensure that the user can be authenticated with the domain name in the future and that the format used to build the unique name is stored. Therefore, when creating a domain name for a new entity, you should also create a domain name matching the unique name of the entity.

Domain names should be unique across the system. This ensures that a domain name can be searched for without the entity ID, simplifying lookups and authentication.