One Identity Safeguard for Privileged Sessions 5.7.0 - REST API Reference Guide

Credential stores

Credential Stores offer a way to store user credentials (for example, passwords, private keys, certificates) and use them to login to the target server, without the user having access to the credentials. That way, the users only have to perform gateway authentication on Safeguard for Privileged Sessions with their usual password (or to an LDAP database), and if the user is allowed to access the target server, Safeguard for Privileged Sessions automatically logs in using the Credential Store.

URL

GET https://<IP-address-of-Safeguard for Privileged Sessions>/api/configuration/policies/credentialstores

Headers

Sample request

The following command lists the credential stores.

curl --cookie cookies https://<IP-address-of-Safeguard for Privileged Sessions>/api/configuration/policies/credentialstores

The following command retrieves the properties of a specific credential store.

curl --cookie cookies https://<IP-address-of-Safeguard for Privileged Sessions>/api/policies/credentialstores/<policy-id>

Response

The following is a sample response received when listing credential stores. For details of the meta object, see Introduction.

{
  "items": [
    {
      "key": "1580973975727acedd51b2",
      "meta": {
        "href": "/api/configuration/policies/credentialstores/1580973975727acedd51b2"
      }
    },
    {
      "key": "935272738572bc2ec1dbdd",
      "meta": {
        "href": "/api/configuration/policies/credentialstores/935272738572bc2ec1dbdd"
      }
    }
  ],
  "meta": {
    "first": "/api/configuration/policies/audit_policies",
    "href": "/api/configuration/policies/credentialstores",
    "last": "/api/configuration/policies/usermapping_policies",
    "next": "/api/configuration/policies/indexing",
    "parent": "/api/configuration/policies",
    "previous": "/api/configuration/policies/content_policies",
    "transaction": "/api/transaction"
  }
}

When retrieving the endpoint of a specific credential store, the response is the following.

{
  "body": {
    "name": "API_LIEBERMANN",
    "type": {
      "authenticator_name": "auth_server_name",
      "default_namespace": "{HOST}",
      "dns_servers": {
        "primary": "192.168.56.1",
        "secondary": "192.168.56.2"
      },
      "domain_mappings": [
        {
          "domain": "domain",
          "host": {
            "selection": "fqdn",
            "value": "host"
          }
        }
      ],
      "login_mode": {
        "password": {
          "key": "e0ecbe98-bd17-4805-ba5d-17fb789f3971",
          "meta": {
            "href": "/api/configuration/passwords/e0ecbe98-bd17-4805-ba5d-17fb789f3971"
          }
        },
        "selection": "fixed",
        "username": "fixed_username"
      },
      "proxy_server": "http://192.168.56.201:9999",
      "selection": "lieberman",
      "server_certificate_check": {
        "enabled": true,
        "trusted_ca": {
          "key": "12269547065727ad6e79d9e",
          "meta": {
            "href": "/api/configuration/policies/trusted_ca_lists/12269547065727ad6e79d9e"
          }
        }
      },
      "web_interface_url": "http://erpm_address"
    }
  },
  "key": "935272738572bc2ec1dbdd",
  "meta": {
    "first": "/api/configuration/policies/credentialstores/1580973975727acedd51b2",
    "href": "/api/configuration/policies/credentialstores/935272738572bc2ec1dbdd",
    "last": "/api/configuration/policies/credentialstores/935272738572bc2ec1dbdd",
    "next": null,
    "parent": "/api/configuration/policies/credentialstores",
    "previous": "/api/configuration/policies/credentialstores/1580973975727acedd51b2",
    "transaction": "/api/transaction"
  }
}

Examples:

Use a Lieberman ERPM server, configure domain mapping and provide the host address as an IP, reuse the gateway login credentials of the user to access the ERPM server, and do not verify the server's certificate.

{
  "name": "API_LIEBERMANN",
  "type": {
    "authenticator_name": "auth_server_name",
    "default_namespace": "{HOST}",
    "dns_servers": {
      "primary": "192.168.56.1",
      "secondary": "192.168.56.2"
    },
    "domain_mappings": [
      {
        "domain": "domain",
        "host": {
          "selection": "ip",
          "value": "192.168.56.1"
        }
      }
    ],
    "login_mode": {
      "selection": "gateway_auth_credentials"
    },
    "proxy_server": "http://192.168.56.201:9999",
    "selection": "lieberman",
    "server_certificate_check": {
      "enabled": false
    },
    "web_interface_url": "https://erpm_address"
  }
}

Change the host address to a hostname for domain mapping, and verify the server's certificate.

