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

HTTP 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/http/connections/

Cookies

Sample request

The following command lists HTTP connection policies.

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

The following command retrieves the properties of a specific policy.

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

Response

The following is a sample response received when querying an HTTP connection policy with proxy connection.

For details of the meta object, see Message format.

{
  "key": "http-connection-simple-proxy",
  "body":
  {
    "name": "http_proxy",
    "active": true,
    "network": {
      "clients": ["0.0.0.0/0"],
      "targets": ["0.0.0.0/0"],
      "ports": [3128]
    },
    "server_address": {
      "selection": "inband",
      "dns_server": null,
      "dns_suffixes": [],
      "exception_domains": [],
      "domains": [
        {
          "domain": {
            "selection": "domain",
            "value": "*"
          },
          "port": 80
        }
      ]
    },
    "source_address": {
      "selection": "box_address"
    },
    "web_proxy": {
      "enabled": true,
      "transport_security": {
        "selection": "disabled"
      }
    },
    "transport_security": {
      "selection": "disabled"
    },
    "access_control": [],
    "indexing": {
      "enabled": true,
      "policy": {
        "key": "-50000",
        "meta": { "href": "/api/configuration/policies/indexing/-50000" }
      },
      "priority": 3
    },
    "rate_limit": {
      "enabled": false
    },
    "log_audit_trail_downloads": true,
    "channel_database_cleanup": {
      "enabled": false
    },
    "policies": {
      "channel_policy": {
        "key": "-304001002",
        "meta": { "href": "/api/configuration/http/channel_policies/-304001002" }
      },
      "settings": {
        "key": "-3040010",
        "meta": { "href": "/api/configuration/http/settings_policies/-3040010" }
      },
      "audit_policy": {
        "key": "78101850949e47437dd91d",
        "meta": { "href": "/api/configuration/policies/audit_policies/78101850949e47437dd91d" }
      },
      "ldap_server": null,
      "backup_policy": null,
      "authentication_policy": {
        "key": "-304002001",
        "meta": { "href": "/api/configuration/http/authentication_policies/-304002001" }
      },
      "usermapping_policy": null,
      "archive_cleanup_policy": null,
      "analytics_policy": null
    }
  }
}

"server_certificate_check": {
    "enabled": false
},

"server_certificate_check": {
    "enabled": true,
    "trusted_ca": "9106862955a844051d7bf6"
},

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.

HTTP 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/http/authentication_policies

Cookies

Sample request

The following command lists SSH authentication policies.

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

The following command retrieves the properties of a specific policy.

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

Response

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

For details of the meta object, see Message format.

{
  "items": [
    {
      "key": "-200",
      "meta": {
        "href": "/api/configuration/ssh/authentication_policies/-200"
      }
    },
    {
      "key": "-304002001",
      "meta":  { 
        "href": "/api/configuration/http/authentication_policies/-304002001" }

      }
    }
  ],
  "meta": {
    "first": "/api/configuration/http/authentication_policies",
    "href": "/api/configuration/http/authentication_policies",
    "last": "/api/configuration/http/settings_policies",
    "next": "/api/configuration/http/channel_policies",
    "parent": "/api/configuration/http",
    "previous": null,
    "transaction": "/api/transaction"
  }
}

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

{
  "key": "http-auth-pol-4",
  "body": {
    "name": "http_radius",
    "gateway_authentication": {
      "selection": "radius",
      "servers": [
        {
          "address": {
            "selection": "ip",
            "value": "1.2.3.4"
          },
          "port": 1812,
          "shared_secret": {
            "key": "XXXXXXXX-XXXX-XXXX-XXXX-XXXXXXXXXXXX",
            "meta": { "href": "/api/configuration/passwords#XXXXXXXX-XXXX-XXXX-XXXX-XXXXXXXXXXXX" }
          }
        }
      ],
      "authentication_protocol": "pap",
      "timeout": 3600,
      "keepalive": true
    }
  }

}

Examples:

Querying base authentication policy without gateway authentication:

{
  "key": "-304002001",
  "body": {
    "name": "base",
    "gateway_authentication": {
      "selection": "none"
    }
  }
}

Querying authentication policy with LDAP backend:

{
  "key": "http-auth-pol-2",
  "body": {
    "name": "http_ldap",
    "gateway_authentication": {
      "selection": "ldap",
      "timeout": 3600,
      "keepalive": true
    }
  }
}

Querying authentication policy with local backend:

{
  "key": "http-auth-pol-3",
  "body": {
    "name": "http_local",
    "gateway_authentication": {
      "selection": "local",
      "user_database": {
        "key": "local-user-database-1",
        "meta": { "href": "/api/configuration/policies/user_databases/local-user-database-1" }
      },
      "timeout": 3600,
      "keepalive": true
    }
  }
}

Querying authentication policy with RADIUS backend:

{
  "key": "http-auth-pol-4",
  "body": {
    "name": "http_radius",
    "gateway_authentication": {
      "selection": "radius",
      "servers": [
        {
          "address": {
            "selection": "ip",
            "value": "1.2.3.4"
          },
          "port": 1812,
          "shared_secret": {
            "key": "XXXXXXXX-XXXX-XXXX-XXXX-XXXXXXXXXXXX",
            "meta": { "href": "/api/configuration/passwords#XXXXXXXX-XXXX-XXXX-XXXX-XXXXXXXXXXXX" }
          }
        }
      ],
      "authentication_protocol": "pap",
      "timeout": 3600,
      "keepalive": true
    }
  }
}

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 HTTP authentication policy

