Chat now with support
Chat with Support

One Identity Safeguard for Privileged Sessions 7.5 - 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, retrieve, download, and index sessions Reporting Health and maintenance Advanced authentication and authorization Completing the Welcome Wizard using REST Enable and configure analytics using REST REST API examples

Manage usergroups locally on SPS

Contains the local usergroups of SPS. You can use local groups to control the privileges of SPS local and LDAP users — who can view and configure what. You can edit the group memberships here as well.

Note that currently you cannot edit the privileges (ACLs) of the groups using the REST API. If you change the privileges of a usergroup on the SPS web interface, the changes will apply to the users when they authenticate again on SPS, the privileges of active sessions are not affected.

URL
GET https://<IP-address-of-SPS>/api/configuration/aaa/local_database/groups
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 more information on authentication, see Authenticate to the SPS REST API.

NOTE: 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 local usergroups.

curl --cookie cookies.txt https://<IP-address-of-SPS>/api/configuration/aaa/local_database/groups
Response

The following is a sample response received when querying a particular usergroup endpoint.

For more information on the meta object, see Message format.

{
    "body": {
        "members": [],
        "name": "http-write"
    },
    "key": "ca2dc85730ca082ee6b5c8",
    "meta": {
        "first": "/api/configuration/aaa/local_database/groups/224696054489c27f6c5710",
        "href": "/api/configuration/aaa/local_database/groups/ca2dc85730ca082ee6b5c8",
        "last": "/api/configuration/aaa/local_database/groups/ca2dc85730ca082ee6b5f8",
        "next": "/api/configuration/aaa/local_database/groups/b080b1ba546232548bb1f9",
        "parent": "/api/configuration/aaa/local_database/groups",
        "previous": "/api/configuration/aaa/local_database/groups/b080b1ba546232548bb1a9",
        "transaction": "/api/transaction"
    }
}
Element Type Description
body Top level element (JSON object) Contains the properties of the usergroup.
members list Lists the names of the users belonging to the group.
name string The name of the group.
key string Top level element, contains the ID of the endpoint.
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.
409 NoTransaction No open Transaction is available. You must open a transaction first (for details, see Open a transaction).
Add new local usergroup

To create a new local usergroup, you have to POST the name and members of the group as a JSON object to the https://<IP-address-of-SPS>/api/configuration/aaa/local_database/groups endpoint. For details, see Create a new object.

  1. Open a transaction.

    For details, see Open a transaction.

  2. Create a new usergroup.

    POST the name of the group and the list of member accounts as a JSON object to the https://<IP-address-of-SPS>/api/configuration/aaa/local_database/groups endpoint. The body of the POST request should be the following. Note that you must refer to existing user accounts, and use their reference IDs, not their usernames.

    {
        "name": "new-userggroup",
        "members": ["46785097158061f46c63d0", "1362061674580df4e00620d"]
    }

    For example:

    curl -X POST -H "Content-Type: application/json" --cookie cookies.txt https://<IP-address-of-SPS>/api/configuration/aaa/local_database/groups --data '{"name": "new-usergroup", "members": ["46785097158061f46c63d0", "1362061674580df4e00620d"]}'

    If the POST request is successful, the response includes a reference ID for the usergroup object.

  3. Commit your changes.

    For details, see Commit a transaction.

Delete usergroup

To delete a usergroup, you have to:

  1. Open a transaction (for details, see Open a transaction).

  2. DELETE the https://<IP-address-of-SPS>/api/configuration/aaa/local_database/groups/<ID-of-the-group> endpoint. For details, see Delete an object. If the DELETE request is successful, the response includes only the meta object, for example:

    {
        "meta": {
            "href": "/api/configuration/aaa/local_database/groups/b080b1ba546232548bb1a9",
            "parent": "/api/configuration/aaa/local_database/groups"
        }
    }
  3. Commit your changes to actually delete the object from SPS (for details, see Commit a transaction).

Delete user from usergroup

To delete a user from a usergroup, you have to:

  1. Open a transaction (for details, see Open a transaction).

  2. Create an updated version of the usergroup object that does not include the user you want to delete.

  3. PUT the updated usergroup object to the https://<IP-address-of-SPS>/api/configuration/aaa/local_database/groups/<ID-of-the-group> endpoint. For details, see Delete an object.

  4. Commit your changes to actually delete the object from SPS (for details, see Commit a transaction).

Manage users locally on SPS

