Chat now with support
Chat with Support

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

Introduction Using the Safeguard for Privileged Sessions REST API Basic settings User management and access control Managing Safeguard for Privileged Sessions General connection settings HTTP connections Citrix ICA connections RDP connections SSH connections Telnet connections VNC connections Search, download, and index sessions Reporting Advanced authentication and authorization Completing the Welcome Wizard using REST Enable and configure analytics using REST About us Third-party contributions

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
Header name Description Required Values
session_id Contains the authentication token of the user Required

The value of the session ID cookie received from the REST server in the authentication response, for example, a1f71d030e657634730b9e887cb59a5e56162860. For details on authentication, see Authenticate to the Safeguard for Privileged Sessions REST API.

Note that this session ID refers to the connection between the REST client and the Safeguard for Privileged Sessions REST API. It is not related to the sessions that Safeguard for Privileged Sessions records (and which also have a session ID, but in a different format).

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"
  }
}
Element Type Description
key string Top level element, contains the ID of the endpoint.
body Top level element (string) Contains the configuration options for traffic-related alerts.
scbAuthFailure Top level item User authentication failed.
email boolean Set to true to enable e-mail alerts.
snmp boolean Set to true to enable SNMP alerts.
scbAuthSuccess Top level item Successful user authentication.
email boolean Set to true to enable e-mail alerts.
snmp boolean Set to true to enable SNMP alerts.
scbChannelDenied Top level item Channel opening denied.
email boolean Set to true to enable e-mail alerts.
snmp boolean Set to true to enable SNMP alerts.
scbConnectionDenied Top level item Connection denied.
email boolean Set to true to enable e-mail alerts.
snmp boolean Set to true to enable SNMP alerts.
scbConnectionFailed Top level item Connection to the server failed.
email boolean Set to true to enable e-mail alerts.
snmp boolean Set to true to enable SNMP alerts.
scbConnectionTimedout Top level item Connection timed out.
email boolean Set to true to enable e-mail alerts.
snmp boolean Set to true to enable SNMP alerts.
scbCredStoreClosed Top level item The requested credential store is closed.
email boolean Set to true to enable e-mail alerts.
snmp boolean Set to true to enable SNMP alerts.
scbCredStoreDecryptError Top level item Failure to decrypt a credential.
email boolean Set to true to enable e-mail alerts.
snmp boolean Set to true to enable SNMP alerts.
scbCredStoreUnlockFailure Top level item Failure to unlock the credential store.
email boolean Set to true to enable e-mail alerts.
snmp boolean Set to true to enable SNMP alerts.
scbGWAuthFailure Top level item The user failed to authenticate on the gateway.
email boolean Set to true to enable e-mail alerts.
snmp boolean Set to true to enable SNMP alerts.
scbGWAuthSuccess Top level item Successful authentication on the gateway.
email boolean Set to true to enable e-mail alerts.
snmp boolean Set to true to enable SNMP alerts.
scbProtocolViolation Top level item Protocol violation.
email boolean Set to true to enable e-mail alerts.
snmp boolean Set to true to enable SNMP alerts.
scbRealTimeAlert Top level item Real-time audit event detected.
email boolean Set to true to enable e-mail alerts.
snmp boolean Set to true to enable SNMP alerts.
scbSshHostKeyLearned Top level item New SSH hostkey learned.
email boolean Set to true to enable e-mail alerts.
snmp boolean Set to true to enable SNMP alerts.
scbSshHostKeyMismatch Top level item SSH host key mismatch.
email boolean Set to true to enable e-mail alerts.
snmp boolean Set to true to enable SNMP alerts.
scbUserMappingFailure Top level item User mapping failed on the gateway.
email boolean Set to true to enable e-mail alerts.
snmp boolean Set to true to enable SNMP alerts.
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.

Code Description Notes
201 Created The new resource was successfully created.
401 Unauthenticated The requested resource cannot be retrieved because the client is not authenticated and the resource requires authorization to access it. The details section contains the path that was attempted to be accessed, but could not be retrieved.
401 AuthenticationFailure Authenticating the user with the given credentials has failed.
404 NotFound The requested object does not exist.

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
Header name Description Required Values
session_id Contains the authentication token of the user Required

The value of the session ID cookie received from the REST server in the authentication response, for example, a1f71d030e657634730b9e887cb59a5e56162860. For details on authentication, see Authenticate to the Safeguard for Privileged Sessions REST API.

Note that this session ID refers to the connection between the REST client and the Safeguard for Privileged Sessions REST API. It is not related to the sessions that Safeguard for Privileged Sessions records (and which also have a session ID, but in a different format).

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"
  }
}
Element Description
acls Access control settings for usergroups.
local_database Local users and usergroups.
settings Authentication and user database settings.
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.

