Authentication

Cisco Catalyst SD-WAN Manager REST API access control is based on sessions. The user enters a session after successful login. The following are typical steps for a user to consume the API:

Log in with a username and password to establish a session:

POST /j_security_check with content type x-www-form-urlencoded. Submit the username and password as j_username and j_password. The session token is in the response http cookie, JSESSIONID={session hash}.
```
POST https://{vmanage-ip-address}/j_security_check
Content-Type: application/x-www-form-urlencoded
HTTP Body: "j_username={admin}&j_password={credential}"
```
When a user authenticates successfully, the response body remains empty, and the response includes a valid session cookie (set-cookie: JSESSIONID=). When a user is unauthenticated, the response body contains an HTML login page, indicated by an tag. The API client must check the response body for the tag to determine if authentication is successful. This is the behavior of our application server.
Get a cross-site request forgery prevention token, necessary for most POST operations:

GET /dataservice/client/token with content type application/json. You need the JSESSIONID={session hash} cookie to authenticate.
The XSRF token is in the response body. Use the XSRF token along with the JESSIONID cookie for ongoing API requests.
```
GET https://{vmanage-ip-address}/dataservice/client/token
Content-Type: application/json
HTTP Header: "Cookie: JESSIONID={session hash id}"
```
Make an API request.

For non-whitelisted endpoints, the user must provide an API token as a cookie: JESSIONID={session hash}.

For POST requests, the user must provide the matching XSRF token.
```
https://{vmanage-ip-address}/dataservice/{api-endpoint-url}
Content-Type: application/json
HTTP Header: "Cookie: JESSIONID={session hash id}" "X-XSRF-TOKEN: {XSRF token}"
```
Log out and destroy the session.

The user must log out after finishing the API requests. It is not only a good security practice, but also releases the allocated session resource.

If the HTTP response code is 302 and it redirects with the location header https://{vmanage-ip-address}/welcome.html?nocache=, this indicates an invalidated session.
```
POST https://{vmanage-ip-address}/logout?nocache={random-number}`  
HTTP Header: "Cookie: JESSIONID={session hash id}"
```

Sample code to authenticate with Cisco Catalyst SD-WAN Manager:

class Authentication:

    @staticmethod
    def get_jsessionid(vmanage_host, vmanage_port, username, password):
        api = "/j_security_check"
        base_url = "https://%s:%s"%(vmanage_host, vmanage_port)
        url = base_url + api
        payload = {'j_username' : username, 'j_password' : password}

        response = requests.post(url=url, data=payload, verify=False)
        try:
            cookies = response.headers["Set-Cookie"]
            jsessionid = cookies.split(";")
            return(jsessionid[0])
        except:
            print("No valid JSESSION ID returned\n")
            exit()

    @staticmethod
    def get_token(vmanage_host, vmanage_port, jsessionid):
        headers = {'Cookie': jsessionid}
        base_url = "https://%s:%s"%(vmanage_host, vmanage_port)
        api = "/dataservice/client/token"
        url = base_url + api      
        response = requests.get(url=url, headers=headers, verify=False)
        if response.status_code == 200:
            return(response.text)
        else:
            return None

Auth = Authentication()
jsessionid = Auth.get_jsessionid(vmanage_host,vmanage_port,vmanage_username,vmanage_password)
token = Auth.get_token(vmanage_host,vmanage_port,jsessionid)

if token is not None:
    header = {'Content-Type': "application/json",'Cookie': jsessionid, 'X-XSRF-TOKEN': token}
else:
    header = {'Content-Type': "application/json",'Cookie': jsessionid}

Note: API requests header for GET/POST/PUT/DELETE are:

For Cisco Catalyst SD-WAN Manager pre 19.2 - Session Cookie (jsessionid)

For Cisco Catalyst SD-WAN Manager post-19.2 - Session Cookie (jsessionid) and Token

Sharing the same session is mandatory when invoking multiple API requests sequentially. The default session lifespan is 24 hours, and the session inactivity timeout is 30 minutes.

The maximum concurrent session number is 100. The system invalidates the least recently used session when the maximum number of concurrent sessions is reached by starting a new session.

Refresh Expired Tokens

The session token (JSESSIONID) for Cisco Catalyst SD-WAN Manager expires after 30 minutes of inactivity or after 24 hours, which is the total lifespan of a session. For more information, see https://www.cisco.com/c/en/us/td/docs/routers/sdwan/configuration/sdwan-xe-gs-book/cisco-sd-wan-API-cross-site-request-forgery-prevention.html

The cross-site request forgery prevention token (X-XSRF-TOKEN) is valid for the duration of the session and must be included in the header of each API request. For more information, see https://www.cisco.com/c/en/us/td/docs/routers/sdwan/configuration/sdwan-xe-gs-book/cisco-sd-wan-api-cross-site-request-forgery-prevention.html

SSO Authentication in Cisco Catalyst SD-WAN Manager

If you enable SSO authentication on Cisco Catalyst SD-WAN Manager, you can copy the JSESSIONID and X-XSRF-Token from your browser to authenticate an API request.

Log in to Cisco Catalyst SD-WAN Manager with SSO in your browser.
From your browser's developer tool, select "Network"*.
Inspect an API request.
From the API request headers, copy the value of Cookie: JSESSIONID=<session hash id> and X-XSRF-TOKEN: <XSRF token>.
Use the JSESSIONID and X-XSRF-TOKEN for API authentication.