Explore Cisco
How to Buy

Have an account?

  •   Personalized content
  •   Your products and support

Need an account?

Create an account

Configure Cisco WSA with REST API White Paper

White Paper

Available Languages

Download Options

  • PDF
    (605.3 KB)
    View with Adobe Reader on a variety of devices
Updated:June 11, 2021

Available Languages

Download Options

  • PDF
    (605.3 KB)
    View with Adobe Reader on a variety of devices
Updated:June 11, 2021
 

 

Cisco Secure Web Appliance is an all-in-one highly secure web gateway that brings you strong protection, complete control, and investment value. It also offers an array of competitive web security deployment options, each of which includes Cisco’s market-leading global threat intelligence infrastructure.

The AsyncOS API for Cisco Secure Web Appliances is a representational state transfer (REST) based set of operations that provide secure and authenticated access to the Secure Web Appliance reports, report counters, and tracking. You can retrieve the Secure Web Appliance reporting and tracking data using the API. From AsyncOS 12.5 onwards, you can query for configuration information, as well as posting configuration changes.

The value of using APIs

You have an infrastructure full of products; designed for use by you - a human. We know it may not always seem that way, but human operators are the target users of the command line interfaces and web interfaces that you work with. Which means that when you need to get something done via these interfaces, you have to (or some other human has to) do the work.

The value of using APIs

Modern APIs make it easy for you to make requests of your apps and infrastructure.

If you need some information, ask for it. Want something done? Make the request. Using a machine-to-machine API means your request will complete, your data retrieved, or you will receive notification to the contrary - all done in a way that enables you to automate the interaction.

Prerequisites for Using AsyncOS API

To use AsyncOS API, you must have the knowledge of:

     HTTP, which is the protocol used for API transactions. Secure communication over TLS.

     JavaScript Object Notation (JSON), which the API uses to construct resource representations.

     JSON Web Token (JWT).

     A client or programming library that initiates requests and receives responses from the AsyncOS API using HTTP or HTTPS, for example, cURL. The client or programming library must support JSON to interpret the response from the API.

     Authorization to access the AsyncOS API. See Authorization.

     AsyncOS API enabled using web interface or CLI. See Enabling AsyncOS API.

Enabling AsyncOS API

Before You Begin

Make sure you have access to the interfaceconfig command in CLI. Access to CLI is restricted only to the authorized personnels who are administrators, email administrators, cloud administrators, and operators. You can enable AsyncOS API using the interfaceconfig command in CLI.

Procedure

Step 1. Log in to CLI and run the interfaceconfig command.

Step 2. Choose the interface that you want to edit.

Step 3. Answer the following questions to enable AsyncOS API (Monitoring) HTTP:

     Do you want to enable AsyncOS API (Monitoring) HTTP on this interface? [Y]> Enter Y.

     Which port do you want to use for AsyncOS API (Monitoring) HTTP?[6080]> Enter the default port 6080 or the port you want to define.

Step 4. Answer the following questions to enable AsyncOS API (Monitoring) HTTPS:

     Do you want to enable AsyncOS API (Monitoring) HTTPS on this interface? [Y]> Enter Y.

     Which port do you want to use for AsyncOS API (Monitoring) HTTPS?[6443]> Enter the default port 6443 or the port you want to define.

Note:      AsyncOS API communicates using HTTP / 1.1.

If you have selected HTTPS and want to use your own certificate for secure communication, see Securely Communicating with AsyncOS API.

Note:      Cisco recommends that you always use HTTPS in the production environment. Use HTTP only for troubleshooting and testing the API.

Step 5. Commit the changes

Securely Communicating with AsyncOS API

You can communicate with AsyncOS API over secure HTTP using your own certificate.

Note:      Do not perform this procedure if you are already running the web interface over HTTPS and using your own certificate for secure communication. AsyncOS API uses the same certificate as web interface, for communicating over HTTPS.

Procedure:

Step 1.             Set up a certificate using the certconfig command in the CLI. For instructions, refer the User Guide or Online Help.

Step 2.             Change the HTTPS certificate used by the IP interface to your certificate using the interfaceconfig command in CLI. For instructions, refer the User Guide or Online Help.

Step 3.             Submit and commit your changes.

AsyncOS API Authentication and Authorization

This section explains about the authentication methods, the user roles which can access APIs, and how to query for APIs accessible to a user.

     Authentication

     Authorization

Authentication

You can authenticate queries to the API using either of the following two methods:

     Submit the Secure Web Appliance’s username and password with all the requests to the API, in the Base64-encoded format. OR

     Use JWT token in API request with the token key in the header.