Code Description Notes
401 Unauthenticated The requested resource cannot be retrieved because the client is not authenticated and the resource requires authorization to access it. The details section contains the path that was attempted to be accessed, but could not be retrieved.
401 AuthenticationFailure Authenticating the user with the given credentials has failed.
404 NotFound The requested object does not exist.

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
Header name Description Required Values
session_id Contains the authentication token of the user Required

The value of the session ID cookie received from the REST server in the authentication response, for example, a1f71d030e657634730b9e887cb59a5e56162860. For details on authentication, see Authenticate to the Safeguard for Privileged Sessions REST API.

Note that this session ID refers to the connection between the REST client and the Safeguard for Privileged Sessions REST API. It is not related to the sessions that Safeguard for Privileged Sessions records (and which also have a session ID, but in a different format).

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"
  }
}
Element Type Description
key string Top level element, contains the ID of the endpoint.
body Top level element (string) Contains the authentication settings.
backend Top level item Settings for the user database (local or LDAP), and password policy.
method Top level item Settings for the authentication method (password, RADIUS server, or X.509 certificate).
require_commitlog boolean Set to true to request the user to write an explanation to every configuration change.
Elements of backend Type Description
selection string

Defines the user database back-end. Possible values are:

  • ldap

    Use an LDAP server (AD or POSIX) for authentication.

  • local

    Use a local user database for authentication.

cracklib_enabled boolean

Password setting. Set to false if a RADIUS server or X.509 certificate is used for authentication. Must be used if the value of the selection element is set to local.

Set to true to test the strength of user passwords with simple dictionary attacks before they are committed.

NOTE:

The strength of the password is determined by its entropy: the variety of numbers, letters, capital letters, and special characters used, not only by its length.

To execute some simple dictionary-based attacks to find weak passwords, set Cracklib (eg. dictionary) check on password to Enabled.

expiration_days int

Password setting. Set to 0 if a RADIUS server or X.509 certificate is used for authentication. Must be used if the value of the selection element is set to local.

Configures the number of days the user passwords are considered valid. Expired passwords must be changed upon login.

The 0 value means the passwords do not expire. The highest value you can configure is 365.

minimum_password_strength string

Password setting. Set to disabled if a RADIUS server or X.509 certificate is used for authentication. Must be used if the value of the selection element is set to local.

Configures the required password strength for new passwords. Possible values are:

  • disabled

    Any password is accepted.

  • good

    Weak passwords are not accepted.

  • strong

    Only strong passwords are accepted.

remember_previous_passwords int

Password setting. Set to 0 if a RADIUS server or X.509 certificate is used for authentication. Must be used if the value of the selection element is set to local.

Configures the number of previous passwords to retain to prevent password reuse.

The 0 value means passwords can be reused.

user_base_dn string

Must be used if the value of the selection element is set to ldap.

Name of the DN to be used as the base of queries regarding users.

NOTE:

You must fill in this field. It is OK to use the same value for user_base_dn and group_base_dn.

However, note that specifying a sufficiently narrow base for the LDAP subtrees where users and groups are stored can speed up LDAP operations.

group_base_dn string

Must be used if the value of the selection element is set to ldap.

Name of the DN to be used as the base of queries regarding groups.

NOTE:

You must fill in this field. It is OK to use the same value for user_base_dn and group_base_dn.

However, note that specifying a sufficiently narrow base for the LDAP subtrees where users and groups are stored can speed up LDAP operations.

bind_dn string

The Distinguished Name that Safeguard for Privileged Sessions should use to bind to the LDAP directory. Must be used if the value of the selection element is set to ldap.

NOTE:
  • Safeguard for Privileged Sessions accepts both pre-win2000-style and Win2003-style account names (User Principal Names), for example administrator@example.com is also accepted.

  • Do not use sAMAccountName, as the bind DN expects a CN.

bind_password string

Must be used if the value of the selection element is set to ldap.

References the password Safeguard for Privileged Sessions uses to authenticate on the server. You can configure passwords at the /api/configuration/passwords/ endpoint.

To modify or add a password, use the value of the returned key as the value of the password element, and remove any child elements (including the key).

NOTE:

Safeguard for Privileged Sessions accepts passwords that are not longer than 150 characters. The following special characters can be used: !"#$%&'()*+,-./:;<=>?@[\]^-`{|}

encryption Top level item

Must be used if the value of the selection element is set to ldap.

Configuration settings for encrypting the communication between Safeguard for Privileged Sessions and the LDAP server.

client_authentication Top level item

Must be used with the selection child element.

Configures the X.509 certificate Safeguard for Privileged Sessions uses to authenticate on the LDAP server.

enabled boolean

Must be used with the client-authentication parent element.

Set to true if the LDAP server requires mutual authentication.

x509_identity string

Must be used if the enabled element is set to true.