Contains the local users of SPS. You can use local users and groups to control the privileges of SPS local and LDAP users — who can view and configure what.

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

Local users cannot be managed when LDAP authentication is used. When LDAP authentication is enabled, the accounts of local users is disabled, but they are not deleted,

When using RADIUS authentication together with local users, the users are authenticated to the RADIUS server, only their group memberships must be managed locally on SPS.

For details, see Login settings.

URL
GET https://<IP-address-of-SPS>/api/configuration/aaa/local_database/users
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 more information on authentication, see Authenticate to the SPS REST API.

NOTE: 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 local users.

curl --cookie cookies.txt https://<IP-address-of-SPS>/api/configuration/aaa/local_database/users

The following command displays the parameters of a specific user.

curl --cookie cookies.txt https://<IP-address-of-SPS>/api/configuration/aaa/local_database/users/<ID-of-the-user>
Response

The following is a sample response received when querying the list of users.

For more information on the meta object, see Message format.

{
    "items": [
        {
            "key": "103640099357f3b14f0529a",
            "meta": {
                "href": "/api/configuration/aaa/local_database/users/103640099357f3b14f0529a"
            }
        },
        {
            "key": "46785097158061f46c63d0",
            "meta": {
                "href": "/api/configuration/aaa/local_database/users/46785097158061f46c63d0"
            }
        }
    ],
    "meta": {
        "first": "/api/configuration/aaa/local_database/groups",
        "href": "/api/configuration/aaa/local_database/users",
        "last": "/api/configuration/aaa/local_database/users",
        "next": null,
        "parent": "/api/configuration/aaa/local_database",
        "previous": "/api/configuration/aaa/local_database/groups",
        "transaction": "/api/transaction"
    }
}

The following is a sample response received when querying a specific user.

