One Identity Safeguard for Privileged Sessions 7.0.5.1 LTS

Prerequisites

The REST server must permit password authentication to the SPS web interface. If only certificate-based authentication is permitted, see Authenticate to the SPS REST API using X.509 certificate.

The authentication procedure:

To authenticate on the SPS REST server, send a GET request over HTTPS using the basic HTTP authentication method, including your username and password to the /api/authentication resource.
If the authentication is successful, the server returns the 200 status code, and a meta object in the response body. Also, the HTTP headers of the response include an HTTP cookie named session_id. This cookie is used to identify the client in every subsequent HTTP request.
For every subsequent request, include the session_id header with the value of the received session ID. For example:
```
session_id 087658d7e30cdc2552b015dd761b6f7ccb25bbd5
```
The authenticated session times out after 20 minutes of inactivity.

URL

GET https://<IP-address-of-SPS>/api/authentication

Headers

Header name	Description	Required	Values
Authorization	Contains the username and password of the user	Required	The string Basic followed by the username:password encoded using the RFC2045-MIME. For example, Basic YWRtaW46YQ==

Sample request

Example: Authenticate to the SPS REST server using curl

The following command authenticates on SPS using the curl HTTP client. The --insecure option used in the example is used to bypass verifying the certificate of SPS. (Alternatively, you can use the --cacert option or the CURL_CA_BUNDLE environment variable to specify the Certificate Authority to verify the certificate of SPS. For details, see the curl man page).

When using the REST API in production environments, make sure to download the CA certificate of SPS from Basic Settings > Management > SSL certificate > CA X.509 certificate, and validate the certificate of SPS using this CA certificate, or with the CA certificate you used to sign the Server X.509 certificate of SPS.

curl --basic --user <username>:<password> --cookie-jar cookies --insecure https://<SPS-IP-address>/api/authentication

The cookie containing the session ID is also received (you can display it for example with the tail -l cookies command).

localhost  FALSE  /  FALSE  1395325830  session_id  600dc0ffeec0ffeec0ffeec0ffeec0ffeec0ffee

The following command retrieves the configuration of SPS, using the session ID received during the authentication.

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

Response

The following is a sample response received if the authentication is successful.

{
  "meta": {
     "href": "/api",
     "next": "/api",
     "transaction": "/api/transaction"
  }
}

Authenticate with SPS login methods

You can use different login methods (local, LDAP, RADIUS, or X.509) to authenticate to SPS. To determine which login methods are available to you on SPS, use the Listing SPS login methods endpoint to list them.

URL

https://<IP-address-of-SPS>/api/authentication?login_method=<name-of-the-login-method>&type=<password|x509>

Query parameters related to the /authentication endpoint:

```
?type=<password|x509>
```
Where each value indicates the means of authentication to SPS:
- password - You have to send the username and password in a Basic Authorization header.
- x509 - You have to identify yourself with a client certificate
```
?login_method=<name-of-the-login-method>
```
A unique identifier for the login method. For example, x509_with_ldap_groups_name.

Example: Authenticating with password

The following command authenticates the user to SPS with local login.

curl --user <username>:<password> https://<IP-address-of-SPS>/api/authentication?login_method=example_login_method&type=password

Example: Authenticating with a x509 certificate

The following command authenticates the user to SPS with a x509 certificate.

curl --key <private-key.pem> --cert <x509-certificate.pem> https://<IP-address-of-SPS>/api/authentication?login_method=example_login_method&type=x509

Response

In all four examples, the following sample response is received if the authentication is successful.