References the identifier of the X.509 certificate stored on Safeguard for Privileged Sessions. You can configure certificates at the /api/configuration/x509/ endpoint.

To modify or add an X.509 host certificate, use the value of the returned key as the value of the x509_identity element, and remove any child elements (including the key).

selection string

Defines the type of encryption Safeguard for Privileged Sessions uses to communicate with the LDAP server. Possible values are:

  • disabled

    The communication is not encrypted.

  • ssl

    If you set the address using a domain name ("host": { "selection": "fqdn"), and you use a TLS-encrypted with certificate verification to connect to the LDAP server, use the full domain name (for example ldap.example.com), otherwise the certificate verification might fail. The name of the LDAP server must appear in the Common Name of the certificate.

    NOTE:

    TLS-encrypted connection to Microsoft Active Directory is supported only on Windows 2003 Server and newer platforms. Windows 2000 Server is not supported.

  • starttls

    Opportunistic TLS.

server_certificate_check Top level item

Must be used with the selection child element.

Configuration settings for verifying the LDAP server's certificate.

enabled boolean

Must be used with the server_certificate_check parent element.

Set to true to verify the LDAP server's certificate using the certificate of a Certificate Authority (CA).

server_certificate_ca string

Must be used if the enabled element is set to true.

The certificate of the CA.

memberof_attribute string

The name of the user attribute (for example, in case of Active Directory: memberOf). Must be used if the value of the selection element is set to ldap, otherwise it is optional.

Configure this element if you have an LDAP schema where the user groups can only be determined from a user attribute that contains the group DNs.

Caution:

Using this option significantly slows down log on to the Safeguard for Privileged Sessions web interface if you have too many groups.

nested_groups boolean

Must be used if the value of the selection element is set to ldap.

Set to true to use nested groups when querying the LDAP server

schema Top level item

Must be used if the value of the selection element is set to ldap.

Schema settings for AD and POSIX servers.

selection string

Configures which LDAP schema to use: AD or POSIX. Possible values are:

member_uid_attribute string

Must be used if the value of the selection element is set to posix.

Attribute name of the POSIX group membership.

unique_member_attribute string

Must be used if the value of the selection element is set to posix.

Attribute name of the GroupOfUniqueMemberships membership.

username_attribute string

Must be used if the value of the selection element is set to posix.

Attribute name of the username (user ID).

servers Top level list

Must be used if the value of the selection element is set to ldap.

Contains the addresses and ports of the LDAP servers.

host Top level item Contains the address of the LDAP server.
selection string

Defines the address type (IP or domain name). Possible values are:

  • fqdn

    The LDAP server address is provided as a fully qualified domain name.

  • ip

    The LDAP server address is provided as an IP address.

value string

The address of the LDAP server.

  • If you set the address using an IP address ("selection": "ip"), use an IPv4 address.

  • If you set the address using a domain name ("host": { "selection": "fqdn"), and you use a TLS-encrypted with certificate verification to connect to the LDAP server, use the full domain name (for example ldap.example.com), otherwise the certificate verification might fail. The name of the LDAP server must appear in the Common Name of the certificate.

port int The port of the LDAP server.
Elements of method Type Description
selection string

Configures the authentication method. Possible values are:

  • passwd: Use passwords for authentication.

  • radius: Configure authentication against a RADIUS server.

    Caution:

    The challenge/response authentication method is currently not supported. Other authentication methods (for example password, SecureID) should work.

  • x509: Use X.509 certificates for authentication.

servers Top level list

RADIUS setting. Must be used if the value of the selection element is set to radius.

Contains the RADIUS server addresses and port numbers, and references the shared secrets.

address Top level item

RADIUS setting. Must be used if the value of the selection element is set to radius.

The address and port number of the RADIUS server.

authentication_protocol Top level item

RADIUS setting. Set to pap to use the Password Authentication Protocol. To use the Challenge-Handshake Authentication Protocol, set it to chap.

selection string

RADIUS setting. Must be used if the value of the selection element is set to radius.

Defines the address type (IP or domain name). Possible values are:

  • fqdn

    The RADIUS server address is provided as a fully qualified domain name.

  • ip

    The RADIUS server address is provided as an IP address.

value string

RADIUS setting. Must be used if the value of the selection element is set to radius.

The address of the RADIUS server.

port int

RADIUS setting. Must be used if the value of the selection element is set to radius.

The port number of the RADIUS server.

shared_secret string

RADIUS setting. Must be used if the value of the selection element is set to radius.

References the identifier of the shared secret. You can view or modify the list of shared secrets at the /api/configuration/passwords/ endpoint.

To modify or add a shared secret, use the value of the returned key as the value of the shared_secret element, and remove any child elements (including the key).

admin_fallback boolean

X.509 setting. Must be used if the value of the selection element is set to x509.

Set to true to allow the admin user to use password for login.

dn string

X.509 setting. Must be used if the value of the selection element is set to x509.

X.509 DN field name of the username (case sensitive). In most cases, this value is either CN or UID.

trusted_ca string

X.509 setting. Must be used if the value of the selection element is set to x509.

References the identifier of the trusted CA. You can view or modify the list of trusted CAs at the /api/configuration/policies/trusted_ca_lists/ endpoint.

To modify or add a trusted CA, use the value of the returned key as the value of the trusted_ca element, and remove any child elements (including the key).

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:

NOTE:

Safeguard for Privileged Sessions accepts passwords that are not longer than 150 characters. The following special characters can be used: !"#$%&'()*+,-./:;<=>?@[\]^-`{|}

NOTE:

The strength of the password is determined by its entropy: the variety of numbers, letters, capital letters, and special characters used, not only by its length.

To execute some simple dictionary-based attacks to find weak passwords, set Cracklib (eg. dictionary) check on password to Enabled.

NOTE:

Changes to the password policy do not affect existing passwords. However, setting password expiry will require every user to change their passwords after the expiry date, and the new passwords must comply with the strength requirements set in the password policy.

{
  "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.

Caution:

The challenge/response authentication method is currently not supported. Other authentication methods (for example password, SecureID) should work.

Caution:

After you commit this configuration, the Safeguard for Privileged Sessions web interface will be available only after successfully authenticating to the RADIUS server. Note that the default admin account of Safeguard for Privileged Sessions will be able to login normally, even if the RADIUS server is unaccessible.

{
  "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

NOTE:
  • The admin user is available by default and has all privileges. It is not possible to delete this user.

  • Enabling LDAP authentication automatically disables the access of every local user except for admin. The admin user can login to Safeguard for Privileged Sessions even if LDAP authentication is used.

  • Safeguard for Privileged Sessions accepts both pre-win2000-style and Win2003-style account names (User Principal Names). User Principal Names (UPNs) consist of a username, the at (@) character, and a domain name, for example administrator@example.com.

  • For the username of SSH users, only valid UTF-8 strings are allowed.

  • The following characters cannot be used in usernames and group names: <>/\[]:;|=,+*)?@"

  • When using RADIUS authentication together with LDAP users, the users are authenticated to the RADIUS server, only their group memberships must be managed in LDAP. For details, see "Authenticating users to a RADIUS server" in the Administration Guide.

Caution:

A user can belong to a maximum of 10,000 groups, further groups are ignored.

Caution:

By default, Safeguard for Privileged Sessions uses nested groups when querying the LDAP server. Nested groups are mostly useful when authenticating the users to Microsoft Active Directory, but can slow down the query and cause the connection to timeout if the LDAP tree is very large. In this case, disable the Enable nested groups option.

NOTE:

You also have to configure the usergroups in Safeguard for Privileged Sessions and possibly in your LDAP database. For details on using usergroups, see "Using usergroups" in the Administration Guide.

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

NOTE:
  • The admin user is available by default and has all privileges. It is not possible to delete this user.

  • Enabling LDAP authentication automatically disables the access of every local user except for admin. The admin user can login to Safeguard for Privileged Sessions even if LDAP authentication is used.

  • Safeguard for Privileged Sessions accepts both pre-win2000-style and Win2003-style account names (User Principal Names). User Principal Names (UPNs) consist of a username, the at (@) character, and a domain name, for example administrator@example.com.

  • For the username of SSH users, only valid UTF-8 strings are allowed.

  • The following characters cannot be used in usernames and group names: <>/\[]:;|=,+*)?@"

  • When using RADIUS authentication together with LDAP users, the users are authenticated to the RADIUS server, only their group memberships must be managed in LDAP. For details, see "Authenticating users to a RADIUS server" in the Administration Guide.

Caution:

A user can belong to a maximum of 10,000 groups, further groups are ignored.

Caution:

By default, Safeguard for Privileged Sessions uses nested groups when querying the LDAP server. Nested groups are mostly useful when authenticating the users to Microsoft Active Directory, but can slow down the query and cause the connection to timeout if the LDAP tree is very large. In this case, disable the Enable nested groups option.

NOTE:

You also have to configure the usergroups in Safeguard for Privileged Sessions and possibly in your LDAP database. For details on using usergroups, see "Using usergroups" in the Administration Guide.

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.

Code Description Notes
201 Created The new resource was successfully created.
401 Unauthenticated The requested resource cannot be retrieved because the client is not authenticated and the resource requires authorization to access it. The details section contains the path that was attempted to be accessed, but could not be retrieved.
401 AuthenticationFailure Authenticating the user with the given credentials has failed.
404 NotFound The requested object does not exist.
Related Documents

The document was helpful.

Select Rating

I easily found the information I needed.

Select Rating