Chat now with support
Chat with Support

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

Introduction Using the SPS REST API Basic settings User management and access control Managing SPS General connection settings HTTP connections Citrix ICA connections MSSQL connections RDP connections SSH connections Telnet connections VNC connections Search, download, and index sessions Reporting Health and maintenance Advanced authentication and authorization Completing the Welcome Wizard using REST Enable and configure analytics using REST

Trust stores

Trust stores serve as local certificate storages where users can store the certificate chains of trusted Certificate Authorities (CAs). These certificates are then used to ensure secure communication between external parties and the SPS.

There are two types of trust stores: built-in and custom.

The built-in trust store has well known root CAs (such as Google, Microsoft, Verisign, etc.), and it is not modifiable.

Before establishing secure communication (TLS), SPS verifies the certificate of the other party using the assigned trust store. Only certificates signed by any of the CAs in the trust store are accepted.

NOTE: CRL URLs must be listed explicitly in the appropriate field, as those CRL URLs that are embedded in the extensions of the certificates, will be ignored.

URL
GET https://<IP-address-of-SPS>/api/configuration/trust_stores
Cookies
Cookie 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 SPS REST API.

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

Operations with the trust_stores endpoint include:

Operation

 

HTTP method

URL

Notes
Create a trust store POST /api/configuration/trust_stores The name of the trust store must be unique.
List trust stores GET /api/configuration/trust_stores

Users who were not given read access to the trust_stores endpoint explicitly, are still able to retrieve information from it, if they have access to other /configuration related endpoints, which reference trust stores.

Examples of trust store referrer ACL (read access):

  • /pages/starlingjoin
  • /config/xcb/aaa/settings
  • /config/scb/pol_ldaps

Query a trust store GET /api/configuration/trust_stores/<id of the trust store>  
Query the built-in trust store GET /api/configuration/trust_stores/-7001  
Update a trust store PUT /api/configuration/trust_stores/<id of the trust store>

Users who were not given access to the trust_stores endpoint explicitly, but are still able to retrieve information from it because they have access to configuration endpoints which reference trust stores, are unable to modify trust stores.

With the exception of /config/xcb/management, where the same access level is granted to the trust stores for the user as they have for /config/xcb/management.

Delete a trust store DELETE /api/configuration/trust_stores/<id of the trust store>  
Sample request

The following command lists the trust stores:

curl --cookie cookies https://<IP-address-of-SPS>/api/configuration/trust_stores
Response

The following is a sample response received when listing trust stores.

For details of the meta object, see Message format.

 

{ "items": [ { "key": "-7001", "meta": { "href": "/api/configuration/trust_stores/-7001" }, "body": { "name": "Built-in", "revocation_check": "none", "trust_store_type": "built-in" } }, { "key": "XXXXXXXX-XXXX-XXXX-XXXX-XXXXXXXXXXXX", "meta": { "href": "/api/configuration/trust_stores/XXXXXXXX-XXXX-XXXX-XXXX-XXXXXXXXXXXX" }, "body": { "name": "My_Custom_Trust_Store", "authorities": [ { "fingerprint": { "digest": "01:25:1f:a2:df:2a:31:1a:29:7a:ba:43:c4:03:42:a5:d7:30:ec:2d:e0:d7:7a:72:a7:1b:c3:99:c5:6c:10:ea", "hash_algorithm": "sha256" }, "issuer": "C=HU/ST=Budapest/L=None/O=Internet Widgits Pty Ltd/OU=None/CN=None/emailAddress=None", "pem": "-----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", "subject": "C=HU/ST=Budapest/L=None/O=Internet Widgits Pty Ltd/OU=None/CN=None/emailAddress=None" } ], "crl_urls": [ "http://crl.it/sec" ], "revocation_check": "full", "trust_store_type": "custom" } } ] }

Elements of the response message body include:

Elements of items

 

Type

Description

Notes
items

 

object array

List of JSON objects available from the current endpoint.

 
 

key

string

The ID of the trust store.

Each trust store has a unique key.

The built-in trust store's ID is "-7001".

 

meta

string (uri)

The href field contains the URL of the trust store.

 
 

body

     
Elements of body

 

Type

Description

Notes
body

 

object Top level element.  
 

name

string The name of the trust store.

The name field is set by the user and it must be unique.

For example:

"name": "My_Custom_Trust_Store".

The built-in trust store's name is "Built-in".

 

authorities

 

     
 

crl_urls

string array The crl_urls field contains the list of CRL web addresses (HTTP or HTTPs URLs) used for revocation check.

If a trust store that uses certificate revocation lists (CRLs) does not work properly, it might be due to invalid or inaccessible CRL URLs. Troubleshooting can involve checking whether all URLs of the CA CRL URL list are valid, and can be accessed from the SPS via the Basic Settings / Troubleshooting / Connect to TCP port function in the Web UI.

 

revocation_check

enum

The type of the revocation check.