To add an HTTP 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/http/authentication_policies/ 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 policy. For example:

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

3. Commit your changes.

   For details, see Commit a transaction.

Modify an HTTP authentication policy

To modify an HTTP 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/http/authentication_policies/<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.

Global HTTP options

List of options that affect all HTTP connections.

URL

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

Cookies

Sample request

The following command lists global HTTP options.

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

Response

The following is a sample response received when listing global HTTP options.

For details of the meta object, see Message format.

{
  "body": {
    "audit": {
      "cleanup": {
        "enabled": false
      },
      "timestamping": {
        "selection": "local",
        "signing_interval": 30
      }
    },
    "service": {
      "enabled": true,
      "log_level": 4
    }
  },
  "key": "options",
  "meta": {
    "first": "/api/configuration/http/channel_policies",
    "href": "/api/configuration/http/options",
    "last": "/api/configuration/http/settings_policies",
    "next": "/api/configuration/http/settings_policies",
    "parent": "/api/configuration/http",
    "previous": "/api/configuration/http/channel_policies",
    "transaction": "/api/transaction"
  }
}

Examples:

Set SPS as the timestamping server:

{
  "audit": {
    "cleanup": {
      "enabled": false
    },
    "timestamping": {
      "selection": "local",
      "signing_interval": 30
    }
  },
  "service": {
    "enabled": true,
    "log_level": 4
  }
}

Enable cleanup, and set it to occur every 10 days:

{
  "audit": {
    "cleanup": {
      "channel_database_cleanup_days": 10,
      "enabled": true
    },
    "timestamping": {
      "selection": "local",
      "signing_interval": 30
    }
  },
  "service": {
    "enabled": true,
    "log_level": 4
  }
}

Change timestamping to a remote server, without specifying a timestamping policy:

{
  "audit": {
    "cleanup": {
      "channel_database_cleanup_days": 10,
      "enabled": true
    },
    "timestamping": {
        "oid": {
          "enabled": false
        },
        "selection": "remote",
        "server_url": "<url-of-timestamping-server>",
        "signing_interval": 30
      }
  },
  "service": {
    "enabled": true,
    "log_level": 4
  }
}

Change timestamping to a remote server, and specify the 1.2.3 timestamping policy:

{
  "audit": {
    "cleanup": {
      "channel_database_cleanup_days": 10,
      "enabled": true
    },
    "timestamping": {
        "oid": {
          "enabled": true,
          "policy_oid": "1.2.3"
        },
        "selection": "remote",
        "server_url": "<url-of-timestamping-server>",
        "signing_interval": 30
      }
  },
  "service": {
    "enabled": true,
    "log_level": 4
  }
}

Modify global HTTP settings

To modify global HTTP settings, you have to:

1. Open a transaction.

   For details, see Open a transaction.

2. Modify the JSON object of the global HTTP settings endpoint.

   PUT the modified JSON object to the https://<IP-address-of-SPS>/api/configuration/http/options endpoint. You can find a detailed description of the available parameters listed in Element . The elements of the audit item are described in Elements of audit.

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.

HTTP settings policies

HTTP settings policies define protocol-level settings for idle and session timeout. You can create multiple policies, and choose the appropriate one for each HTTP connection.

URL

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

Cookies

Sample request

The following command lists HTTP settings policies.

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

The following command retrieves the properties of a specific policy.

curl --cookie cookies https://<IP-address-of-SPS>/api/configuration/http/settings_policies/<policy-id>

Response

The following is a sample response received when listing HTTP settings policies.

For details of the meta object, see Message format.

{
  "items": [
    {
      "key": "-3040010",
      "meta": {
        "href": "/api/configuration/http/settings_policies/-3040010"
      }
    }
  ],
  "meta": {
    "first": "/api/configuration/http/channel_policies",
    "href": "/api/configuration/http/settings_policies",
    "last": "/api/configuration/http/settings_policies",
    "next": null,
    "parent": "/api/configuration/http",
    "previous": "/api/configuration/http/options",
    "transaction": "/api/transaction"
  }
}

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

{
  "body": {
    "client_tls_security_settings": {
        "cipher_strength": {
            "selection": "recommended"
        },
        "minimum_tls_version": "TLSv1_2"
    },
    "name": "default",
    "server_tls_security_settings": {
        "cipher_strength": {
            "selection": "recommended"
        },
        "minimum_tls_version": "TLSv1_2"
    },
    "session_timeout": 900,
    "timeout": 300
    "webapp_session_cookies": [
      "PHPSESSID",
      "JSESSIONID",
      "ASP.NET_SessionId"
    ]
  },
  "key": "-3040010",
  "meta": {
    "first": "/api/configuration/http/settings_policies/-3040010",
    "href": "/api/configuration/http/settings_policies/-3040010",
    "last": "/api/configuration/http/settings_policies/-3040010",
    "next": null,
    "parent": "/api/configuration/http/settings_policies",
    "previous": null,
    "transaction": "/api/transaction"
  }
}

Add HTTP settings policies

To add a settings 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/http/settings_policies/ 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 policy. For example:

   {
     "key": "3848c708-2e1d-4463-b232-0c8c5875ff55",
     "meta": {
       "href": "/api/configuration/http/settings_policies/3848c708-2e1d-4463-b232-0c8c5875ff55",
       "parent": "/api/configuration/http/settings_policies",
       "transaction": "/api/transaction"
     }
   }

3. Commit your changes.

   For details, see Commit a transaction.

Modify HTTP settings policies

To modify a settings 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/http/settings_policies/<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.

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.