Domain management

Use the Axiomatics Services Manager to manage authorization domain configurations to an Authorization Service.

Access the Domain Management page by clicking the Domain Management link in the navigation control bar.

This page displays the most recently viewed or edited domains on the left, and a list with all available domains along with a search function in the main area.

On this page, you can perform the following actions:

• Hover the mouse pointer over the recently visited domains or a row in the list to reveal a line of buttons: Copy, Roll back, Export, and Delete. By clicking one of these buttons, you can directly initiate that action for the selected domain.

• Click a row in the domains list to display the domain page, where you can view and edit the configuration of that domain.

• Click the Create new Domain button on the right to create a new domain. See Create a domain for a description of the authorization domain content.

• Use the search field to look up domains by name and narrow down the domains listed.

  note

  This is a dynamic search field and returns relevant results as you type.

Create a domain

1. Go to the Domain Management page.

2. Click the Create new Domain button on the right of the page.

   

   The Create new Domain page displays where you can specify the domain configuration.

3. Enter and/or select the required information as described in the following sections.

4. Finally, click the Create button in the lower right corner of the page to finish.

Name and description

1. In the Name field, enter a name for the new domain. The name is used to refer to the domain within the Axiomatics Services Manager GUI.

   Important

   The length of a domain name is limited to 500 characters.

2. Optionally, provide more details about the domain in the Description field.

Policy Package

A Policy Package is a data structure that contains XACML policies and/or policy sets that can be assigned to a domain. A policy package is a required component of the domain.

Any software tool, including plain text editors, with which you can produce XACML 3.0 compliant policies can be used to create policy packages.

There are three tools provided by Axiomatics that you can use to create policies: the Policy Editor within ASM, the Policy Administration Point (PAP), and the Axiomatics Language for Authorization (ALFA) plugin and compiler.

Policies created in the Policy Editor are automatically added to the library. Policies created with external tools must be imported to the library to become available for selection. See Import a Policy Package for more information.

note

If changes are made to a policy package in the Policy Editor, these changes are not automatically transferred to the domain. To update the policies in the domain, select the policy package again to reload it with the latest version.

1. Click the Add new button under the Policy Package heading.

   A dialog box is displayed with a list of available policies in the Policy Package Library. The list is searchable.

2. Use the search field to find a specific policy package or go through the list.

   note

   This is a dynamic search field and returns relevant results as you type.

3. Click a policy package in the list to select it.

4. Click Save to add it to the domain.

   note

   The simplest possible domain configuration requires only a Policy Package. The absence of Attribute Connectors implies that all attribute references in the Policy Package are provided by the Policy Enforcement Point (PEP).

Attribute Connectors

A domain can be configured with zero or more attribute connectors. An attribute connector is required when attributes used in a policy need to get their values from an external source such as a database or an LDAP directory. A source of such data is called a Policy Information Point (PIP). The authorization engine connects to a PIP through an attribute connector.

The attribute connector contains information about the type of attribute source (for example, LDAP, or SQL), the XACML attributes it provides, and how to obtain them (query strings specific to the PIP type and instance). The attribute connectors themselves are then used at runtime during policy evaluation.

See the Attribute Connector Management topic for more information about attribute connectors.

1. Click the the Add new button under the Attribute Connectors heading.

   A dialog box is displayed with a list of the available attribute connectors. The list is searchable.

2. Use the search field to find a specific attribute connector or go through the list.

   note

   This is a dynamic search field and returns relevant results as you type.

3. Click an attribute connector in the list to select it.

   More than one attribute connector can be selected. Click again on a selected item to deselect it.

4. Click Save to add the selected attribute connector(s) to the domain.

   Each attribute connector is represented in the panel. Scroll the list of attribute connectors if necessary.

   note

   If changes are made to an attribute connector configuration in the Attribute Connectors section, these changes are not automatically transferred to the domain. To update the attribute connector in the domain, select it again to reload it with the latest configuration.

Decision parameters

This optional property controls how the authorization engine should attempt to perform multiple-request optimization. In some cases this can improve the performance of authorization engine. In some special cases it may have a negative impact on performance. The actual improvement depends on several factors, for example, the structure of the request and the structure of the policy.