Possible values: "full", "leaf", "none".

"full" - The crl_urls field must contain CRL URLs for all of the CAs that are part of the chain of a given certificate which is being verified.

"leaf" - The crl_urls field must contain at least the CRL URL of the CA which signed the certificate which is being validated.

"none" - The crl_urls field must be empty.

 

trust_store_type

enum

The type of the trust store.

Possible values: "built-in", "custom".

The built-in trust store comes with the operation system. This type of trust store is read-only. There is no CRL check involved, and it cannot be removed.

Elements of authorities

 

Type

Description

Notes
authorities

 

array List of Certificate Authorities.  
 

fingerprint

     
 

issuer

 

string The name of the entity that signed the certificate.  
 

pem

string The certificate in PEM format.  

 

subject

string

The subject of the certificate.

 

Elements of fingerprint

 

Type

Description

Notes
fingerprint

 

  A two-piece byte sequence consisting of a hash algorithm and a message digest.  
 

digest

string The string of digits produced by the hash algorithm.  
 

hash_algorithm

 

string The name of the hash algorithm.  
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 Application level error codes.

Code Description Notes
400 SyntacticError

A value to be set is not accepted syntactically. The details section contains the path that was found to be invalid.

Possible syntactic error messages related to trust store:

  • The user is not allowed to create a built-in trust store or edit or delete the existing one.
  • When revocation_check is set to "none", the crl_urls field must be empty. The user cannot add any element to crl_urls.
  • When revocation_check is set to "full" or "leaf", the crl_urls cannot be empty.

400 SemanticError

The configuration contains semantic errors, inconsistencies or other problems that would put the system into an unreliable state if the configuration had been applied. The details section contains the errors that were found in the configuration.

Possible semantic error messages related to trust store:

  • The name of the trust stores must be unique.
  • The authorities of a trust store must be unique.
  • The CRL URLs of a trust store must be unique.

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.

User management and access control

Topics:

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

URL
GET https://<IP-address-of-SPS>/api/configuration/aaa/
Cookies
Cookie 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 SPS REST API.

Note that this session ID refers to the connection between the REST client and the SPS REST API. It is not related to the sessions that SPS 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-SPS>/api/configuration/aaa/
Response

The following is a sample response received when listing AAA configuration endpoints.

For details of the meta object, see Message format.

{
  "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 Application level error codes.

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

Authentication and user database settings

Contains settings for authenticating to SPS. You can create a user database locally on SPS, 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-SPS>/api/configuration/aaa/settings
Cookies
Cookie 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 SPS REST API.

Note that this session ID refers to the connection between the REST client and the SPS REST API. It is not related to the sessions that SPS 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-SPS>/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 Message format.

{
    "key": "settings",
    "body": {
        "method": {
            "selection": "x509",
            "admin_fallback": true,
            "trusted_ca": {
                "key": "18610698755c8de61207a7",
                "meta": {"href": "/api/configuration/policies/trusted_ca_lists/18610698755c8de61207a7"}
            },
            "username_attribute": "commonName"
        },
        "backend": {
            "selection": "ldap",
            "schema": {
                "selection": "ad",
                "membership_check": {
                    "enabled": true,
                    "nested_groups": false
                },
                "memberof_check": {
                    "enabled": true,
                    "memberof_user_attribute": "memberOf"
                },
                "user_dn_in_groups": []
            },
            "servers": [
                {
                    "host": {
                        "selection": "ip",
                        "value": "10.110.0.1"
                    },
                    "port": 389
                },
                {
                    "host": {
                        "selection": "fqdn",
                        "value": "my.example"
                    },
                    "port": 389
                }
            ],
            "user_base_dn": "ou=People,dc=example",
            "group_base_dn": "ou=Groups,dc=example",
            "bind_dn": "cn=admin,dc=example",
            "bind_password": {
                "key": "XXXXXXXX-XXXX-XXXX-XXXX-XXXXXXXXXXXX",
                "meta": {"href": "/api/configuration/passwords#XXXXXXXX-XXXX-XXXX-XXXX-XXXXXXXXXXXX"}
            },
            "encryption": {
                "selection": "starttls",
                "server_certificate_check": {
                    "enabled": false
                },
                "client_authentication": {
                    "enabled": true,
                    "x509_identity": {
                        "key": "XXXXXXXX-XXXX-XXXX-XXXX-XXXXXXXXXXXX",
                        "meta": {"href": "/api/configuration/x509/XXXXXXXX-XXXX-XXXX-XXXX-XXXXXXXXXXXX"}
                    }
                }
            }
        },
        "require_commitlog": true
    }
}
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 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-win2000-style and Win2003-style account names (User Principal Names), for example administrator@example.com is also accepted.

bind_password string

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

References the password SPS 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: One Identity Safeguard for Privileged Sessions (SPS) accepts passwords that are not longer than 150 characters. Letters A-Z, a-z, numbers 0-9, the space character, as well as 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 SPS and the LDAP server.

selection string

Defines the type of encryption SPS 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.

client_authentication Top level item

Must be used with the selection child element.

Configures the X.509 certificate SPS 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 SPS. 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).

