One Identity Safeguard for Privileged Sessions 7.0.5.1 LTS

Configure LDAP AD and LDAP POSIX servers for authentication, authorization, and accounting (AAA).

URL

POST https://<IP-address-of-SPS>/api/configuration/aaa/ldap_servers

Operations

Operations with the /aaa/ldap_servers endpoint include:

Operation	HTTP method	URL	Notes
Creating a new LDAP server	POST	/api/configuration/aaa/ldap_servers
Retrieving a LDAP server	GET	/api/configuration/aaa/ldap_servers

Sample request

The following command creates a new LDAP server.

curl --cookie cookies https://<IP-address-of-SPS>/api/configuration/aaa/ldap_servers

The following is a sample request.

{
     "name": "ldap-server-name",
     "schema": {
       "selection": "posix",
       "username_attribute": "uid",
       "membership_check": {
         "enabled": true,
         "member_uid_attribute": "memberUid"
       },
       "memberof_check": {
         "enabled": true,
         "memberof_user_attribute": "memberOf",
         "memberof_group_objectclass": "groupOfNames"
       },
       "user_dn_in_groups": [
         {
           "object_class": "groupOfNames",
           "attribute": "member"
         },
         {
           "object_class": "groupOfUniqueNames",
           "attribute": "uniqueMember"
         }
       ]
     },
     "servers": [
       {
         "host": {
           "selection": "ip",
           "value": "10.110.0.1"
         },
         "port": 389
       }
     ],
     "user_base_dn": "ou=People,dc=example",
     "group_base_dn": "ou=Groups,dc=example",
     "bind_dn": null,
     "bind_password": null,
     "encryption": {
       "selection": "disabled"
     }
   }

Response

The following is a sample response received when you retrieve LDAP server information.

{
     "items": [
       {
         "body": {
           "bind_dn": null,
           "bind_password": null,
           "encryption": {
             "selection": "disabled"
           },
           "group_base_dn": "ou=Groups,dc=example",
           "name": "ldap-server-name",
           "schema": {
             "memberof_check": {
               "enabled": true,
               "memberof_group_objectclass": "groupOfNames",
               "memberof_user_attribute": "memberOf"
             },
             "membership_check": {
               "enabled": true,
               "member_uid_attribute": "memberUid"
             },
             "selection": "posix",
             "user_dn_in_groups": [
               {
                 "attribute": "member",
                 "object_class": "groupOfNames"
               },
               {
                 "attribute": "uniqueMember",
                 "object_class": "groupOfUniqueNames"
               }
             ],
             "username_attribute": "uid"
           },
           "servers": [
             {
               "host": {
                 "selection": "ip",
                 "value": "10.110.0.1"
               },
               "port": 389
             }
           ],
           "user_base_dn": "ou=People,dc=example"
         },
         "key": "XXXXXXXX-XXXX-XXXX-XXXX-XXXXXXXXXXXX",
         "meta": {
           "href": "/api/configuration/aaa/ldap_servers/XXXXXXXX-XXXX-XXXX-XXXX-XXXXXXXXXXXX"
         }
       }
     ]
   }

Elements of the response message body include:

Element	Type	Description	Notes
bind_dn	string	The Distinguished Name that SPS should use to bind to the LDAP directory. Must be used if the value of the selection element is set to ldap.	NOTE: SPS accepts both pre Windows 2000-style and Windows 2003-style account names, or User Principal Names (UPNs). For example, administrator@example.com is also accepted.
bind_password	null \| string	References the password SPS uses to authenticate on the server. You can configure passwords at the /api/configuration/passwords/ endpoint. Must be used if the value of the selection element is set to ldap. 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: SPS accepts passwords that are not longer than 150 characters and supports the following characters: Letters A-Z, a-z Numbers 0-9 The space character Special characters: !"#$%&'()*+,-./:;<>=?@[]\^-`{}_\|
encryption	union	Configuration settings for encrypting the communication between SPS and the LDAP server.	The displayed value type depends on the encryption.selection parameter.
encryption.selection	enum	Defines the type of encryption SPS uses to communicate with the LDAP server. Possible values are: disabled The communication is not encrypted. ssl TLS/SSL encryption. To use a TLS-encrypted with certificate verification to connect to the LDAP server, use the full domain name (for example ldap.example.com) as the server address, 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.	Example if the value is disabled { "selection": "disabled" } Example if the value is ssl or starttls: { "selection": "ssl \| starttls", "trust_store": null\|<trust-store-ref>, "client_authentication": null\|<x509-ref> }
group_base_dn	string	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.	Example: "ou=users,ou=example"
name	string	Top level element, the name of the object. This name is also displayed on the SPS web interface. It cannot contain whitespace.
schema	union	AD and POSIX specific LDAP configuration.	Example with LDAP AD server, where the schema selection is ad: { "selection": "ad", "membership_check": ..., "memberof_check": ..., "user_dn_in_groups": … } Example with LDAP POSIX server, where the schema selection is posix: { "selection": "posix", "membership_check": ..., "memberof_check": ..., "user_dn_in_groups": ..., "username_attribute": … }
schema.memberof_check	object	The Enable checking for group DNs in user objects setting allows checking a configurable attribute in the user object. This attribute contains a list of group DNs the user is additionally a member of. This user attribute is usually memberOf.	Example with LDAP AD server, if memberof_check and memberof_user_attribute are enabled: "schema": { "memberof_check": { "enabled": true, "memberof_user_attribute": "memberOf" } Example with LDAP POSIX server, if memberof_check is enabled: "schema": { "memberof_check": { "enabled": true, "memberof_group_objectclass": "groupOfNames", "memberof_user_attribute": "memberOf" } To disable memberof_check for both LDAP AD and LDAP POSIX servers, set the enabled parameter to false. "schema": { "memberof_check": { "enabled": false }
schema.memberof_check.enabled	boolean	To enable memberof_check, set it to true.
schema.memberof_check.memberof_group_objectclass	string	The attribute holding the members of the LDAP group.	This field is case-sensitive. Default value: groupOfNames
schema.memberof_check.memberof_user_attribute	string	Must be used if the memberof_check is set it to true. The name of the user attribute (for example, memberOf) that contains the group DNs.	This attribute is the same for both LDAP AD and LDAP POSIX schema.
schema.membership_check	object	POSIX: POSIX primary and supplementary group membership checking. AD: Active Directory specific non-primary group membership checking.	Example with LDAP AD server, if membership_check and nested_groups are enabled: "membership_check": { "enabled": true, "nested_groups": true \| false" } Example with LDAP POSIX server, if membership_check and member_uid_attribute are enabled: "membership_check": { "enabled": true, "member_uid_attribute": null \| "memberUid" } To disable membership_check for both LDAP AD and LDAP POSIX servers, set the enabled parameter to false. "membership_check": { "enabled": false }
schema.membership_check.enabled	boolean	POSIX: Enables POSIX primary and supplementary group membership checking. AD: Enables Active Directory specific non-primary group membership checking.
schema.membership_check.member_uid_attribute	string	Must be used if the value of the selection element is set to posix. The POSIX group membership attribute name is the name of the attribute in a posixGroup group object, which lists the plain usernames that are members of the group. These groups are usually referred to as supplementary groups of the referred user. Can be null.	Default value: memberUid
schema.selection	string	Configures which LDAP schema to use: AD or POSIX. Possible values are: ad: Microsoft Active Directory server. For details and examples, see Configuring LDAP servers. posix: The server uses the POSIX LDAP scheme. Must be used with the member_uid_attribute and username_attribute elements. For details and examples, see Configuring LDAP servers.	Default value: ad, posix
schema.user_dn_in_groups	array	Add object_class / attribute pairs. SPS will search for the user DN in the group's attribute defined here. If it finds the user DN there, SPS considers the user the member of that group.	Example: "user_dn_in_groups": [ { "attribute": "member", "object_class": "groupOfNames" }, { "attribute": "uniqueMember", "object_class": "groupOfUniqueNames" } ] The array can return empty: "user_dn_in_groups": [] user_dn_in_groups can serve as additional validation. At least one out of membership_check, memberof_check or user_dn_in_groups must be filled for validation.
schema.user_dn_in_groups.attribute	string	Name of the group attribute which contains the user DN.	Default value: member
schema.user_dn_in_groups.object_class	string	Consider groups of this objectClass.	Possible values: groupOfNames, groupOfUniqueNames
schema.username_attribute	string	The login attribute that uniquely identifies a single user record.	Default value: uid
servers	array	Contains the addresses and ports of the LDAP servers.	The displayed value type depends on the servers.host.selection parameter. Possible values are: ip, fqdn Example if the host selection is ip: "servers": [ { "host":{ "selection": "ip", "value": "1.2.3.4" }, "port": 123 } ], Example, if the host selection is fqdn: "servers": [ { "host": { "selection": "fqdn", "value": "my.example" }, "port": 123 } ],
servers.host	object	Contains the address of the LDAP server.
servers.host.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.
servers.host.value	string	The address of the LDAP server.
servers.port	int	The port of the LDAP server.
user_base_dn	string	Name of the DN to be used as the base of queries regarding users. Must be used if the value of the selection element is set to ldap. 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.	For example: "ou=groups,ou=example"

Configure LDAP servers

To configure an LDAP server, you have to:

Open a transaction.

For more information, see Open a transaction.
Create the JSON object for the new LDAP server configuration.

POST the JSON object to the https://<IP-address-of-SPS>/api/configuration/aaa/ldap_servers endpoint. You can find a detailed description of the available parameters listed in Element .
Commit your changes.

For more information, see Commit a transaction.

HTTP response codes

For more information and a complete list of standard HTTP response codes, see Application level error codes.

Use the /aaa/login_methods endpoint to configure multiple login methods for SPS. Possible login methods are the following:

Local login
LDAP login (AD or POSIX)
X509 login
RADIUS login

URL

POST https://<IP-address-of-SPS>/api/configuration/aaa/login_methods

Operations

Operations with the /aaa/login_methods endpoint include:

Operation	HTTP method	URL	Notes
Configuring the Local login method	POST	/api/configuration/aaa/login_methods	NOTE: Changing your password is possible only with Local login.
Configuring the X509 login method			Before you can configure the X509 login method, you must upload your X509 certificate to a trust store at the /api/configuration/trust_stores endpoint.
Configuring the password-based LDAP login method (AD or POSIX)			Before you can configure the LDAP login method, you must create a new LDAP server at the /api/configuration/aaa/ldap_servers endpoint.
Configuring the RADIUS login method
Reordering login methods	PUT	/api/configuration/aaa/login_methods/@order	By default, the Local login method button appears as the first login method on the SPS web interface. To reorder the login method buttons, use the /@order endpoint.

Sample request

The following command creates a new login method.

curl --cookie cookies https://<IP-address-of-SPS>/api/configuration/aaa/login_methods

The following parameters are applicable to all login methods - Local, LDAP, X509, and RADIUS.

Element	Type	Description	Notes
type	enum	The login method type used for authentication.	Possible values are: local Use a local user database for authentication. x509 Use a X509 certificate for authentication. ldap Use an LDAP server (AD or POSIX) for authentication. radius Use a RADIUS server for authentication.
name	string	A unique identifier of the login method.
title	string	The title that appears above the login method button on the SPS web interface. This can be customized.	In the case of X509 login method, there is only one button.
active	boolean	Indicates whether the login method is enabled or not.

Example: Sample request for configuring Local login

{
     "type": "local",
     "name": "inactive-local",
     "title": "Local login",
     "active": false,
     "cracklib_enabled": true,
     "expiration_days": 30,
     "remember_previous_passwords": 10,
     "minimum_password_strength": "good",
     "minimum_password_length": 1
   }

Elements of the request message body include:

Element	Type	Description	Notes
cracklib_enabled	boolean	Password setting. 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. Set to false if a RADIUS server or X.509 certificate is used for authentication.	NOTE: The strength of a password is determined by its length and complexity: the variety of numbers, letters, capital letters, and special characters used. To run simple dictionary-based attacks to find weak passwords, enable Cracklib (eg. dictionary) protection.
expiration_days	integer	Password setting. Configures the number of days the user passwords are considered valid. Expired passwords must be changed upon login.	Set to 0 if a RADIUS server or X.509 certificate is used for authentication. The 0 value means the passwords do not expire. The highest value you can configure is 365. Must be used if the value of the selection element is set to local.
remember_previous_passwords	integer	Password setting. Configures the number of previous passwords to retain to prevent password reuse.	Set to 0 if a RADIUS server or X.509 certificate is used for authentication. The 0 value means passwords can be reused. Must be used if the value of the selection element is set to local.
minimum_password_strength	string	Password setting. Configures the required password strength for new passwords.	Set to disabled if a RADIUS server or X.509 certificate is used for authentication. Possible values are: disabled Any password is accepted. good Weak passwords are not accepted. strong Only strong passwords are accepted. Must be used if the value of the selection element is set to local.
minimum_password_length	number	The minimum number of characters the password must consist of.

Example: Sample request for configuring LDAP login

{
     "type": "ldap",
     "name": "ldap",
     "title": "LDAP login",
     "active": true,
     "ldap_server": "5ed1b422-395a-4d5e-abf0-b43cd6c752f8"
   }

Elements of the request message body include:

Element	Type	Description	Notes
ldap_server	string	The identifier of the previously created LDAP server.

Example: Sample request for configuring X509 login

{
     "type": "x509",
     "name": "x509",
     "title": "X509 login",
     "active": true,
     "trust_store": "5ed1b422-395a-4d5e-abf0-b43cd6c752f8",
     "username_attribute": "commonName",
     "groups": {
       "type": "local"
     }
   }

Elements of the request message body include:

Element	Type	Description	Notes
trust_store	string	The identifier of the X509 certificate that was previously uploaded into Trust stores.	Trust stores serve as local certificate storages where users can store the certificate chains of trusted Certificate Authorities (CAs).
username_attribute	enum	The login attribute that uniquely identifies a single user record. You can choose which type of username you want to use.	Possible values are: commonName emailAddress userId userPrincipalName
groups	object	The location of your group from which you will authorize access.
groups.type	enum	The type of the group.	Possibe values are: local ldap If the group type is ldap, the identifier of the previously created LDAP server (the value of the ldap_server field) will appear.

Example: Configuring X509 login with LDAP groups

To configure a X509 login with LDAP groups

Create a new LDAP server at the /api/configuration/aaa/ldap_servers endpoint.

{
     "name": "ldap_server",
     "schema": {
         "selection": "posix",
         "username_attribute": "uid",
         "membership_check": {
             "enabled": true,
             "member_uid_attribute": "memberUid"
         },
         "memberof_check": {
             "enabled": true,
             "memberof_user_attribute": "memberOf",
             "memberof_group_objectclass": "groupOfNames"
         },
         "user_dn_in_groups": [
             {
                 "object_class": "groupOfNames",
                 "attribute": "member"
             },
             {
                 "object_class": "groupOfUniqueNames",
                 "attribute": "uniqueMember"
             }
         ]
     },
     "servers": [
         {
             "host": {
                 "selection": "ip",
                 "value": "1.2.3.4"
             },
             "port": 389
         }
     ],
     "user_base_dn": "ou=People,dc=example",
     "group_base_dn": "ou=Groups,dc=example",
     "bind_dn": null,
     "bind_password": null,
     "encryption": {
         "selection": "disabled"
     }
}

Upload a X509 certificate at the /api/configuration/trust_stores endpoint.

{
     "name": "X509_Trust_Store",
     "authorities": [
         "-----BEGIN CERTIFICATE-----\nMIIDZzCCAk+gAwIBAgIUMlI5+EgTDAh2zqRDGYrzFRyozI8wDQYJKoZIhvcNAQEL\nBQAwQzELMAkGA1UEBhMCSFUxETAPBgNVBAgMCEJ1ZGFwZXN0MSEwHwYDVQQKDBhJ\nbnRlcm5ldCBXaWRnaXRzIFB0eSBMdGQwHhcNMTQwODEyMTIzNjQ4WhcNMzQwNjE4\nMTIzNjQ4WjBDMQswCQYDVQQGEwJIVTERMA8GA1UECAwIQnVkYXBlc3QxITAfBgNV\nBAoMGEludGVybmV0IFdpZGdpdHMgUHR5IEx0ZDCCASIwDQYJKoZIhvcNAQEBBQAD\nggEPADCCAQoCggEBALffJBDD6A/ZGBTgFbyLXHulU+hGnMW3DoPo2q4HY1/FfbkS\nrzmK+Fiz+3EwJCWi+EwK9mqve/nh6YRRw/VaAVQ7CkA7f7to+I7gP647Bq1wk0lh\nBVEJNlN0jfYYSumGxzPotw/fon1MkXuMbLc0Pr/vFX3NQC7/STAV5dZFcdboXDA7\nZZ3rzBIr93ThObsGj01MRO6wrS3rfE7Px9D7C2u9YSkP3OQ1Sfm/jqyLNaT6xt4i\nhrLnfYEc8mClnrlvILi+q/D6mIUSjb4IGvergAyl4jgPjO02UcvBzOIA9tDlBJBi\nQxZx+T620ubmEwOl9Q0G8RAWKz7szrBcXEjXhYUCAwEAAaNTMFEwHQYDVR0OBBYE\nFCDfEeq5Hsm8jMrG110iNpt5cikTMB8GA1UdIwQYMBaAFCDfEeq5Hsm8jMrG110i\nNpt5cikTMA8GA1UdEwEB/wQFMAMBAf8wDQYJKoZIhvcNAQELBQADggEBAK3iizM4\nCx69YD+4CWOUswULrCJA38C+nDYONLbNkact8JKXqCn/MaZTII+dZoV9RjjX4AzA\nPTQkZT+RoVeCZyt+qWHMdjq6koabXwQmXNozUtaxEZTrnoUDEWtNIbjV/gNtRcSG\nsU7i9L2YnwDzTw0cR/pu1Hykq8fwqNqjQGYnmXtJspMkKAtVe1CrtnPLiC6JBr0g\n5GZF58sHx5+gO0RkqdzJgRAGnImdfAahqfHmKRFmxoxWLyylRyqDgQ+KqcaDvZI+\ni36M+NQHVrDX4jo4CFoXhFlSOepvtDOpmzoWhugwDNMPuU1IEY7//CJBXQnjp+uf\nLO6PsNmMKDGi9Dk=\n-----END CERTIFICATE-----\n"
     ],
     "crl_urls": [
         "http://crl.it/sec"
     ],
     "revocation_check": "full"
}

Create a new LDAP login method at the /api/configuration/aaa/login_methods endpoint.

{
     "type": "x509",
     "name": "x509",
     "title": "X509 login",
     "active": true,
     "trust_store": "5ed1b422-395a-4d5e-abf0-b43cd6c752f8",
     "username_attribute": "commonName",
     "groups": {
        "type": "ldap",
        "ldap_server": "5ed1b422-395a-4d5e-abf0-b43cd6c752f8"
     }
}

Example: Configuring RADIUS login with local groups

To configure a RADIUS login with local groups

Create a new secret for your RADIUS server at the /api/configuration/passwords/ endpoint. For example, any.secret.

Create a new RADIUS login method at the /api/configuration/aaa/login_methods endpoint.

{
     "type": "radius",
     "name": "radius",
     "title": "Radius login",
     "active": true,
     "servers": [
         {
           "address": {
             "selection": "ip",
             "value": "4.5.6.7"
           },
           "port": 1812,
           "shared_secret": "<'key' from the response of the penultimate creation>"
         },
         {
           "address": {
             "selection": "fqdn",
             "value": "radius.example"
           },
           "port": 18120,
           "shared_secret": "<'key' from the response of the last creation>"
         }
     ],
     "authentication_protocol": "pap",
     "groups": {
         "type": "local"
     }
}

Example: Configuring RADIUS login with LDAP groups (AD or POSIX)

To configure a RADIUS login with LDAP groups

Create a new LDAP server at the /api/configuration/aaa/ldap_servers endpoint.
Create a new secret for your RADIUS server at the /api/configuration/passwords/ endpoint. For example, any.secret.

Create a new LDAP server login method at the /api/configuration/aaa/login_methods endpoint.

{
     "type": "radius",
     "name": "radius",
     "title": "Radius login",
     "active": true,
     "servers": [
         {
             "address": {
               "selection": "fqdn",
               "value": "radius.balabit"
             },
             "port": 18120,
             "shared_secret": "<'key' from the response of the last creation>"
         }
     ],
     "authentication_protocol": "pap",
     "groups": {
         "type": "ldap",
         "ldap_server": "<'key' from the response of the penultimate creation>"
     }
}

Response

HTTP response codes

For more information and a complete list of standard HTTP response codes, see Application level error codes.

Element			Type	Description
key			string	Top level element, contains the ID of the endpoint.
body			Top level element (string)	Contains the troubleshooting settings.
	core_files		Top level item	Contains the settings for core dump file retention.
		retention_days	int	Retention time for core files, in days.
	debug_logging		Top level item	Settings for debug logging.
		enabled	boolean	Set to true to increase the log level of the non-network-related events, adding the commands executed by the SPS web interface to the log.

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.
403	Unauthorized	The requested resource cannot be retrieved because the client is not authorized to access it. The details section contains the path that was attempted to be accessed, but could not be retrieved.
404	NotFound	The requested object does not exist.

One Identity Safeguard for Privileged Sessions 7.0.5.1 LTS - REST API Reference Guide

Configuring LDAP servers

URL

Operations

Sample request

Response

Configure LDAP servers

HTTP response codes

Configuring SPS login methods

URL

Operations

Sample request

Example: Sample request for configuring Local login

Example: Sample request for configuring LDAP login

Example: Sample request for configuring X509 login

Example: Configuring X509 login with LDAP groups

Example: Configuring RADIUS login with local groups

Example: Configuring RADIUS login with LDAP groups (AD or POSIX)

Response

HTTP response codes

Managing SPS

Detailed information about this topic

Troubleshooting options

URL

Sample request

Response

Modify troubleshooting settings

Modify the JSON object of the troubleshooting options.

Please select your product:

To serve you better, please complete the Purpose of your Chat:

Recommended Solutions for Your Problem

One Identity Safeguard for Privileged Sessions 7.0.5.1 LTS - REST API Reference Guide

Configuring LDAP servers

URL

Operations

Sample request

Response

Configure LDAP servers

HTTP response codes

Configuring SPS login methods

URL

Operations

Sample request

Example: Sample request for configuring Local login

Example: Sample request for configuring LDAP login

Example: Sample request for configuring X509 login

Example: Configuring X509 login with LDAP groups

Example: Configuring RADIUS login with local groups

Example: Configuring RADIUS login with LDAP groups (AD or POSIX)

Response

HTTP response codes

Managing SPS

Detailed information about this topic

Troubleshooting options

URL

Sample request

Response

Modify troubleshooting settings

Modify the JSON object of the troubleshooting options.