{
  "name": "API_LIEBERMANN",
  "type": {
    "authenticator_name": "auth_server_name",
    "default_namespace": "{HOST}",
    "dns_servers": {
      "primary": "192.168.56.1",
      "secondary": "192.168.56.2"
    },
    "domain_mappings": [
      {
        "domain": "domain",
        "host": {
          "selection": "fqdn",
          "value": "host"
        }
      }
    ],
    "login_mode": {
      "selection": "gateway_auth_credentials"
    },
    "proxy_server": "http://192.168.56.201:9999",
    "selection": "lieberman",
    "server_certificate_check": {
      "enabled": true,
      "trusted_ca": {
        "key": "12269547065727ad6e79d9e",
        "meta": {
          "href": "/api/configuration/policies/trusted_ca_lists/12269547065727ad6e79d9e"
        }
      }
    },
    "web_interface_url": "https://erpm_address"
  }
}

Use a fixed username to access the Lieberman ERPM server.

{
  "name": "API_LIEBERMANN",
  "type": {
    "authenticator_name": "auth_server_name",
    "default_namespace": "{HOST}",
    "dns_servers": {
      "primary": "192.168.56.1",
      "secondary": "192.168.56.2"
    },
    "domain_mappings": [
      {
        "domain": "domain",
        "host": {
          "selection": "fqdn",
          "value": "host"
        }
      }
    ],
    "login_mode": {
      "password": {
        "key": "e0ecbe98-bd17-4805-ba5d-17fb789f3971",
        "meta": {
          "href": "/api/configuration/passwords/e0ecbe98-bd17-4805-ba5d-17fb789f3971"
        }
      },
      "selection": "fixed",
      "username": "fixed_username"
    },
    "proxy_server": "http://192.168.56.201:9999",
    "selection": "lieberman",
    "server_certificate_check": {
      "enabled": true,
      "trusted_ca": {
        "key": "12269547065727ad6e79d9e",
        "meta": {
          "href": "/api/configuration/policies/trusted_ca_lists/12269547065727ad6e79d9e"
        }
      }
    },
    "web_interface_url": "http://erpm_address"
  }
}

Use a credential store plugin.

{
  "name": "API_PLUGIN",
  "type": {
    "plugin": {
      "key": "2534221015734bb18aaf32",
      "meta": {
        "href": "/api/configuration/plugins/credentialstore/2534221015734bb18aaf32"
      }
    },
    "selection": "external_plugin"
  }
}

Status and error codes

The following table lists the typical status and error codes for this request. For a complete list of error codes, see Using the Safeguard for Privileged Sessions REST API.

Ticketing policies

Safeguard for Privileged Sessions provides a plugin framework to integrate Safeguard for Privileged Sessions to external ticketing (or issue tracking) systems, allowing you to request a ticket ID from the user before authenticating on the target server. That way, Safeguard for Privileged Sessions can verify that the user has a valid reason to access the server — and optionally terminate the connection if he does not. Requesting a ticket ID currently supports the following protocols:

• Remote Desktop (RDP)

• Secure Shell (SSH)

• TELNET

• TN3270

To request a plugin that interoperates with your ticketing system, contact the One Identity Support Team.

You can upload ticketing plugins using the web interface of Safeguard for Privileged Sessions. The API allows you to reference existing (uploaded) ticketing plugins, change the message prompts, and configure the validation of the provided ticket number.

URL

GET https://<IP-address-of-Safeguard for Privileged Sessions>/api/configuration/policies/ticketing_policies

Headers

Sample request

The following command lists ticketing policies.

curl --cookie cookies https://<IP-address-of-Safeguard for Privileged Sessions>/api/configuration/policies/ticketing_policies

The following command retrieves the properties of a specific ticketing policy.

curl --cookie cookies https://<IP-address-of-Safeguard for Privileged Sessions>/api/configuration/policies/ticketing_policies/<policy-id>

Response

The following is a sample response received when listing ticketing policies. For details of the meta object, see Introduction.

{
  "items": [
    {
      "key": "9816939765734be5978af1",
      "meta": {
        "href": "/api/configuration/policies/ticketing_policies/9816939765734be5978af1"
      }
    }
  ],
  "meta": {
    "first": "/api/configuration/policies/audit_policies",
    "href": "/api/configuration/policies/ticketing_policies",
    "last": "/api/configuration/policies/usermapping_policies",
    "next": "/api/configuration/policies/time_policies",
    "parent": "/api/configuration/policies",
    "previous": "/api/configuration/policies/signing_cas",
    "transaction": "/api/transaction"
  }
}

When retrieving the endpoint of a specific ticketing policy, the response is the following.

{
  "body": {
    "name": "API_ticketing_plugin",
    "plugin": {
      "key": "21425174515734bb223d197",
      "meta": {
        "href": "/api/configuration/plugins/ticketing/21425174515734bb223d197"
      }
    },
    "prompt": "Please enter ticket ID: ",
    "require_valid_ticket": true
  },
  "key": "9816939765734be5978af1",
  "meta": {
    "first": "/api/configuration/policies/ticketing_policies/9816939765734be5978af1",
    "href": "/api/configuration/policies/ticketing_policies/9816939765734be5978af1",
    "last": "/api/configuration/policies/ticketing_policies/9816939765734be5978af1",
    "next": null,
    "parent": "/api/configuration/policies/ticketing_policies",
    "previous": null,
    "transaction": "/api/transaction"
  }
}

