SysActions REST Web Service

The SysActions REST Web Service is the official DirX Access interface that provides the following capabilities:

  • Deployment of DirX Access components

    • PEPs

    • WebApplications

      • SOAP Web Services

      • REST Web Services

      • Authentication Applications

      • SAML endpoints

      • WS-Federation endpoint

      • OAuth endpoints

    • DirX Access Bridge

  • Keystore’s generation and import

Description

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

Public OpenAPI tools can autogenerate documentation and clients for a 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 files in a user-friendly format.

Deployment

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

The {sysactions_rest_web_application_location} of the SysActions REST web application is constructed from the hostname of the DirX Access Server, 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 SysActions 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.

Examples

Deployment of a Web Application (FILESYSTEM)

Request

POST {sysactions_rest_web_application_location}/Action
{
    "action": {
        "@odata.type": "#net.atos.dirx.access.sysactions.api.action.deployment.webapplication.WebApplicationDeploymentSysAction",
        "type": "FILESYSTEM",
        "key": "{web_application_id}"
    }
}

The FILESYSTEM value of the type parameter denotes that the {web_application_id} web application is deployed locally on the DirX Access Server where the request has been sent.

For more information regarding request parameters, please see the OpenAPI 3.0 document.

Response

{
    "@odata.context": "https://my-server.my-company.example:10115/odata4/sysactions/1_0_0/$metadata#Collection(net.atos.dirx.access.sysactions.api.action.SysActionResponse)",
    "@odata.type": "#net.atos.dirx.access.sysactions.api.action.deployment.DeploymentSysActionResponse",
    "fileSystemTargets": [
        {web_application_targets_updated}
    ],
    "fileEncoding": "UTF-8",
    "file": "{web_application_archive_base64_string}",
    "fileType": "ZIP"
}

For more information regarding response parameters, please see the OpenAPI 3.0 document.

Deployment of a Web Application (ARCHIVE)

Request

POST {sysactions_rest_web_application_location}/Action
{
    "action": {
        "@odata.type": "#net.atos.dirx.access.sysactions.api.action.deployment.webapplication.WebApplicationDeploymentSysAction",
        "target": "C:/Users/Administrator/Desktop",
        "type": "ARCHIVE",
        "key": "{web_application_id}"
    }
}

The ARCHIVE value of the type parameter denotes that all artifacts of the {web_application_id} web application is deployed to the archive.

The target parameter denotes the optional local location of the archive.

Response

{
    "@odata.context": "https://my-server.my-company.example:10115/odata4/sysactions/1_0_0/$metadata#Collection(net.atos.dirx.access.sysactions.api.action.SysActionResponse)",
    "@odata.type": "#net.atos.dirx.access.sysactions.api.action.deployment.DeploymentSysActionResponse",
    "fileSystemTargets": [
        "C:\\Users\\Administrator\\Desktop\\dirx.access.webapp.{web_application}.zip"
    ],
    "file": "{web_application_archive_base64_string}",
    "fileType": "ZIP",
    "fileEncoding": "UTF-8"
}

Deployment of a PEP (ARCHIVE)

Request

POST {sysactions_rest_web_application_location}/Action
{
    "action": {
        "@odata.type": "#net.atos.dirx.access.sysactions.api.action.deployment.pep.ServletFilterPepDeploymentSysAction",
        "target": "C:/Users/Administrator/Desktop",
        "type": "ARCHIVE",
        "clientId": "{pep_id}",
        "issuerOfClientKeystore": {
            "keystoreId": {
                "key": "{ca_keystore_id}",
                "type": "net.atos.dirx.access.apprepo.api.config.keymanagement.Keystore"
            },
            "keystorePassword": "{ca_keystore_password}",
            "keyPairAlias": "{ca_keystore_signing_key_alias}"
        },
        "version": "SERVLET_API_5",
        "webAppName": "servlet_filter5.war"
    }
}

The issuerOfClientKeystore parameter represents the selection of the key for creation of the cryptomaterial for secure communication of the PEP.

Response

{
    "@odata.context": "https://my-server.my-company.example:10115/odata4/sysactions/1_0_0/$metadata#Collection(net.atos.dirx.access.sysactions.api.action.SysActionResponse)",
    "@odata.type": "#net.atos.dirx.access.sysactions.api.action.deployment.DeploymentSysActionResponse",
    "fileType": "ZIP",
    "fileSystemTargets": [
        "C:\\Users\\Administrator\\Desktop\\dirx.access.pep.{pep}.zip"
    ],
    "fileEncoding": "UTF-8",
    "file": "{pep_archive_base64_string}"
}

Deployment of a DirX Access Bridge

Request

POST {sysactions_rest_web_application_location}/Action
{
    "action": {
        "@odata.type": "#net.atos.dirx.access.sysactions.api.action.deployment.bridge.BridgeDeploymentSysAction",
        "serverId": "{server_id}",
        "target": "C:/Users/Administrator/Desktop"
    }
}

The serverId parameter denotes the respective Port Assignments of the DirX Access Server for which the outbound connectors are created.

Response

{
    "@odata.context": "https://my-server.my-company.example:10115/odata4/sysactions/1_0_0/$metadata#Collection(net.atos.dirx.access.sysactions.api.action.SysActionResponse)",
    "@odata.type": "#net.atos.dirx.access.sysactions.api.action.deployment.DeploymentSysActionResponse",
    "fileType": "ZIP",
    "fileSystemTargets": [
        "c:\\Users\\Administrator\\Desktop\\dirx.access.bridge-9.1.0.zip"
    ],
    "fileEncoding": "UTF-8",
    "file": "{bridge_archive_base64_string}"
}

