Chat now with support
Chat mit Support

One Identity Safeguard for Privileged Sessions 6.0.12 - 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 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

Traffic alerts

Configuration options for sending traffic-related alerts.

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

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

URL
GET https://<IP-address-of-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).
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:

  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/alerting/traffic_alerts 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.
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

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

Authentication and user database settings

Contains settings for authenticating to 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. 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. 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:

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

The document was helpful.

Bewertung auswählen

I easily found the information I needed.

Bewertung auswählen