Enabling this property means that the authorization engine will attempt to perform multiple-request optimization.

The threshold value indicates how many individual requests a multiple-decision request should contain before the authorization engine attempts to optimize that specific multiple request.

This setting is enabled by entering a value in the Partial Evaluation Threshold field in the Decision parameters block. You can enter a value directly or click the plus or minus buttons to set a value.

If enabled, two requirements apply:

• the value must be an integer
• the value must be between 2 and 9999 (0 and 1 are not allowed)

If the threshold value is set too low, it may reduce performance. If the threshold value is set too high, it is less likely that it will be reached. The correct number cannot be determined without testing.

Edit a domain

To view and/or edit a domain, go to the main Domain Management page and click a row in the list of domains.

The domain page displays, where you can edit the information, and change the selected policy package and/or attribute connectors.

Change or delete the policy package

A policy package is required for a valid domain configuration.

To change the policy package:

1. Click the Pen icon to open the list of available policy packages.
2. Use the search field to find a specific policy package or go through the list.
3. Click a policy package in the list to select it.
4. Click Save.

To delete the policy package:

1. Click the - icon to remove the policy package from the domain configuration.

note

If changes are made to a policy package in the Policy Editor, these changes are not automatically transferred to the domain. To update the policies in the domain, select the policy package again to reload it with the latest version.

Change or add attribute connectors

• To add an attribute connector to the domain configuration, click the the Add new button under the Attribute Connectors heading.

• To view information about the attribute connector, click the eye icon.

• To remove an attribute connector, click the - icon for an attribute connector to remove it.

note

If changes are made to an attribute connector configuration in the Attribute Connectors section, these changes are not automatically transferred to the domain. To update the attribute connector in the domain, select it again to reload it with the latest configuration.

Save an updated domain

If you have updated any part of the domain configuration, you need to save the domain for the changes to take effect.

• Click the Save domain button to save the edited domain configuration and return to the main Domain Management page.

• Alternatively, click the Cancel button to abort all changes and end the editing session. This will also return you to the main Domain Management page.

Export a domain

Export the domain content as a YAML-format file as follows:

1. There are two ways to initiate the export operation:

   • From the main Domain Management page, click the Export button in the row of buttons that appear when you hover the mouse pointer over a recently visited domain or a row in the list of domains.

   • From a domain page, click the Export button in the tool bar in the upper right part of the domain page.

2. A standard file system dialog displays.
3. Navigate to the directory you want to save the domain file
4. Click Save.

Delete a domain

1. There are two ways to delete a domain:

   • From the main Domain Management page, click the Delete button in the row of buttons that appear when you hover the mouse pointer over a recently visited domain or a row in the list of domains.

   • From a domain page, click the Delete button in the tool bar in the upper right part of the domain page.

2. A confirmation dialog box displays.
3. Confirm that you want to go ahead with the deletion or click Cancel to abort the operation.

note

What is being deleted here is the mapping, or association, of the domain name to the project, not the actual domain. The domain itself cannot be deleted, and the domain ID remains unchanged for audit and forensic purposes.

Copy a domain

You have the option to copy the content of one domain to another, which can be useful when developing authorization domains.

There are two ways to initiate the copy operation:

• From the main Domain Management page, click the Copy button in the row of buttons that appear when you hover the mouse pointer over a recently visited domain or a row in the list of domains.
• From a domain page, click the Copy button in the tool bar in the right corner of the domain page.

The Copy page displays, showing the selected (or source) domain in the left panel. Click the maximize button to expand the view of the domain information. Click minimize to return.

Copying can be performed in two different ways:

• Copy and Replace - A source domain is selected and copied to a target domain, thereby replacing the existing contents of the target domain.

• Copy and Create - A source domain is selected, a new name is entered, and the new domain is created as part of the Copy operation.

note

Except for the name, the source domain is copied over to the target domain in its entirety. It is not possible to copy only subsets of domain content.

The selected copy method controls which options are available in the operation.

Copy and Replace

1. Click the Copy and Replace button to select copy method.

