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

Traffic alerts

Configuration options for sending traffic-related alerts.

E-mail alerts, when enabled, are sent to the e-mail address configured in the alerting_address element of the /api/configuration/management/email endoint.

SNMP alerts, when enabled, are sent to the SNMP server configured at the /api/configuration/management/snmp/trap endpoint.

URL

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

Headers

Sample request

The following command lists the configuration options for traffic-related alerts..

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

Response

The following is a sample response received when listing the configuration options for traffic-related alerts. For details of the meta object, see Introduction.

{
  "body": {
    "scbAuthFailure": {
      "email": false,
      "snmp": false
    },
    "scbAuthSuccess": {
      "email": false,
      "snmp": false
    },
    "scbChannelDenied": {
      "email": false,
      "snmp": false
    },
    "scbConnectionDenied": {
      "email": false,
      "snmp": false
    },
    "scbConnectionFailed": {
      "email": false,
      "snmp": false
    },
    "scbConnectionTimedout": {
      "email": false,
      "snmp": false
    },
    "scbCredStoreClosed": {
      "email": false,
      "snmp": false
    },
    "scbCredStoreDecryptError": {
      "email": false,
      "snmp": false
    },
    "scbCredStoreUnlockFailure": {
      "email": false,
      "snmp": false
    },
    "scbGWAuthFailure": {
      "email": false,
      "snmp": false
    },
    "scbGWAuthSuccess": {
      "email": false,
      "snmp": false
    },
    "scbProtocolViolation": {
      "email": false,
      "snmp": false
    },
    "scbRealTimeAlert": {
      "email": false,
      "snmp": false
    },
    "scbSshHostKeyLearned": {
      "email": false,
      "snmp": false
    },
    "scbSshHostKeyMismatch": {
      "email": false,
      "snmp": false
    },
    "scbUserMappingFailure": {
      "email": false,
      "snmp": false
    }
  },
  "key": "traffic_alerts",
  "meta": {
    "first": "/api/configuration/alerting/system_alerts",
    "href": "/api/configuration/alerting/traffic_alerts",
    "last": "/api/configuration/alerting/traffic_alerts",
    "next": null,
    "parent": "/api/configuration/alerting",
    "previous": "/api/configuration/alerting/system_alerts",
    "transaction": "/api/transaction"
  }
}

Modify a traffic-related alert

To enable or disable an alert, you have to:

1. Open a transaction.

   For details, see Open a transaction.

2. Modify the JSON object of the endpoint.

   PUT the modified JSON object to the https://<IP-address-of-Safeguard for Privileged Sessions>/api/configuration/alerting/traffic_alerts endpoint. You can find a detailed description of the available parameters listed in Traffic alerts.

3. 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.

User management and access control

User management and access control

The AAA endpoint contains the configuration endpoints for the authentication, authorization, and account (AAA) settings of the users who access Safeguard for Privileged Sessions.

URL

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

Headers

Sample request

The following command lists the AAA configuration endpoints.

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

Response

The following is a sample response received when listing AAA configuration endpoints. For details of the meta object, see Introduction.

