Config REST Web Service

The Config REST Web Service is the official DirX Access interface that provides the management capabilities for the configuration and policy objects.

Description

The Config RESTful Web Service is described by the OpenAPI 3.0 document which can be found at {config_rest_web_application_location}/openapi.json
or {config_rest_web_application_location}/openapi.yaml.

Public OpenAPI tools are able to autogenerate documentation and clients for given document. The readers are recommended to use such tools (e.g., Swagger , or OpenAPI.Tools - an Open Source list of great tools for OpenAPI), mainly, for the generation of documentation file in a user-friendly format.

Deployment

The Config REST Web Service functionality is provided based on the Config REST web application. The application has to have its configuration and be deployed on the DirX Access Server. Multiple Config REST applications can coexist on DirX Access Server, therefore configuration includes PortAssignment and context path.

The {config_rest_web_application_location} of the Config REST web application is constructed from the hostname of the DirX Access Server or Cluster, the port of the assigned PortAssignment configuration object and the web application context path.

The deployment can be done via Direct Application of System Actions and Configuration or SysActions REST Web Service.

Authorization

Considering the capabilities of the Config REST Web Service, the interface should be protected and at least as secure as DirX Access Manager. The DirX Access Manager requires the interface to be deployed and running.

Each request can be processed according to the DirX Access internal authorization which means the granularity of decisioning can be performed at the attribute level. The internal authorization has to enabled on the PEP that handles the authentication. For more information please see one of:

Size limitations when reading configuration objects

When listing a type of configuration object, for types that have large number of nodes in LDAP a search size limit can be encountered. This is described in: LDAP - Large search results limitations.

Large property truncation in responses

Certain configuration object properties (such as metadata in SAML metadata objects) can hold very large values. To keep responses compact when listing or reading configuration objects, the Config REST Web Service may omit properties whose values exceed a configured size threshold.

When a property is omitted, the response metadata (meta) section includes an omittedLargeProperties map. Each entry in the map has the property name as the key and a URL as the value, from which the full property value can be retrieved individually.

Example response with omitted large properties

{
    "meta": {
        "omittedLargeProperties": [
            {
                "key": "metadata",
                "value": "{config_rest_web_application_location}/SamlMetadatas('My Metadata')/metadata"
            }
        ]
    },
    "key": "My Metadata",
    "dp": "net.atos.dirx.access.apprepo.api.config.client.web.saml.SamlMetadata",
    "url": "https://idp.example.com/saml/metadata"
}

In this example, the metadata property was too large to include inline. The client can retrieve the full value by performing a GET request to the URL provided in omittedLargeProperties.

The omittedLargeProperties field is read-only and only appears in responses. It is not part of the configuration object itself and cannot be set via POST, PUT, or PATCH requests.

Examples

Reading the Cluster configuration object

Request

GET {config_rest_web_application_location}/Cluster

Reading the SubjectTemplate configuration object

Request

GET {config_rest_web_application_location}/SubjectTemplate

Reading Server configuration objects

Request

GET {config_rest_web_application_location}/Servers?$count=true

Reading the “DirX Access Server” Server configuration object

Request

GET {config_rest_web_application_location}/Servers('DirX Access Server')

Reading SamlMetadata configuration objects

Request

GET {config_rest_web_application_location}/SamlMetadatas?$count=true

Reading the “Metadata” SamlMetadata configuration object

Request

GET {config_rest_web_application_location}/SamlMetadatas('Metadata')

Create the “Metadata“ SamlMetadata configuration object

Request

POST {config_rest_web_application_location}/SamlMetadatas
{
    "dp": "net.atos.dirx.access.apprepo.api.config.client.web.saml.SamlMetadata",
    "key": "Metadata",
    "metadata": "{metadata_xml_string}"
}

Replace the “Metadata“ SamlMetadata configuration object

Request

PUT {config_rest_web_application_location}/SamlMetadatas('Metadata')
{
    "dp": "net.atos.dirx.access.apprepo.api.config.client.web.saml.SamlMetadata",
    "key": "Metadata",
    "metadata": "{metadata_xml_string}"
}

Modify the “Metadata“ SamlMetadata configuration object

Request

PATCH {config_rest_web_application_location}/SamlMetadatas('Metadata')
{
    "description": "Description of the metadata"
}

Remove the “Metadata“ SamlMetadata configuration object

Request

DELETE {config_rest_web_application_location}/SamlMetadatas('Metadata')

Implementation Details

The Config RESTful Web Service is implemented according to the OData4 protocol. For the clients that are built according to the OData4 standard, the metadata document can be found at config_web_application_location/$metadata.