2. Select a target domain in in the Choose domain drop-down menu.

   The panel on the right now displays the selected target domain, the contents of which will be replaced by the contents of the domain shown in the left panel.

   The configuration is not editable in this view, but you can click the Eye icon to view information about the attribute connector(s) assigned to the domain.

3. Click the Copy and Replace button to execute the operation, or Cancel to abort.

Copy and Create

1. Click the Copy and Create button to select copy method.

2. Enter a name for the new domain in the text field.

3. Click the Submit button.

   The panel on the right now displays the new domain configuration and the new domain name.

   The configuration is not editable in this view, but you can click the Eye icon to view information about the attribute connector(s) assigned to the domain.

4. Click the Copy and Create button to execute the operation, or Cancel to abort.

Roll back a domain

This operation is used to revert to an older version of a domain, for example, when a revision to a domain does not go as planned.

note

The Roll back functionality is only supported for ASM users that have the domain-auditor role assigned to them. Read the Map user roles section for more information.

This is done by selecting a historical version of the domain to go back to, based on time and domain ID, and that will restore the domain to its previous state represented by the domain ID.

There are two ways to initiate the roll back operation:

• From the main Domain Management page, click the Roll back button in the row of buttons that appear when you hover the mouse pointer over a recently visited domain or a row in the list of domains.
• From a domain page, click the Roll back button in the tool bar in the upper right corner of the domain area.

The Roll back page displays.

The current version of the domain displays in the left panel. Click the maximize button to expand the view of the domain information. Click minimize to return.

1. Click Select previous version.

   A list of previous versions displays.

2. Select the previous version that you want to roll back to .

   All the historical instances of this domain are listed together with domain IDs and a time stamp showing when it was in use.

   The panel on the right now displays the selected version of the domain, where you can review it. The configuration is not editable in this view, but you can click the Eye icon to view information about the attribute connector(s) assigned to the domain.

3. Click Roll Back to execute the operation or Cancel to abort.

Domain management API

It is possible to manage domains by calling the endpoints directly as an alternative to using the UI. The project functionality of ASM is implemented in the API via the use of namespaces. The endpoint addresses are provided for reference in the following table.

This domain management API is also supported by the standalone component Authorization Domain Manager (ADM).

Endpoint addresses for operations

This is the interface by which the client contacts the domain manager (that is, the internal functionality of ADM) for operations. The domain manager provides a REST API for HTTPS or HTTP.

The following endpoints can be used:

Operation	Method	URI	Description
Retrieve domain by id	GET	/api/domains/<domain_id>	A method of retrieval primarily used for auditing. Requires the user role domain-auditor.
Retrieve domain by name	GET	/api/namespaces/<namespace>/names/<domain_name>/domain	This is the primary method of retrieval. It retrieves a specific domain within a namespace.
Retrieve domain names	GET	/api/namespaces/<namespace>/names	This operation returns a list of the domain names that belong to the same namespace.
Retrieve domain name history	GET	/api/namespaces/<namespace>/names/<domain_name>/history	This operation returns an array of the historical changes of this domain name in the form of pairs of dates and domain IDs sorted by time.
Roll back a domain name change	POST	/api/namespaces/<namespace>/names/<domain_name>/rollback/<domain_id>	This operation points the domain name to the domain ID in the argument, thereby restoring it to a previous state.
Store domain	POST	/api/namespaces/<namespace>/names/<domain_name>	Once stored the domain is always retrievable. Domains cannot be deleted. If the domain of a namespace is deleted or overwritten it is still retrievable by the domain identifier.
Delete name	DELETE	/api/namespaces/<namespace>/names/<domain_name>	This deletes only the mapping of the name from the namespace.
Delete namespace	DELETE	/api/namespaces/<namespace>/	This deletes a namespace along with its domain members and its history.
Copy name	PUT	/api/namespaces/<namespace>/names/<sourceName>/copy/<destinationName>	Copy the contents of a domain to another domain in the same namespace.

Important

The length of a <namespace> is limited to 500 characters, as is the length of a <domain_name>.

Swagger UI

The API is also documented using Swagger UI. More information for each operation is available via:

https://<host:applicationConnectorsPort>/swagger-ui/