{
  "items": [
    {
      "key": "acls",
      "meta": {
        "href": "/api/configuration/aaa/acls"
      }
    },
    {
      "key": "local_database",
      "meta": {
        "href": "/api/configuration/aaa/local_database"
      }
    },
    {
      "key": "settings",
      "meta": {
        "href": "/api/configuration/aaa/settings"
      }
    }
  ],
  "meta": {
    "first": "/api/configuration/aaa",
    "href": "/api/configuration/aaa",
    "last": "/api/configuration/x509",
    "next": "/api/configuration/alerting",
    "parent": "/api/configuration",
    "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.

Authentication and user database settings

Contains settings for authenticating to Safeguard for Privileged Sessions. You can create a user database locally on Safeguard for Privileged Sessions, or connect to an LDAP server to authenticate users. You can configure authentication with passwords, X.509 certificates, or against a RADIUS server.

URL

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

Headers

Sample request

The following command lists the authentication and user database settings.

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

Response

The following is a sample response received when listing authentication and user database settings. For details of the meta object, see Introduction.

{
  "body": {
    "backend": {
      "cracklib_enabled": false,
      "expiration_days": 0,
      "minimum_password_strength": "good",
      "remember_previous_passwords": 10,
      "selection": "local"
    },
    "method": {
      "selection": "passwd"
    },
    "require_commitlog": false
  },
  "key": "settings",
  "meta": {
    "first": "/api/configuration/aaa/acls",
    "href": "/api/configuration/aaa/settings",
    "last": "/api/configuration/aaa/settings",
    "next": null,
    "parent": "/api/configuration/aaa",
    "previous": "/api/configuration/aaa/local_database",
    "transaction": "/api/transaction"
  }
}

Local user database with password authentication

This example configures a local user database with a password policy to authenticate the users of Safeguard for Privileged Sessions:

{
  "backend": {
    "cracklib_enabled": false,
    "expiration_days": 0,
    "minimum_password_strength": "good",
    "remember_previous_passwords": 10,
    "selection": "local"
  },
  "method": {
    "selection": "passwd"
  },
  "require_commitlog": false
}

Local user database with RADIUS server

This example configures a local user database with a RADIUS server to authenticate the users of Safeguard for Privileged Sessions. Note that the password-related elements have to be disabled, as the RADIUS server determines the password policy.

{
  "backend": {
    "cracklib_enabled": false,
    "expiration_days": 0,
    "minimum_password_strength": "disabled",
    "remember_previous_passwords": 0,
    "selection": "local"
  },
  "method": {
    "selection": "radius",
    "servers": [
      {
        "address": {
          "selection": "ip",
          "value": "<server-ip>"
        },
        "port": <port>,
        "shared_secret": "<id-of-the-password>"
      }
    ]
  },
  "require_commitlog": false
}

Local user database with X.509 certificates

This example configures a local user database with X.509 certificates to authenticate the users of Safeguard for Privileged Sessions. Note that the password-related elements have to be disabled.

{
  "backend": {
    "cracklib_enabled": false,
    "expiration_days": 0,
    "minimum_password_strength": "disabled",
    "remember_previous_passwords": 0,
    "selection": "local"
  },
  "method": {
    "admin_fallback": true,
    "dn": "<CN>",
    "selection": "x509",
    "trusted_ca": "<id-of-the-trusted-ca>"
  },
  "require_commitlog": false
}

POSIX LDAP server

This example configures a POSIX LDAP server, communication between Safeguard for Privileged Sessions and the LDAP server is not encrypted. Note that for password authentication, the password-related elements have to be omitted from the JSON, as the POSIX server determines the password policy.

{
  "backend": {
    "user_base_dn": "<basedn>",
    "group_base_dn": "<basedn>",
    "bind_dn": "<binddn>",
    "bind_password": "<id-of-the-password>",
    "encryption": {
      "selection": "disabled"
    },
    "memberof_attribute": "<user-attr-of-group-dns>",
    "nested_groups": true,
    "schema": {
      "member_uid_attribute": "<memberUid-attr>",
      "selection": "posix",
      "unique_member_attribute": "<uniqueMember-attr>",
      "username_attribute": "<uid-attr>"
    },
    "selection": "ldap",
    "servers": [
      {
        "host": {
          "selection": "ip",
          "value": "<ip-of-server>"
        },
        "port": <port>
      }
    ]
  },
  "method": {
    "selection": "passwd"
  },
  "require_commitlog": false
}

Microsoft Active Directory server

This example configures a Microsoft Active Directory server with mutual authentication, and Safeguard for Privileged Sessions verifies the certificate of the server. Note that for password authentication, the password-related elements have to be omitted from the JSON, as the AD server determines the password policy.

{
  "backend": {
    "user_base_dn": "<basedn>",
    "group_base_dn": "<basedn>",
    "bind_dn": "<bind-dn>",
    "bind_password": "<id-of-the-password>",
    "encryption": {
      "client_authentication": {
        "enabled": true,
        "x509_identity": "<id-of-the-cert>",
      "selection": "starttls",
      "server_certificate_check": {
        "enabled": true,
        "server_certificate_ca": "<cert>"
      }
    },
    "memberof_attribute": "<memberOf-attribute-name>",
    "nested_groups": true,
    "schema": {
      "selection": "ad"
    },
    "selection": "ldap",
    "servers": [
      {
        "host": {
          "selection": "ip",
          "value": "<ip-of-server>"
        },
        "port": <port>
      }
    ]
  },
  "method": {
    "selection": "passwd"
  },
  "require_commitlog": false
}

Modify the authentication and user database settings

To modify the authentication and user database settings, you have to:

1. Open a transaction.

   For details, see Open a transaction.

2. Modify the JSON object of the endpoint.

   PUT the modified JSON object to the https://<IP-address-of-Safeguard for Privileged Sessions>/api/configuration/aaa/settings endpoint. You can find a detailed description of the available parameters listed in Authentication and user database settings.

3. 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.