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

SSH connections

List of endpoints for configuring the policies, options and connection rules of SSH connections.

URL

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

Cookies

Sample request

The following command lists the available settings for configuring for SSH connections.

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

Response

The following is a sample response received when listing the configuration settings.

For details of the meta object, see Message format.

{
  "items": [
    {
      "key": "authentication_policies",
      "meta": {
        "href": "/api/configuration/ssh/authentication_policies"
      }
    },
    {
      "key": "channel_policies",
      "meta": {
        "href": "/api/configuration/ssh/channel_policies"
      }
    },
    {
      "key": "connections",
      "meta": {
        "href": "/api/configuration/ssh/connections"
      }
    },
    {
      "key": "options",
      "meta": {
        "href": "/api/configuration/ssh/options"
      }
    },
    {
      "key": "settings_policies",
      "meta": {
        "href": "/api/configuration/ssh/settings_policies"
      }
    }
  ],
  "meta": {
    "first": "/api/configuration/aaa",
    "href": "/api/configuration/ssh",
    "last": "/api/configuration/x509",
    "next": "/api/configuration/telnet",
    "parent": "/api/configuration",
    "previous": "/api/configuration/reporting",
    "transaction": "/api/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.

SSH connection policies

Connection policies determine if a server can be accessed from a particular client. Connection policies reference other resources (policies, usergroups, keys) that must be configured and available before creating a connection policy.

URL

GET https://<IP-address-of-SPS>/api/configuration/ssh/connections/

Cookies

Sample request

The following command lists SSH connection policies.

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

The following command retrieves the properties of a specific policy.

curl --cookie cookies https://<IP-address-of-SPS>/api/configuration/ssh/connections/<connection-key>

Response

The following is a sample response received when listing SSH connection policies.

For details of the meta object, see Message format.

{
  "items": [
    {
      "key": "8348340645707e2575e3c6",
      "meta": {
        "href": "/api/configuration/ssh/connections/8348340645707e2575e3c6"
      }
    }
  ],
  "meta": {
    "first": "/api/configuration/ssh/authentication_policies",
    "href": "/api/configuration/ssh/connections",
    "last": "/api/configuration/ssh/settings_policies",
    "next": "/api/configuration/ssh/options",
    "parent": "/api/configuration/ssh",
    "previous": "/api/configuration/ssh/channel_policies",
    "remaining_seconds": 600,
    "transaction": "/api/transaction"
  }
}

When retrieving the endpoint of a specific SSH connection policy, the response is the following.

{
  "body": {
    "access_control": [
      {
        "authorizer": "reporting",
        "permission": "audit_and_authorize",
        "require_different_ip": true,
        "require_different_username": true,
        "subject": {
          "selection": "everybody"
        }
      }
    ],
    "active": true,
    "channel_database_cleanup": {
      "days": 550,
      "enabled": true
    },
    "client_side_hostkey": {
      "plain_hostkey": {
        "dsa_key": null,
        "enabled": true,
        "rsa_key": {
          "key": "e5a58682-6189-4477-9415-67c1c9b20b0d",
          "meta": {
            "href": "/api/configuration/private_keys/e5a58682-6189-4477-9415-67c1c9b20b0d"
          }
        }
      },
      "x509_hostkey": {
        "enabled": false
      }
    },
    "indexing": {
      "enabled": true,
      "policy": {
        "key": "-50000",
        "meta": {
          "href": "/api/configuration/policies/indexing/-50000"
        }
      },
      "priority": 2
    },
    "log_audit_trail_downloads": true,
    "name": "API_test_SSH",
    "network": {
      "clients": [
        "0.0.0.0/24"
      ],
      "ports": [
        22
      ],
      "targets": [
        "192.168.56.102/24"
      ]
    },
    "policies": {
      "aa_plugin": null,
      "analytics_policy": null,
      "archive_cleanup_policy": {
        "key": "1854671967571b9063c4c82",
        "meta": {
          "href": "/api/configuration/policies/archive_cleanup_policies/1854671967571b9063c4c82"
        }
      },
      "audit_policy": {
        "key": "78101850949e47437dd91d",
        "meta": {
          "href": "/api/configuration/policies/audit_policies/78101850949e47437dd91d"
        }
      },
      "authentication_policy": {
        "key": "1895203635707e3340262f",
        "meta": {
          "href": "/api/configuration/ssh/authentication_policies/1895203635707e3340262f"
        }
      },
      "backup_policy": {
        "key": "512524636571b903540804",
        "meta": {
          "href": "/api/configuration/policies/backup_policies/512524636571b903540804"
        }
      },
      "channel_policy": {
        "key": "-10000",
        "meta": {
          "href": "/api/configuration/ssh/channel_policies/-10000"
        }
      },
      "credential_store": {
        "key": "505008562571b936560254",
        "meta": {
          "href": "/api/configuration/policies/credentialstores/505008562571b936560254"
        }
      },
      "ldap_server": {
        "key": "250588254571b931066482",
        "meta": {
          "href": "/api/configuration/policies/ldap_servers/250588254571b931066482"
        }
      },
      "settings": {
        "key": "-300",
        "meta": {
          "href": "/api/configuration/ssh/settings_policies/-300"
        }
      },
      "usermapping_policy": {
        "key": "9328731525704545f5e3de",
        "meta": {
          "href": "/api/configuration/policies/usermapping_policies/9328731525704545f5e3de"
        }
      }
    },
    "rate_limit": {
      "enabled": true,
      "value": 200
    },
    "server_address": {
      "selection": "original"
    },
    "server_side_hostkey": {
      "plain_hostkey": {
        "enabled": true,
        "hostkey_check": "accept-first-time"
      },
      "x509_hostkey": {
        "enabled": false
      }
    },
    "source_address": {
      "selection": "box_address"
    },
    "web_gateway_authentication": {
      "enabled": true,
      "groups": [
        "reporting"
      ],
      "require_same_ip": true
    }
  },
  "key": "8348340645707e2575e3c6",
  "meta": {
    "first": "/api/configuration/ssh/connections/8348340645707e2575e3c6",
    "href": "/api/configuration/ssh/connections/8348340645707e2575e3c6",
    "last": "/api/configuration/ssh/connections/8348340645707e2575e3c6",
    "next": null,
    "parent": "/api/configuration/ssh/connections",
    "previous": null,
    "transaction": "/api/transaction"
  }
}

Examples

For practical purposes, the following examples show only the relevant parts of a connection policy JSON object. To modify or add a connection policy, always submit the full JSON object.

Access control list: configuring the "security" usergroup to only audit connections made by the "root_only" usergroup.

"access_control": [
      {
    "authorizer": "security",
    "permission": "audit",
    "require_different_ip": true,
    "require_different_username": true,
    "subject": {
      "group": "root_only",
      "selection": "only"
    }
  }

Target server: use the address specified by the client.

"server_address": {
  "selection": "original"
}

Target server: use a fix address.

"server_address": {
  "address": "<fix-IP>",
  "port": 22,
  "selection": "fix"
}

Target server: configure inband destination selection, where the client can specify the target address in the username. The target can be either an IP range, or a domain.

"server_address": {
  "dns_server": "<ip-of-dns-server>",
  "dns_suffixes": null,
  "domains": [
    {
      "domain": {
        "selection": "address",
        "value": "<IP-range>"
      },
      "port": 22
    },
    {
      "domain": {
        "selection": "domain",
        "value": "*.example"
      },
      "port": 22
    }
  ],
  "selection": "inband"
}

Source address: use the same fix IP when connecting to the remote server.

"source_address": {
  "address": "<ip-address>",
  "selection": "fix"
}

Web gateway authentication: require the admin usergroup to perform an additional gateway authentication on the SPS web interface. They must authenticate from the same host which initiated the connection.

"web_gateway_authentication": {
  "enabled": true,
  "groups": [
    "admin"
  ],
  "require_same_ip": true
}

Client-side hostkey: use plain hostkeys uploaded to SPS, and generate X.509 certificates for the connection.

"client_side_hostkey": {
  "plain_hostkey": {
    "dsa_key": "<id-of-dsa-key>",
    "enabled": true,
    "rsa_key": "<id-of-rsa-key>"
  },
  "x509_hostkey": {
    "enabled": true,
    "x509": {
      "selection": "generate",
      "signing_ca": "<key-of-signing-ca>"
    }
  }
}

Policies: configure only the required policies.

"policies": {
  "aa_plugin": null,
  "analytics_policy": null,
  "archive_cleanup_policy": null,
  "audit_policy": "<key-of-audit-policy>",
  "authentication_policy": "<key-of-auth-policy>",
  "backup_policy": null,
  "channel_policy": "<key-of-channel-policy>",
  "credential_store": null,
  "ldap_server": null,
  "settings": "<key-of-settings-policy>",
  "usermapping_policy": null
}

Server-side hostkey: accept the hostkey or X.509 certificate presented at the first connection, and require the same hostkey or certificate for any subsequent connections.

"server_side_hostkey": {
  "plain_hostkey": {
    "enabled": true,
    "hostkey_check": "accept-first-time"
  },
  "x509_hostkey": {
    "enabled": true,
    "x509_check": {
      "selection": "accept-first-time"
    }
  }
}

Server-side hostkey: only accept X.509 certificates that are verified by a trusted CA.

"server_side_hostkey": {
  "plain_hostkey": {
    "enabled": false
  },
  "x509_hostkey": {
    "enabled": true,
    "x509_check": {
      "selection": "accept-signed-by",
      "trusted_ca": "<id-of-trusted-ca>"
    }
  }
}

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.

Add an SSH connection policy

To add an SSH connection policy, you have to:

1. Open a transaction.

   For details, see Open a transaction.

2. Create the JSON object for the new SSH connection policy.

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

   If the POST request is successful, the response includes the key of the new SSH connection policy. For example:

   {
     "key": "a99be49b-b0a2-4cf9-b70d-fea1f9ea188f",
     "meta": {
       "href": "/api/configuration/ssh/connections/a99be49b-b0a2-4cf9-b70d-fea1f9ea188f",
       "parent": "/api/configuration/ssh/connections",
       "transaction": "/api/transaction"
     }
   }

3. Commit your changes.

   For details, see Commit a transaction.

Modify an SSH connection policy

To modify an SSH connection policy, you have to:

1. Open a transaction.

   For details, see Open a transaction.

2. Modify the JSON object of the SSH connection policy.

   PUT the modified JSON object to the https://<IP-address-of-SPS>/api/configuration/ssh/connections/<key-of-the-object> endpoint. You can find a detailed description of the available parameters listed in Element .

3. Commit your changes.

   For details, see Commit a transaction.

SSH channels

The available SSH channel types and their functionalities are described below.

"networks": [
  {
    "selection": "address",
    "value": "192.168.1.1"
  },
  {
    "selection": "address",
    "value": "192.168.1.2"
  }
                        
NOTE: 
Certain client applications send the Target address as a hostname, while others as an IP address. If you are using a mix of different client applications, you might have to duplicate the channel rules and create IP-address and hostname versions of the same rule.
Channel-specific access control rules:
networks (list): To X11-forwarding only to specific clients, list the IP addresses or networks of the clients in this field. Leave it empty to permit access to every client. For details, see Limiting addresses in port forwarding.

"local_forwards": [
  {
    "host_address": {
      "selection": "address",
      "value": "192.168.100.1"
    },
    "host_port": 5555,
    "originator_address": {
      "selection": "address",
      "value": "192.168.1.1"
    }
  }
                        
Channel-specific access control rules:
local_forwards (list): To permit local forwarding only to specific addresses, list the addresses in this field. Leave it empty to enable without restriction. In this case the client may forward any traffic to the remote host.
Enter the source of the forwarded traffic into the originator_address field, the target of the traffic into the host_address field. Specify IP addresses or networks (in IP address/Prefix format). These parameters are the end-points of the forwarded traffic (that is, the local host that sends data to the remote host), and not the SSH server or the client. For example, to enable forwarding from the 192.168.20.20 host to the remote host 192.168.50.50, enter 192.168.20.20 into the originator_address, and 192.168.50.50 into the host_address field. For details, see Limiting addresses in port forwarding.

"remote_forwards": [
  {
    "connected_address": {
      "selection": "address",
      "value": "192.168.100.1"
    },
    "connected_port": 5555,
    "originator_address": {
      "selection": "address",
      "value": "192.168.1.1"
    }
  }
                        
Channel-specific access control rules:
remote_forwards (list): To permit only specific forwardins, list the permitted addresses in this field. Leave it empty to permit forwarding without restrictions.
Enter the source of the forwarded traffic into the originator_address, the target of the traffic into the connected_address field. Specify IP addresses or networks (in IP address/Prefix format). These parameters are the end-points of the forwarded traffic (that is, the remote host that sends data to the client), and not the SSH server. For example, to enable forwarding from the 192.168.20.20 remote host to the client 192.168.50.50, enter 192.168.20.20 into the originator_address, and 192.168.50.50 into the connected_address field. For details, see Limiting addresses in port forwarding.

"execs": [
  "top",
  "ls"
                    

"actions": {
  "audit": false,
  "four_eyes": false,
  "ids": false,
  "log_transfer_to_db": true,
  "log_transfer_to_syslog": true
}

"execs": [
  "top",
  "ls"
                    

"actions": {
  "audit": false,
  "four_eyes": false,
  "ids": false,
  "log_transfer_to_db": true,
  "log_transfer_to_syslog": true
}

"actions": {
  "audit": true,
  "content_policy": {
    "key": "433849548566ab327522e6"
  },
  "four_eyes": false,
  "ids": false
}

Limiting addresses in port forwarding

The connected_address, host_address, network, and originator_address options that you can use in SSH channel policies that allow port-forwarding and X11 forwarding have the following parameters.

SSH authentication policies

Lists the configured authentication methods that can be used in a connection. Each connection policy uses an authentication policy to determine how the client can authenticate to the target server. Separate authentication methods can be used on the client and the server-side of the connection.

URL

GET https://<IP-address-of-SPS>/api/configuration/ssh/authentication_policies

Cookies

Sample request

The following command lists SSH authentication policies.

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

The following command retrieves the properties of a specific policy.

curl --cookie cookies https://<IP-address-of-SPS>/api/configuration/ssh/authentication_policies<object-id>

Response

The following is a sample response received when listing SSH authentication policies.

For details of the meta object, see Message format.

{
  "items": [
    {
      "key": "-200",
      "meta": {
        "href": "/api/configuration/ssh/authentication_policies/-200"
      }
    },
    {
      "key": "1895203635707e3340262f",
      "meta": {
        "href": "/api/configuration/ssh/authentication_policies/1895203635707e3340262f"
      }
    }
  ],
  "meta": {
    "first": "/api/configuration/ssh/authentication_policies",
    "href": "/api/configuration/ssh/authentication_policies",
    "last": "/api/configuration/ssh/settings_policies",
    "next": "/api/configuration/ssh/channel_policies",
    "parent": "/api/configuration/ssh",
    "previous": null,
    "transaction": "/api/transaction"
  }
}

When retrieving the endpoint of a specific policy, the response is the following.

{
  "body": {
    "mode": {
      "gateway_authentication": {
        "selection": "none"
      },
      "gssapi": false,
      "relayed_methods": {
        "certificate": {
          "selection": "disabled"
        },
        "keyboard_interactive": true,
        "password": true,
        "public_key": {
          "selection": "disabled"
        }
      }
    },
    "name": "base"
  },
  "key": "-200",
  "meta": {
    "first": "/api/configuration/ssh/authentication_policies/-200",
    "href": "/api/configuration/ssh/authentication_policies/-200",
    "last": "/api/configuration/ssh/authentication_policies/1895203635707e3340262f",
    "next": "/api/configuration/ssh/authentication_policies/1895203635707e3340262f",
    "parent": "/api/configuration/ssh/authentication_policies",
    "previous": null,
    "transaction": "/api/transaction"
  }
}

Examples:

Password authentication against LDAP on the client side, and using a username and password on the remote server:

{
  "mode": {
    "gateway_authentication": {
      "certificate": {
        "enabled": false
      },
      "password": true,
      "public_key": {
        "enabled": false
      },
      "selection": "ldap"
    },
    "gssapi": false,
    "relayed_methods": {
      "certificate": {
        "selection": "disabled"
      },
      "keyboard_interactive": false,
      "password": true,
      "public_key": {
        "selection": "disabled"
      }
    }
  },
  "name": "Passwords"
}

Password authentication against a local user database on SPS, and using a username and password on the remote server. You can find the key of the local user database is available at the /api/configuration/policies/user_databases/ endpoint.

{
  "mode": {
    "gateway_authentication": {
      "certificate": {
        "enabled": false
      },
      "password": true,
      "public_key": {
        "enabled": false
      },
      "selection": "local",
      "user_database": <key-of-the-local-usr-db>
    },
    "gssapi": false,
    "relayed_methods": {
      "certificate": {
        "selection": "disabled"
      },
      "keyboard_interactive": false,
      "password": true,
      "public_key": {
        "selection": "disabled"
      }
    }
  },
  "name": "Local_usr_db"
}

Authenticating against an RADIUS server on the client side, and using a username and password on the remote server. You can configure the key of the shared secret at the /api/configuration/passwords/ endpoint. The IP of the RADIUS server is used.

{
  "mode": {
    "gateway_authentication": {
      "selection": "radius",
      "servers": [
        {
          "address": {
            "selection": "ip",
            "value": "<radius-server-ip>"
          },
          "port": 1812,
          "shared_secret": <key-of-shared-secret>
        }
      ]
    },
    "gssapi": false,
    "relayed_methods": {
      "certificate": {
        "selection": "disabled"
      },
      "keyboard_interactive": false,
      "password": true,
      "public_key": {
        "selection": "disabled"
      }
    }
  },
  "name": "RADIUS"
}

Using X.509 certificates against an LDAP server on the client-side, and forwarding it for authentication on the server-side. The key of the trusted Certificate Authority (CA) is available at the /api/configuration/policies/trusted_ca_lists endpoint.

{
  "mode": {
    "gateway_authentication": {
      "certificate": {
        "enabled": true,
        "trusted_ca": <key-of-trusted-ca>
      },
      "password": false,
      "public_key": {
        "enabled": false
      },
      "selection": "ldap"
    },
    "gssapi": false,
    "relayed_methods": {
      "certificate": {
        "selection": "agent"
      },
      "keyboard_interactive": false,
      "password": false,
      "public_key": {
        "selection": "disabled"
      }
    }
  },
  "name": "X509_forwarding"
}

Using X.509 certificates against an LDAP server on the client-side, and generating X.509 certificate and key on the fly for authentication on the server-side. The generated keys are uploaded to the LDAP server, so that SPS can authenticate the user on the remote server. The key of the trusted Certificate Authority (CA) is available at the /api/configuration/policies/trusted_ca_lists/ endpoint. The key of the signing Certificate Authority (CA) is available at the /api/configuration/policies/signing_cas/ endpoint.

{
  "mode": {
    "gateway_authentication": {
      "certificate": {
        "enabled": true,
        "trusted_ca": <key-of-trusted-ca>
      },
      "password": false,
      "public_key": {
        "enabled": false
      },
      "selection": "ldap"
    },
    "gssapi": false,
    "relayed_methods": {
      "certificate": {
        "selection": "publish_to_ldap",
        "signing_ca": <key-of-signing-ca>
      },
      "keyboard_interactive": false,
      "password": false,
      "public_key": {
        "selection": "disabled"
      }
    }
  },
  "name": "X509"
}

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.

Add an SSH authentication policy

To add an SSH authentication policy, you have to:

1. Open a transaction.

   For details, see Open a transaction.

2. Create the JSON object for the new policy.

   POST the JSON object to the https://<IP-address-of-SPS>/api/configuration/ssh/authentication_policies/ endpoint. You can find a detailed description of the available parameters listed in Element . The elements of gateway_authentication are listed in Elements of gateway_authentication. The elements of relayed_authentication are listed in Elements of relayed_authentication.

   If the POST request is successful, the response includes the key of the new policy. For example:

   {
     "key": "6f924f39-e4c9-4b0f-8018-8842e2115ebd",
     "meta": {
       "href": "/api/configuration/ssh/authentication_policies/6f924f39-e4c9-4b0f-8018-8842e2115ebd",
       "parent": "/api/configuration/ssh/authentication_policies",
       "transaction": "/api/transaction"
     }
   }

3. Commit your changes.

   For details, see Commit a transaction.

Modify an SSH authentication policy

To modify an SSH authentication policy, you have to:

1. Open a transaction.

   For details, see Open a transaction.

2. Modify the JSON object of the policy.

   PUT the modified JSON object to the https://<IP-address-of-SPS>/api/configuration/ssh/authentication_policies/<key-of-the-object> endpoint. You can find a detailed description of the available parameters listed in Element . The elements of gateway_authentication are listed in Elements of gateway_authentication. The elements of relayed_authentication are listed in Elements of relayed_authentication.

3. Commit your changes.

   For details, see Commit a transaction.