How to Authenticate
Catalyst Manager REST API access control is based on sessions. All users will be able to get a session after successfully logging in. The following are typical steps for a user to consume the API:
Log in with a user name and password to establish a session:
POST /j_security_check with content type x-www-form-urlencoded
. The user name and password are submitted 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}"
If a user is successfully authenticated, the response body is empty and a valid session cookie is set is response (set-cookie: JSESSIONID=
). If a user is un-authenticated, the response body contains a html login page with tag in it. API client should check the response body for to identify whether the authentication is successful or not. This is the behavior of our application server. Get a cross-site request forgery prevention token, which is required for most POST operations:
GET /dataservice/client/token
with content typeapplication/json
. TheJESSIONID={session hash}
cookie is required to authenticate.
The XSRF token is in the response body. Use the XSRF token along with theJESSIONID
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 needs to provide an API token as a cookie: JESSIONID={session hash}.
For POST requests, the user also needs to 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 needs to log out after finishing the API requests. This is not only a good security practice, but also releases the allocated session resource.
If the http response code is 302 redirect with location header
https://{vmanage-ip-address}/welcome.html?nocache=
, the session has been invalidated. Otherwise, an error occurred in the session invalidation process.POST https://{vmanage-ip-address}/logout?nocache={random-number}` HTTP Header: "Cookie: JESSIONID={session hash id}"
Sample code to authenticate with Catalyst 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 Catalyst Manager pre-19.2 - Session Cookie (jsessionid)
- For Catalyst Manager post-19.2 - Session Cooke (jsessionid) and Token
It is mandatory to share the same session if multiple API requests are invoked sequentially. The default session lifespan is 24 hours, and the session inactivity timeout is 30 minutes.
The maximum concurrent session number is 100. The new session will invalidate the least recently used session if the maximum concurrent session number is reached.
How to Authenticate in SSO Enabled Catalyst Manager
If SSO authentication is enabled on Catalyst Manager, you can copy the JSESSIONID and X-XSRF-Token from your browser to authenticate an API request.
- Login to Catalyst Manager via SSO in your browser.
- From your browser's developer tool, select the "Network" tab.
- Inspect an API request.
- From the API request headers, copy the value of "Cookie: JSESSIONID=
" and "X-XSRF-TOKEN: ". - Use the JSESSIONID and X-XSRF-TOKEN for API authentication.