{
    "body": {
        "name": "testuser",
        "password": {
            "key": "8f84d7d1-9de1-429a-a7a7-c33a61cc7419",
            "meta": {
                "href": "/api/configuration/passwords/8f84d7d1-9de1-429a-a7a7-c33a61cc7419"
            }
        },
        "password_created": 1476796261
    },
    "key": "46785097158061f46c63d0",
    "meta": {
        "first": "/api/configuration/aaa/local_database/users/103640099357f3b14f0529a",
        "href": "/api/configuration/aaa/local_database/users/46785097158061f46c63d0",
        "last": "/api/configuration/aaa/local_database/users/46785097158061f46c63d0",
        "next": null,
        "parent": "/api/configuration/aaa/local_database/users",
        "previous": "/api/configuration/aaa/local_database/users/103640099357f3b14f0529a",
        "transaction": "/api/transaction"
    }
Element Type Description
body Top level element (JSON object) Contains the properties of the user.
name string The username of the user account.
password reference A reference to a password object. To create or update passwords, see Passwords stored on SPS.
password_created integer The date when the password of the account was changed in UNIX timestamp format (for example, 1476796261).
key string Top level element, contains the ID of the user.
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 SemanticError You tried to reuse a password object. You can use a password object for only one purpose, that is, you cannot reference a password object twice.
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.
409 NoTransaction No open Transaction is available. You must open a transaction first (for details, see Open a transaction).

Configuring LDAP servers

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

URL
POST https://<IP-address-of-SPS>/api/configuration/aaa/ldap_servers
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 more information on authentication, see Authenticate to the SPS REST API.

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

Operations with the /aaa/ldap_servers endpoint include:

Operation HTTP method URL

Notes

Creating a new LDAP server POST /api/configuration/aaa/ldap_servers

 

Retrieving a LDAP server

GET

 

Sample request

The following command creates a new LDAP server.

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

The following is a sample request.

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

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

For more information on the meta object, see Message format.

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

Elements of the response message body include:

Element

Type

Description

Notes

bind_dn

string

The Distinguished Name that SPS should use to bind to the LDAP directory.

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

NOTE: SPS accepts both pre Windows 2000-style and Windows 2003-style account names, or User Principal Names (UPNs). For example, administrator@example.com is also accepted.

bind_password null | string

References the password SPS uses to authenticate on the server. You can configure passwords at the /api/configuration/passwords/ endpoint.

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

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

NOTE: SPS accepts passwords that are not longer than 150 characters and supports the following characters:

  • Letters A-Z, a-z

  • Numbers 0-9

  • The space character

  • Special characters: !"#$%&'()*+,-./:;<>=?@[]\^-`{}_|

encryption union

Configuration settings for encrypting the communication between SPS and the LDAP server.

The displayed value type depends on the encryption.selection parameter.

encryption.selection enum

Defines the type of encryption SPS uses to communicate with the LDAP server. Possible values are:

  • disabled

    The communication is not encrypted.

  • ssl

    TLS/SSL encryption. To use a TLS-encrypted with certificate verification to connect to the LDAP server, use the full domain name (for example ldap.example.com) as the server address, otherwise the certificate verification might fail. The name of the LDAP server must appear in the Common Name of the certificate.

  • starttls

    Opportunistic TLS.

  • Example if the value is disabled

    {
      "selection": "disabled"
    }
  • Example if the value is ssl or starttls:

    {
      "selection": "ssl | starttls",
      "trust_store": null|<trust-store-ref>,
      "client_authentication": null|<x509-ref>
    }

group_base_dn

string

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

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

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

Example:

"ou=users,ou=example"

name

string

Top level element, the name of the object. This name is also displayed on the SPS web interface. It cannot contain whitespace.

 

schema

union

AD and POSIX specific LDAP configuration.

  • Example with LDAP AD server, where the schema selection is ad:

    {
      "selection": "ad",
      "membership_check": ...,
      "memberof_check": ...,
      "user_dn_in_groups": …
    }			
  • Example with LDAP POSIX server, where the schema selection is posix:

    {
      "selection": "posix",
      "membership_check": ...,
      "memberof_check": ...,
      "user_dn_in_groups": ...,
      "username_attribute": …
    }

schema.memberof_check

object

The Enable checking for group DNs in user objects setting allows checking a configurable attribute in the user object. This attribute contains a list of group DNs the user is additionally a member of. This user attribute is usually memberOf.

  • Example with LDAP AD server, if memberof_check and memberof_user_attribute are enabled:

    "schema": {
                   "memberof_check": {
                     "enabled": true,
                     "memberof_user_attribute": "memberOf"
                   }
  • Example with LDAP POSIX server, if memberof_check is enabled:

    "schema": {
                   "memberof_check": {
                     "enabled": true,
                     "memberof_group_objectclass": "groupOfNames",
                     "memberof_user_attribute": "memberOf"
                   }
  • To disable memberof_check for both LDAP AD and LDAP POSIX servers, set the enabled parameter to false.

    "schema": {
                   "memberof_check": {
                     "enabled": false
                   }

schema.memberof_check.enabled

boolean

To enable memberof_check, set it to true.

 

schema.memberof_check.memberof_group_objectclass

string

The attribute holding the members of the LDAP group.

This field is case-sensitive.

Default value: groupOfNames

schema.memberof_check.memberof_user_attribute

string

Must be used if the memberof_check is set to true. The name of the user attribute (for example, memberOf) that contains the group DNs.

This attribute is the same for both LDAP AD and LDAP POSIX schema.

schema.membership_check

object

  • POSIX: POSIX primary and supplementary group membership checking.

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

  • Example with LDAP AD server, if membership_check and nested_groups are enabled:

    "membership_check": {
                    "enabled": true,
                    "nested_groups": true | false"
                  }
  • Example with LDAP POSIX server, if membership_check and member_uid_attribute are enabled:

    "membership_check": {
                    "enabled": true,
                    "member_uid_attribute": null | "memberUid"
                  }
  • To disable membership_check for both LDAP AD and LDAP POSIX servers, set the enabled parameter to false.

    "membership_check": {
                    "enabled": false
                  }

schema.membership_check.enabled

boolean

POSIX: Enables POSIX primary and supplementary group membership checking.

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

 

schema.membership_check.member_uid_attribute

string

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

The POSIX group membership attribute name is the name of the attribute in a posixGroup group object, which lists the plain usernames that are members of the group. These groups are usually referred to as supplementary groups of the referred user. Can be null.

Default value: memberUid

schema.selection

string

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

  • ad: Microsoft Active Directory server. For details and examples, see Configuring LDAP servers.

  • posix: The server uses the POSIX LDAP scheme.

    Must be used with the member_uid_attribute and username_attribute elements. For details and examples, see Configuring LDAP servers.

Default value: ad, posix

schema.user_dn_in_groups

array

Add object_class / attribute pairs. SPS will search for the user DN in the group's attribute defined here. If it finds the user DN there, SPS considers the user the member of that group.

Example:

"user_dn_in_groups": [
                  {
                    "attribute": "member",
                    "object_class": "groupOfNames"
                  },
                  {
                    "attribute": "uniqueMember",
                    "object_class": "groupOfUniqueNames"
                  }
                ]

The array can return empty:

"user_dn_in_groups": []

user_dn_in_groups can serve as additional validation. At least one out of membership_check, memberof_check or user_dn_in_groups must be filled for validation.

schema.user_dn_in_groups.attribute

string

Name of the group attribute which contains the user DN.

Default value: member

schema.user_dn_in_groups.object_class

string

Consider groups of this objectClass.

Possible values: groupOfNames, groupOfUniqueNames

schema.username_attribute

string

The login attribute that uniquely identifies a single user record.

Default value: uid

servers

array

Contains the addresses and ports of the LDAP servers.

The displayed value type depends on the servers.host.selection parameter.

Possible values are: ip, fqdn

  • Example if the host selection is ip:

    "servers": [
                    {
                      "host":{
                        "selection": "ip",
                        "value": "1.2.3.4"
                      },
                      "port": 123
                    }
                  ],
    
  • Example, if the host selection is fqdn:

    "servers": [
                    {
                      "host": {
                        "selection": "fqdn",
                        "value": "my.example"
                      },
                      "port": 123
                    }
                  ],
    

servers.host

object

Contains the address of the LDAP server.

 

servers.host.selection

string

Defines the address type (IP or domain name).

Possible values are:

  • fqdn

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

  • ip

    The LDAP server address is provided as an IP address.

servers.host.value

string

The address of the LDAP server.

 

servers.port

int

The port of the LDAP server.

 

user_base_dn

string

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

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

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

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

For example:

"ou=groups,ou=example"
Configure LDAP servers

To configure an LDAP server, you have to:

  1. Open a transaction.

    For more information, see Open a transaction.

  2. Create the JSON object for the new LDAP server configuration.

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

  3. Commit your changes.

    For more information, see Commit a transaction.

HTTP response codes

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

Configuring SPS login methods

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

  • Local login

  • LDAP login (AD or POSIX)

  • X.509 login

  • RADIUS login

  • SAML2 login (Security Assertion Markup Language 2.0)

URL
https://<IP-address-of-SPS>/api/configuration/aaa/login_methods
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 more information on authentication, see Authenticate to the SPS REST API.

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

HTTP operations

HTTP operations with the /aaa/login_methods endpoint include:

HTTP method

URL

Description

Notes

POST

/api/configuration/aaa/login_methods

Configuring the local login method

NOTE: Changing your password is possible only with Local login.

 

 

Configuring the X.509 login method

Before you can configure the X.509 login method, you must upload your X.509 certificate to a trust store at the /api/configuration/trust_stores endpoint.

 

 

Configuring the password-based LDAP login method (AD or POSIX)

Before you can configure the LDAP login method, you must create a new LDAP server at the /api/configuration/aaa/ldap_servers endpoint.

 

 

Configuring the RADIUS login method

 

 

 

Configuring the SAML2 login method

 

PUT

/api/configuration/aaa/login_methods/@order

Reordering login methods

By default, the Local login method button appears as the first login method on the SPS web interface. To reorder the login method buttons, use the /@order endpoint.

Sample request

The following command creates a new login method.

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

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

Element

Type

Description

Notes

type

enum

The login method type used for authentication.

Possible values are:

  • local

    Use a local user database for authentication.

  • x509

    Use a X.509 certificate for authentication.

  • ldap

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

  • radius

    Use a RADIUS server for authentication.

name

string

A unique identifier of the login method.

title

string

The title that appears above the login method button on the SPS web interface. This can be customized. In the case of X.509 login method, there is only one button.
active

boolean

Indicates whether the login method is enabled or not.

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

Elements of the request message body include:

Element

Type

Description

Notes

cracklib_enabled

boolean

Password setting. Must be used if the value of the selection element is set to local.

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

Set to false if a RADIUS server or X.509 certificate is used for authentication.

NOTE: The strength of a password is determined by its length and complexity: the variety of numbers, letters, capital letters, and special characters used.

To run simple dictionary-based attacks to find weak passwords, enable Cracklib (eg. dictionary) protection.

expiration_days

integer

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

Set to 0 if a RADIUS server or X.509 certificate is used for authentication.

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

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

remember_previous_passwords

integer

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

Set to 0 if a RADIUS server or X.509 certificate is used for authentication.

The 0 value means passwords can be reused.

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

minimum_password_strength

string

Password setting. Configures the required password strength for new passwords.

Set to disabled if a RADIUS server or X.509 certificate is used for authentication.

Possible values are:

  • disabled

    Any password is accepted.

  • good

    Weak passwords are not accepted.

  • strong

    Only strong passwords are accepted.

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

minimum_password_length

number

The minimum number of characters the password must consist of.

 

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

Elements of the request message body include:

Element

Type

Description

Notes

ldap_server

string

The identifier of the previously created LDAP server.

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

Elements of the request message body include:

Element

Type

Description

Notes

trust_store

string

The identifier of the X509 certificate that was previously uploaded into Trust stores.

Trust stores serve as local certificate storages where users can store the certificate chains of trusted Certificate Authorities (CAs).

username_attribute

enum

The login attribute that uniquely identifies a single user record. You can choose which type of username you want to use.

Possible values are:

  • commonName

  • emailAddress

  • userId

  • userPrincipalName

groups

object

The location of your group from which you will authorize access.  
groups.type

enum

The type of the group.

Possibe values are:

  • local
  • ldap

If the group type is ldap, the identifier of the previously created LDAP server (the value of the ldap_server field) will appear.

Example: Sample request for configuring SAML2 login
{
                "type": "saml2",
                "name": "saml_idp",
                "title": "SAML IdP",
                "active": true,
                "groups": {
                    "type": "local"
                },
                "idp_metadata": "<?xml version=\"1.0\" encoding=\"UTF-8\"?><md:EntityDescriptor entityID=\"http:\/\/www.okta.com\/exk4qxi1pzvjH2zBZ5d7\" xmlns:md=\"urn:oasis:names:tc:SAML:2.0:metadata\"><md:IDPSSODescriptor WantAuthnRequestsSigned=\"false\" protocolSupportEnumeration=\"urn:oasis:names:tc:SAML:2.0:protocol\"><md:KeyDescriptor use=\"signing\"><ds:KeyInfo xmlns:ds=\"http:\/\/www.w3.org\/2000\/09\/xmldsig#\"><ds:X509Data><ds:X509Certificate>MIIDpjCCAo6gAwIBAgIGAXjzrIibMA0GCSqGSIb3DQEBCwUAMIGTMQswCQYDVQQGEwJVUzETMBEG\nA1UECAwKQ2FsaWZvcm5pYTEWMBQGA1UEBwwNU2FuIEZyYW5jaXNjbzENMAsGA1UECgwET2t0YTEU\nMBIGA1UECwwLU1NPUHJvdmlkZXIxFDASBgNVBAMMC2Rldi00NzkyNDAyMRwwGgYJKoZIhvcNAQkB\nFg1pbmZvQG9rdGEuY29tMB4XDTIxMDQyMTA5MDMzM1oXDTMxMDQyMTA5MDQzM1owgZMxCzAJBgNV\nBAYTAlVTMRMwEQYDVQQIDApDYWxpZm9ybmlhMRYwFAYDVQQHDA1TYW4gRnJhbmNpc2NvMQ0wCwYD\nVQQKDARPa3RhMRQwEgYDVQQLDAtTU09Qcm92aWRlcjEUMBIGA1UEAwwLZGV2LTQ3OTI0MDIxHDAa\nBgkqhkiG9w0BCQEWDWluZm9Ab2t0YS5jb20wggEiMA0GCSqGSIb3DQEBAQUAA4IBDwAwggEKAoIB\nAQCV8kFXnxvMmTBlOPGk0qUsO12vqUKdRXvbYke0xzpdsgk1xyGMDxLms6zdrlisgTFvP+N0CO4n\nYoZ\/gFbsIlQN7YCvV0P7Tm4vbCdL08GpFJllmougTQvXMCGmPZyuAA8aEKDbITD5vDjLRMiAzuP6\nt8WNocRzsBZCLoN0AEdCkjGArNzg9XeNef\/89YEvKtJKRyFk2uxjn7vakYwekjgXNRKTAYvtvwDt\n10qNc1fEhZ+H8h6zqACQH+AehJRIY1atYscQm1XhsDXu2s9Vz8W5M6WtflQD6rxKIB8q64scpk8F\nPcuv327sjdTL2BjmzWjOekdjr9WUkxJJ1hZXGHHbAgMBAAEwDQYJKoZIhvcNAQELBQADggEBAG42\nISgPo0uypP5rc451JQVfSiY9+Bg+UoekGZKksm9NA1XHJKAd7+OAuZe9OeTXKaB6KtImphl95xe1\nVyvKPwZhNo91QoP6SMwUwES8A45j2\/2vi87Y2\/V5nEAahNy3Kcvl8v8MghIZja1F\/rZu3ha51sl5\n\/k6G7CG3mi1MknC0\/kNSw+FrVcAuJOqnJEUDvWBcoJ4NCVcGddmqHpLuESHswnMH03HRPgVI1b8M\nLnPrgvZfEEQV\/dIIDR9AOl9dmKG\/7HpL+gL8L5J1r3PSFN0kPTlXbZFIiUfAPKJuSxm4WgMWdCiT\nCT1H\/87qV0GjNmdMBU9IFlHBYi4eLzv5VZo=<\/ds:X509Certificate><\/ds:X509Data><\/ds:KeyInfo><\/md:KeyDescriptor><md:NameIDFormat>urn:oasis:names:tc:SAML:1.1:nameid-format:emailAddress<\/md:NameIDFormat><md:SingleSignOnService Binding=\"urn:oasis:names:tc:SAML:2.0:bindings:HTTP-POST\" Location=\"https:\/\/dev-4792402.okta.com\/app\/dev-4792402_ztsscb2_1\/exk4qxi1pzvjH2zBZ5d7\/sso\/saml\"\/><md:SingleSignOnService Binding=\"urn:oasis:names:tc:SAML:2.0:bindings:HTTP-Redirect\" Location=\"https:\/\/dev-4792402.okta.com\/app\/dev-4792402_ztsscb2_1\/exk4qxi1pzvjH2zBZ5d7\/sso\/saml\"\/><\/md:IDPSSODescriptor><\/md:EntityDescriptor>"
            }

Elements of the request message body include:

Element

Type

Description

Notes

groups

object

The location of your group from which you will authorize access.  

groups.type

enum

The type of the group.

Possibe values are:

  • local
  • ldap

If the group type is ldap, the identifier of the previously created LDAP server (the value of the ldap_server field) will appear.

idp_metadata

 

Metadata XML of the Identity Provider.

You must upload the metadata XML file contents as a properly escaped JSON string.

Example: Configuring X.509 login with LDAP groups

To configure an X.509 login with LDAP groups

  1. Open a transaction

    For more information, see Open a transaction.

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

    {
         "name": "ldap_server",
         "schema": {
             "selection": "posix",
             "username_attribute": "uid",
             "membership_check": {
                 "enabled": true,
                 "member_uid_attribute": "memberUid"
             },
             "memberof_check": {
                 "enabled": true,
                 "memberof_user_attribute": "memberOf",
                 "memberof_group_objectclass": "groupOfNames"
             },
             "user_dn_in_groups": [
                 {
                     "object_class": "groupOfNames",
                     "attribute": "member"
                 },
                 {
                     "object_class": "groupOfUniqueNames",
                     "attribute": "uniqueMember"
                 }
             ]
         },
         "servers": [
             {
                 "host": {
                     "selection": "ip",
                     "value": "1.2.3.4"
                 },
                 "port": 389
             }
         ],
         "user_base_dn": "ou=People,dc=example",
         "group_base_dn": "ou=Groups,dc=example",
         "bind_dn": null,
         "bind_password": null,
         "encryption": {
             "selection": "disabled"
         }
    }
  3. Upload a X509 certificate at the /api/configuration/trust_stores endpoint.

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

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

    For more information, see Commit a transaction.

Example: Configuring RADIUS login with local groups

To configure a RADIUS login with local groups

  1. Open a transaction

    For more information, see Open a transaction.

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

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

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

    For more information, see Commit a transaction.

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

To configure a RADIUS login with LDAP groups

  1. Open a transaction

    For more information, see Open a transaction.

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

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

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

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

    For more information, see Commit a transaction.

Example: Configuring SAML2 login

To configure a SAML2 login

  1. Open a transaction

    For more information, see Open a transaction.

  2. Download the metadata XML of your Identity Provider.

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

  4. Commit your changes

    For more information, see Commit a transaction.

Response

For more information on the meta object, see Message format.

HTTP response codes

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

Related Documents

The document was helpful.

Select Rating

I easily found the information I needed.

Select Rating