Authentication Methods
Authentication allows XML API interaction with the Cisco UCS. It provides a way to set permissions and control the operations that can be performed.
Note |
Most code examples
in this guide substitute the term
|
Login
To log in, the XML API client establishes a TCP connection to the Cisco UCS Manager HTTP (or HTTPS) server and posts an XML document containing the aaaLogin method.
In the following example, the Telnet utility is used to establish a TCP connection to port 80 of the Cisco UCS Manager with IP address 192.0.20.72. The path used is /nuova.
$ telnet 192.0.20.72 80
POST /nuova HTTP/1.1
USER-Agent: lwp-request/2.06
HOST: 192.0.20.72
Content-Length: 62
Content-Type: application/x-www-form-urlencoded
Next, the client specifies the aaaLogin method and provides a user name and password:
<aaaLogin
inName="admin"
inPassword="password" />
Note |
Do not include XML version or DOCTYPE lines in the XML API document. The inName and inPassword attributes are parameters. |
Each XML API document represents an operation to be performed. When the request is received as an XML API document, Cisco UCS reads the request and performs the actions as provided in the method. Cisco UCS responds with a message in XML document format and indicates success or failure of the request.
The following is a typical successful response:
1 <aaaLogin
2 response="yes"
3 outCookie="<real_cookie>"
4 outRefreshPeriod="600"
5 outPriv="aaa,ext-lan-policy,ext-lan-qos,ext-san-policy,operations,
pod-policy,pod-qos,read-only"
6 outDomains="mgmt02-dummy"
7 outChannel="noencssl"
8 outEvtChannel="noencssl">
9 </aaaLogin>
Each line in the response should be interpreted as follows:
-
Specifies the method used to login.
-
Confirms that this is a response.
-
Provides the session cookie.
-
Specifies the recommended cookie refresh period. The default login session length is 600 seconds.
-
Specifies the privilege level assigned to the user account.
-
The outDomains value is
mgmt02-dummy
. -
The outChannel value of
noencssl
declares that this session is not using encryption over SSL. -
The outEvtChannel value of
noencssl
declares that any event subscriptions would not use encryption over SSL. -
Closing tag.
Alternatively, you can use the cURL utility to log in to the XML API, as shown in the following example:
curl -d "<aaaLogin inName='admin' inPassword='password'></aaaLogin>" http://192.0.20.72/nuova
If HTTPS is enabled, you must use HTTPS in the cURL command, as shown in the following example:
curl -d "<aaaLogin inName='admin' inPassword='password'></aaaLogin>" https://192.0.20.72/nuova
Refreshing the Session
Sessions are refreshed with the aaaRefresh method, using the 47-character cookie obtained either from the aaaLogin response or a previous refresh.
<aaaRefresh
inName="admin"
inPassword="mypasword"
inCookie="real_cookie"/>
Logging Out of the Session
Use the following method to log out of a session:
<aaaLogout
inCookie="<real_cookie>" />
Unsuccessful Responses
Failed login:
<aaaLogin
response="yes"
cookie="<real_cookie>"
errorCode="551"
invocationResult="unidentified-fail"
errorDescr="Authentication failed">
</aaaLogin>
Nonexistent object (blank return indicates no object with the specified DN):
<configResolveDn
dn="sys-machine/chassis-1/blade-4711“
cookie="<real_cookie>“
response="yes">
<outConfig> </outConfig>
</configResolveDn>
Bad request:
<configConfMo
dn="fabric/server“
cookie="<real_cookie>“
response="yes“
errorCode="103“
invocationResult="unidentified-fail“
errorDescr="can't create; object already exists.">
</configConfMo>