{

"meta": {

    "href": "/api/authentication",

    "next": "/api",

    "remaining_seconds": 600,

    "transaction": "/api/transaction"

}

The HTTP response code is 302 Moved Temporarily. An HTTP response with this status code provides a redirect URL in the header field Location.

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

Code	Description	Notes
200	OK	Successful authentication
400	InvalidAuthenticationRequest	Unable to authenticate: no valid credentials found.
401	AuthenticationFailure	Authenticating the user with the given credentials has failed.
405	MethodNotAllowed	You tried using an unsupported HTTP method. Use the GET method for authentication.

Authenticate to the SPS REST API using X.509 certificate

Prerequisites

The REST server must permit certificate authentication to the SPS web interface. If only password-based authentication is permitted, see Authenticate to the SPS REST API.

The authentication procedure:

To authenticate on the SPS REST server, send an HTTPS GET request, including your certificate to the /api/authentication?type=x509 resource. The certificate must be signed by the Trusted CA certificate that is configured on the Users & Access Control > Settings > X.509 > AUTHENTICATION CA field of the SPS web interface, or the /api/configuration/aaa/settings resource.
If the authentication is successful, the server responds with an HTTP 302 redirect to the /api/ resource, and also , sets an HTTP cookie named session_id. This cookie is used to identify the client in every subsequent HTTP request. The response body also includes a meta object.
For every subsequent request, include the session_id header with the value of the received session ID. For example:
```
session_id 087658d7e30cdc2552b015dd761b6f7ccb25bbd5
```
The authenticated session times out after 20 minutes of inactivity.

URL

GET https:<IP-address-of-SPS>/api/authentication

Headers

Header name	Description	Required	Values
Authorization	Contains the username and password of the user	Required	The string Basic followed by the username:password encoded using the RFC2045-MIME. For example, Basic YWRtaW46YQ==

Sample request

Example: Authenticate to the SPS REST server using curl

The following command authenticates on SPS using the curl HTTP client. The --insecure option used in the example is used to bypass verifying the certificate of SPS. (Alternatively, you can use the --cacert option or the CURL_CA_BUNDLE environment variable to specify the Certificate Authority to verify the certificate of SPS. For details, see the curl man page).

curl --basic --user <username>:<password> --cookie-jar cookies --insecure https://<SPS-IP-address>/api/authentication

The cookie containing the session ID is also received (you can display it for example with the tail -l cookies command).

localhost  FALSE  /  FALSE  1395325830  session_id  600dc0ffeec0ffeec0ffeec0ffeec0ffeec0ffee

The following command retrieves the configuration of SPS, using the session ID received during the authentication.

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

Response

The following is a sample response received if the authentication is successful.

{
  "meta": {
     "href": "/api",
     "next": "/api",
     "transaction": "/api/transaction"
  }
}

Code	Description	Notes
302	OK	Successful authentication. If the authentication is successful, the server returns the 302 status code, and a meta object in the response body. Also, the HTTP headers of the response include an HTTP cookie named session_id. This cookie is used to identify the client in every subsequent HTTP request. The Location header in the response is /api/.
400	InvalidAuthenticationRequest	Unable to authenticate: no valid credentials found. SPS returns this message if password fallback is enabled for the admin user, but the admin tries to authenticate with a certificate on the /api/authentication endpoint. To authenticate with a certificate, use the /api/authentication?type=x509 endpoint.
401	AuthenticationFailure	Authenticating the user with the given credentials has failed.
405	MethodNotAllowed	You tried using an unsupported HTTP method. Use the GET method for authentication.

Listing SPS login methods

List login methods (local, LDAP, RADIUS, or X.509) to determine which login methods are available to you to authenticate to SPS. For more information on authentication, see Authenticate to the SPS REST API.

URL

GET https://<IP-address-of-SPS>/api/authentication/login_methods

Sample request

The following command lists available login methods in SPS.

curl -X GET https://<IP-address-of-SPS>/api/authentication/login_methods

Response

The following is a sample response received if the request is successful.

 {

                "login_methods": [

                    {

                        "name": "local",

                        "title": "Local login",

                        "authentication": "local",

                        "credential": "password"

                    },

                    {

                        "name": "x509_name",

                        "title": "X509 login",

                        "authentication": "x509",

                        "credential": "x509"

                    },

                    {

                        "name": "x509_with_ldap_groups_name",

                        "title": "X509 login ldap groups",

                        "authentication": "x509",

                        "credential": "x509"

                    },

                    {

                        "name": "radius_with_local_groups_name",

                        "title": "Radius login with local groups",

                        "authentication": "radius",

                        "credential": "password"

                    },

                    {

                        "name": "radius_with_ldap_groups_name",

                        "title": "Radius login with ldap groups",

                        "authentication": "radius",

                        "credential": "password"

                    },

                ],

                "meta": {

                    "href": "/api/authentication/login_methods",

                    "next": "/api/authentication"

                }

            }

Elements of the response message body include:

Element	Type	Description	Notes
login_methods	object array	A list of available SPS login methods.
login_methods.name	string	A unique identifier for the login method.
login_methods.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.
login_methods.authentication	enum	The login method used for authentication.
credential	enum	The type of credential used for authentication.	Possible values are: password Send the username and password in a Basic Authorization header. x509 Use a X.509 certificate for authentication.

HTTP response codes

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

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

Using the SPS REST API

Authenticate to the SPS REST API

Prerequisites

The authentication procedure:

URL

Headers

Sample request

Example: Authenticate to the SPS REST server using curl

Response

Authenticate with SPS login methods

URL

Example: Authenticating with password

Example: Authenticating with a x509 certificate

Response

Authenticate to the SPS REST API using X.509 certificate

Prerequisites

The authentication procedure:

URL

Headers

Sample request

Example: Authenticate to the SPS REST server using curl

Response

Listing SPS login methods

URL

Sample request

Response

HTTP response codes

Please select your product:

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

Recommended Solutions for Your Problem

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

Using the SPS REST API

Authenticate to the SPS REST API

Prerequisites

The authentication procedure:

URL

Headers

Sample request

Example: Authenticate to the SPS REST server using curl

Response

Authenticate with SPS login methods

URL

Example: Authenticating with password

Example: Authenticating with a x509 certificate

Response

Authenticate to the SPS REST API using X.509 certificate

Prerequisites

The authentication procedure:

URL

Headers

Sample request

Example: Authenticate to the SPS REST server using curl

Response

Listing SPS login methods

URL

Sample request

Response

HTTP response codes