server_certificate_check Top level item

Must be used with the enabled 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.

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:

membership_check Top level element
enabled boolean

POSIX: Enables POSIX primary and supplementary group membership checking.

AD: Enables Active Directory specific non-primary group membership checking.

nested_groups boolean

Must be used if the selection element is set to ad.

Enable nested groups allows AD nested group support.

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.

memberof_check Top level element

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.

enabled boolean

To enable memberof_check, set it to true.

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.

memberof_group_objectclass string

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

The objectClass of the referred groups that can be referred in the memberof_user_attribute.

username_attribute string

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

Username (user ID) attribute name is the name of the attribute in the user object, which contains the user’s plain username.

user_dn_in_groups Top level list

Check the user DN in these groups is a list of additional group object classes and their respective attributes where SPS will look for member user DNs.

Add object_class / attribute pairs. SPS will search for the user DN in the group's attribute defined here.

For example:

"user_dn_in_groups": [
    {
        "object_class": "groupOfNames",
        "attribute": "member"
    },
    {
        "object_class": "groupOfUniqueNames",
        "attribute": "uniqueMember"
    }
]
object_class string Consider groups of this objectClass.
attribute string Name of the group attribute which contains the user DN.
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).

Example: Local user database with password authentication

This example configures a local user database with a password policy to authenticate the users of SPS:

NOTE: One Identity Safeguard for Privileged Sessions (SPS) accepts passwords that are not longer than 150 characters. Letters A-Z, a-z, numbers 0-9, the space character, as well as 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
}
Example: Local user database with RADIUS server

This example configures a local user database with a RADIUS server to authenticate the users of SPS. 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 SPS web interface will be available only after successfully authenticating to the RADIUS server. Note that the default admin account of SPS 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
}
Example: Local user database with X.509 certificates

This example configures a local user database with X.509 certificates to authenticate the users of SPS. 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
}
Example: POSIX LDAP server

NOTE: Consider the following:

  • 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 SPS even if LDAP authentication is used.

  • SPS 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: /\[]:;|=+*?<>"
    • 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.

  • SPS treats user and group names in a case insensitive manner if the matching rule for the attribute in question is case insensitive in the LDAP database.

Caution:

Nested groups 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 SPS 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 SPS 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": {
    "selection": "ldap",
    "user_base_dn": "<base-dn>",
    "group_base_dn": "<base-dn>",
    "bind_dn": "<bind-dn>",
    "bind_password": "<id-of-the-password>",
    "schema": {
      "selection": "posix",
      "username_attribute": "<uid-attr>",
      "membership_check": {
        "enabled": true,
        "member_uid_attribute": "<memberUid-attr>"
      },
      "memberof_check": {
        "enabled": true,
        "memberof_user_attribute": "<user-attr-of-group-dns>",
        "memberof_group_objectclass": "<object-class-of-groups>"
      },
      "user_dn_in_groups": []
    },
    "servers": [
      {
        "host": {
          "selection": "ip",
          "value": "<ip-of-server>"
        },
        "port": <port>
      }
    ],
    "encryption": {
      "selection": "disabled"
    }
  },
  "method": {
    "selection": "passwd"
  },
  "require_commitlog": false
}
Example: Microsoft Active Directory server

NOTE: Consider the following:

  • 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 SPS even if LDAP authentication is used.

  • SPS 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: /\[]:;|=+*?<>"
    • 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.

  • SPS treats user and group names in a case insensitive manner if the matching rule for the attribute in question is case insensitive in the LDAP database.

Caution:

Nested groups 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 SPS 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 SPS 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": {
    "selection": "ldap",
    "user_base_dn": "<base-dn>",
    "group_base_dn": "<base-dn>",
    "bind_dn": "<bind-dn>",
    "bind_password": "<id-of-the-password>",
    "schema": {
      "selection": "ad",
      "membership_check": {
        "enabled": true,
        "nested_groups": true
      },
      "memberof_check": {
        "enabled": true,
        "memberof_user_attribute": "<user-attr-of-group-dns>"
      },
      "user_dn_in_groups": []
    },
    "servers": [
      {
        "host": {
          "selection": "ip",
          "value": "<ip-of-server>"
        },
        "port": <port>
      }
    ],
    "encryption": {
      "selection": "starttls",
      "server_certificate_check": {
        "enabled": true,
        "server_certificate_ca": "<cert>"
      },
      "client_authentication": {
        "enabled": true,
        "x509_identity": "<id-of-the-cert-and-key>"
      }
    }
  },
  "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-SPS>/api/configuration/aaa/settings endpoint. You can find a detailed description of the available parameters listed in Element .

  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 Application level error codes.

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.
Related Documents

The document was helpful.

Select Rating

I easily found the information I needed.

Select Rating