The user inactivity timeout settings in the appliance apply to the validity of a JWT. If a request does not include a valid credentials in the Authorization header, the API sends a 401 error message. You can use any base64 library to convert your credentials into base64-encoded format.

Authenticating API Queries with JSON Web Token

You can generate a JSON Web Token (JWT) and use it with your API queries.

Note:      The user inactivity timeout settings in the appliance applies to the validity of a JWT. The Secure Web Appliance checks every API query with a JWT, for its time validity. If a JWT is found to be within 5 minutes of time validity, after which it will time out, a new refresh JWT is sent with the response header. You must use this new refresh JWT with API queries, or generate a new one.

This example shows a query to log in with Base64 encoded credentials, and generate a JWT.

Sample Request

POST /wsa/api/v2.0/login

HTTP/1.1

Content-Type: application/json

cache-control: no-cache

User-Agent: curl/7.54.0

Accept: */*

Host: wsa.cisco.com:6080

accept-encoding: gzip, deflate

content-length: 95

Connection: keep-alive

{

“data”:

{

“userName”:”YWRtaW4=”,

“passphrase”:”aXJvbnBvcnQ=”

}

}

Sample Response

HTTP/1.1 200 OK

Server: API/2.0

Date: Mon, 26 Nov 2018 07:22:47 GMT

Content-type: application/json

Content-Length: 618

Connection: close

Access-Control-Allow-Origin: *

Access-Control-Allow-Headers: content-type, jwttoken, mid, h, email

Access-Control-Allow-Credentials: true

Access-Control-Allow-Methods: GET, POST, DELETE, OPTIONS

Access-Control-Expose-Headers: Content-Disposition, jwtToken

{

“data”: {

“userName”: “admin”,

“is2FactorRedirectRequired”: “false”,

“role”: “Administrator”,

“email”: [],

“jwtToken”: “eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJ1c2VyTmFtZSI6ImFkbWluIiwiaXM

yRmFjdG9yQ2hlY2tSZXF1aXJlZCI6ZmFsc2UsImNvb2tpZSI6IlRucEZOVTFFWTNwTlZFMDlDanRMYVRoeENqdFpiV

1J6VFVSQk5VMURNWGRpTWxGMVdUSnNlbGt5T0hWWk1qbDBUMnBaZDA5RVFUMEtcbk8xVkhPWHBrUnpGb1lteEtNV0p

1VW5CaVYxVjJUbmswTUV4cVFUMEtPMVJVUlhkTlJsazNUVlJKZFUxRE5IZE1WRWw1VFdwek1FMXFcblNUVlNhazVDV

DBWRk1rOUVaM2xTUlVreVRYcGtSazFwTVVSTlZFMHpUbFZXUjA1

}

}

Authorization

The AsyncOS API is a role based system, the scope of API queries is defined by the role of the user. Cisco Secure Web Appliance users with the following roles can access the AsyncOS API:

     Administrator

     Operator

     Technician

     Read-Only Operator

     Guest

     Web Administrator

     Web Policy Administrator

     URL Filtering Administrator

     Email Administrator

     Help Desk User

Note:       

     Externally authenticated users can access the API.

     Custom roles, delegated by the administrator can also access the APIs.

AsyncOS API Requests and Responses

AsyncOS API Requests

Requests made to the API have the following characteristics:

     Requests are sent over HTTP or HTTPS.

     Each request must contain a valid URI in the following format:
http://{appliance}:{port}/wsa/api/v2.0/{resource}/{resource_attributes}
https://{appliance}:{port}/wsa/api/v2.0/{resource}/{resource_attributes}

where:

    {appliance}:{port}
is the FQDN or the IP address of the appliance and the TCP port number on which the appliance is listening.

    {resource}
is the resource you are attempting to access, for example, reports, tracking, quarantine, configuration, or other counters.

    {resource_attributes}
are the supported attributes for a resource, for example, duration, and so on.

     Each request must contain user credentials, or a valid authorization header.

     Each request must be set to accept:
application/json

     Requests sent over HTTPS (using your own certificate) must contain your CA certificate. For example, in case of cURL, you can specify the CA certificate in the API request as follows:
curl --cacert <ca_cert.crt> -u”username:password”
https://<fqdn>:<port>/wsa/api/v2.0/{resource}/{resource_attributes}

Note:      API requests are case sensitive and should be entered as shown in this guide.

For a complete list of APIs, see:

AsyncOS 14.0 API - Addendum to the Getting Started Guide for Cisco Secure Web Appliances.

 

 

 

Learn more