Add a ticketing policy

To add a ticketing policy, you have to:

1. Open a transaction.

   For details, see Open a transaction.

2. Upload a plug-in to use

   For details, see To upload or update a plugin, complete the following steps. Note that currently you cannot delete a plugin, only update it by uploading a new version.. You can find the list of uploaded plug-ins at the /api/configuration/plugins/ticketing/ endpoint.

3. Create the JSON object for the new ticketing policy.

   Use the ticketing plugin's key as the value of the plugin element. You can find a detailed description of the available parameters listed in Ticketing policies.

   POST the JSON object to the https://<IP-address-of-Safeguard for Privileged Sessions>/api/configuration/policies/ticketing_policies endpoint. If the POST request is successful, the response includes the key of the new ticketing policy. For example:

   {
     "key": "aa423b72-0d0f-4275-be30-494e9a99ffad",
     "meta": {
       "href": "/api/configuration/policies/ticketing_policies/aa423b72-0d0f-4275-be30-494e9a99ffad",
       "parent": "/api/configuration/policies/ticketing_policies",
       "transaction": "/api/transaction"
     }
   }

4. Commit your changes.

   For details, see Commit a transaction.

Modify a ticketing policy

To modify a ticketing policy, you have to:

1. Open a transaction.

   For details, see Open a transaction.

2. Find the plugin you want to modify

   You can find the list of available plugins at the /api/configuration/plugins/ticketing/ endpoint.

3. Modify the JSON object of the ticketing policy.

   Use the ticketing plugin's key as the value of the plugin element. You can find a detailed description of the available parameters listed in Ticketing policies.

   PUT the modified JSON object to the https://<IP-address-of-Safeguard for Privileged Sessions>/api/configuration/policies/ticketing_policies/<key-of-the-object> endpoint.

4. Commit your changes.

   For details, see Commit a transaction.

Status and error codes

The following table lists the typical status and error codes for this request. For a complete list of error codes, see Using the Safeguard for Privileged Sessions REST API.

Ticketing plugins

The ticketing plugins used on Safeguard for Privileged Sessions. To upload or update a plugin, see To upload or update a plugin, complete the following steps. Note that currently you cannot delete a plugin, only update it by uploading a new version..

URL

GET https://<IP-address-of-Safeguard for Privileged Sessions>/api/configuration/plugins/ticketing

Headers

Sample request

The following command lists the ticketing plugins stored on Safeguard for Privileged Sessions..

curl --cookie cookies https://<IP-address-of-Safeguard for Privileged Sessions>/api/configuration/plugins/ticketing

The following command retrieves the properties of a specific plugin.

curl --cookie cookies https://<IP-address-of-Safeguard for Privileged Sessions>/api/configuration/plugins/ticketing/<plugin-id>

Response

The following is a sample response received when listing ticketing plugins stored on Safeguard for Privileged Sessions. For details of the meta object, see Introduction.

{
  "items": [
    {
      "key": "21425174515734bb223d197",
      "meta": {
        "href": "/api/configuration/plugins/ticketing/21425174515734bb223d197"
      }
    }
  ],
  "meta": {
    "first": "/api/configuration/plugins/aa",
    "href": "/api/configuration/plugins/ticketing",
    "last": "/api/configuration/plugins/ticketing",
    "next": null,
    "parent": "/api/configuration/plugins",
    "previous": "/api/configuration/plugins/credentialstore",
    "transaction": "/api/transaction"
  }
}

When retrieving the endpoint of a specific plugin, the response is the following.

{
  "body": {
    "api": "1.0",
    "description": "Demo ticketing plugin for demonstration purposes",
    "name": "DemoTicketingPlugin",
    "path": "/opt/scb/var/plugins/ticketing/DemoTicketingPlugin",
    "version": "0.0"
  },
  "key": "21425174515734bb223d197",
  "meta": {
    "first": "/api/configuration/plugins/ticketing/21425174515734bb223d197",
    "href": "/api/configuration/plugins/ticketing/21425174515734bb223d197",
    "last": "/api/configuration/plugins/ticketing/21425174515734bb223d197",
    "next": null,
    "parent": "/api/configuration/plugins/ticketing",
    "previous": null,
    "transaction": "/api/transaction"
  }
}

Status and error codes

The following table lists the typical status and error codes for this request. For a complete list of error codes, see Using the Safeguard for Privileged Sessions REST API.

Completing the Welcome Wizard using REST