The archive contains the custom artifacts necessary for the {server_id} DirX Access Server. The archive has to be merged with the {installation_directory}/Services/templates/bridge folder. To create complete DirX Access Bridge, the inbound connectors have to be configured manually.

Import of a Keystore

Request

POST {sysactions_rest_web_application_location}/Action
{
    "action": {
        "@odata.type": "#net.atos.dirx.access.sysactions.api.action.crypto.ImportKeystoreSysAction",
        "key": "{keystore_id}",
        "keystore": "{keystore_base64_string}",
        "password": "{keystore_password}"
    }
}

The keystore denotes the keystore archive. It is the same string as stored in the application repository or coming from the complete export feature of DirX Access application repository in DirX Access Manager.

Response

{
    "@odata.context": "https://my-server.my-company.example:10115/odata4/sysactions/1_0_0/$metadata#Collection(net.atos.dirx.access.sysactions.api.action.SysActionResponse)",
    "@odata.type": "#net.atos.dirx.access.sysactions.api.action.GeneralSysActionResponse",
    "message": "The '{keystore_id}' keystore has been successfully imported."
}

Generation of a Keystore for SSL Context

Request

POST {sysactions_rest_web_application_location}/Action
{
    "action": {
        "@odata.type": "#net.atos.dirx.access.sysactions.api.action.crypto.GenerateKeystoreSysAction",
        "key": "{keystore_id}",
        "password": "{keystore_password}",
        "entries": [
            {
                "type": "KEY_PAIR",
                "alias": "{keystore_key_alias}",
                "from": 0,
                "to": 0,
                "pairedAlias": "{keystore_key_alias}.trusted",
                "subjectDn": "cn=Secure Communication,o={cluster_name}",
                "keyUsage": "101110010",
                "extendedKeyUsage": [
                    "1.3.6.1.5.5.7.3.1"
                ],
                "dnsNames": [
                    "{cluster_hostname}",
                    "{server1_hostname}",
                    "{server2_hostname}"
                ],
                "issuer": {
                    "keystoreId": {
                        "key": "{ca_keystore_id}",
                        "type": "net.atos.dirx.access.apprepo.api.config.keymanagement.Keystore"
                    },
                    "keystorePassword": "{ca_keystore_password}",
                    "keyPairAlias": "{ca_keystore_signing_key_alias}",
                    "pairedAlias": "{ca_keystore_signing_key_alias}.trusted"
                }
            },
            {
                "type": "CERTIFICATE",
                "alias": "{keystore_key_alias}.trusted",
                "from": 0,
                "to": 0
            },
            {
                "type": "CERTIFICATE",
                "alias": "{ca_keystore_signing_key_alias}.trusted",
                "from": 0,
                "to": 0
            }
        ]
    }
}

For more information regarding request parameters, please see the OpenAPI 3.0 document.

Response

{
    "@odata.context": "https://my-server.my-company.example:10115/odata4/sysactions/1_0_0/$metadata#Collection(net.atos.dirx.access.sysactions.api.action.SysActionResponse)",
    "@odata.type": "#net.atos.dirx.access.sysactions.api.action.crypto.KeystoreSysActionResponse",
    "message": "The '{keystore_id}' keystore has been successfully generated."
}

The message parameter denotes that the {keystore_id} keystore has been successfully generated and store in DirX Access application repository.

For more information regarding response parameters, please see the OpenAPI 3.0 document.

Generation of a Keystore for Client Secure Communication

Request

POST {sysactions_rest_web_application_location}/Action
{
    "action": {
        "@odata.type": "#net.atos.dirx.access.sysactions.api.action.crypto.GenerateKeystoreSysAction",
        "key": "{keystore_id}",
        "password": "{keystore_password}",
        "entries": [
            {
                "type": "KEY_PAIR",
                "alias": "{keystore_key_alias}",
                "from": 0,
                "to": 0,
                "pairedAlias": "{keystore_key_alias}.trusted",
                "subjectDn": "cn=Secure Communication,o={cluster_name}",
                "keyUsage": "100000000",
                "issuer": {
                    "keystoreId": {
                        "key": "{ca_keystore_id}",
                        "type": "net.atos.dirx.access.apprepo.api.config.keymanagement.Keystore"
                    },
                    "keystorePassword": "{ca_keystore_password}",
                    "keyPairAlias": "{ca_keystore_signing_key_alias}",
                    "pairedAlias": "{ca_keystore_signing_key_alias}.trusted"
                }
            },
            {
                "type": "CERTIFICATE",
                "alias": "{keystore_key_alias}.trusted",
                "from": 0,
                "to": 0
            },
            {
                "type": "CERTIFICATE",
                "alias": "{ca_keystore_signing_key_alias}.trusted",
                "from": 0,
                "to": 0
            }
        ],
        "type": "ARCHIVE",
        "target": "c:/Users/Administrator/Desktop"
    }
}

The type and target parameters denote that the {keystore_id} keystore will be stored locally.

Response

{
    "@odata.context": "https://my-server.my-company.example:10115/odata4/sysactions/1_0_0/$metadata#Collection(net.atos.dirx.access.sysactions.api.action.SysActionResponse)",
    "@odata.type": "#net.atos.dirx.access.sysactions.api.action.crypto.KeystoreSysActionResponse",
    "message": "The '{keystore_id}' keystore has been successfully generated.",
    "keystorePassword": "{keystore_password}",
    "keystore": "{keystore_archive_base64_string}"
}

Implementation Details

The SysActions 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 sysactions_web_application_location*/$metadata*.