One Identity Safeguard for Privileged Sessions 6.0.4

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-SPS>/api/configuration/alerting/traffic_alerts

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

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 configuration options for traffic-related alerts..

curl --cookie cookies https://<IP-address-of-SPS>/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 Message format.

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

Open a transaction.

For details, see Open a transaction.
Modify the JSON object of the endpoint.

PUT the modified JSON object to the https://<IP-address-of-SPS>/api/configuration/alerting/traffic_alerts endpoint. You can find a detailed description of the available parameters listed in Element .
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.
401	AuthenticationFailure	Authenticating the user with the given credentials has failed.
404	NotFound	The requested object does not exist.

User management and access control

Topics:

User management and access control

Authentication and user database settings

Privileges of usergroups

Audit data access rules

Active sessions

Manage users and usergroups locally on SPS

Manage usergroups locally on SPS

Manage users locally on SPS

User management and access control

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

Cookie name

Description

Required

Values

session_id

Contains the authentication token of the user

Required

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.
401	AuthenticationFailure	Authenticating the user with the given credentials has failed.
404	NotFound	The requested object does not exist.

Authentication and user database settings

User management and access control > 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).

Cookie name

Description

Required

Values

session_id

Contains the authentication token of the user

Required

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

ad: Microsoft Active Directory server. For details and examples, see Example: Microsoft Active Directory server.
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 Example: POSIX LDAP server.

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.

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

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:

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:

Open a transaction.

For details, see Open a transaction.
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 .
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.
401	AuthenticationFailure	Authenticating the user with the given credentials has failed.
404	NotFound	The requested object does not exist.

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 6.0.4 - REST API Reference Guide

Traffic alerts

URL

Cookies

Sample request

Response

Modify a traffic-related alert

Open a transaction.

Modify the JSON object of the endpoint.

Commit your changes.

Status and error codes

User management and access control

Topics:

User management and access control

URL

Cookies

Sample request

Response

Status and error codes

Authentication and user database settings

URL

Cookies

Sample request

Response

Example: Local user database with password authentication

Example: Local user database with RADIUS server

Example: Local user database with X.509 certificates

Example: POSIX LDAP server

Example: Microsoft Active Directory server

Modify the authentication and user database settings

Open a transaction.

Modify the JSON object of the endpoint.

Commit your changes.

Status and error codes