Authentication
API calls require proper authentication and have the same authorization requirements as those applied to direct access to Orchestrator through its web-based user interface.
There are a number of ways to authenticate API calls; these are described in the table below.
Authentication Model | Description |
---|---|
HTTP basic authentication (most secure) | HTTP basic authentication is supported and is recommended to developers as the
primary authentication model. The advantage of this method is that the credentials are
within each request but they are encoded versus being in plain text. The username and
password are combined into a string, "username:password", then they are
Base64-encoded and put in the HTTP Authorization header. For example:
|
API key or scrambled password | An API key and a scrambled password are generated for each Orchestrator user;
either of these values can be used in the REST URLs for authentication. For
example:
To
obtain the values for the API key or password, do the following:
|
Application cookie |
This can be used if the client is able to use cookies to maintain state information. Once the authentication is made, it will not be necessary to set the credentials again for additional calls. The user obtains the cookie from the authentication call by supplying a username and password. If this is a particular process that will only ask for a cookie once, then the logoff for that process will also need a cookie to correctly log off the user for which the cookie is set. The cookie should be supplied in the HTTP header. The host name in the URLs is defined as localhost in this document to represent the IP address or the fully qualified host name of your Orchestrator node. Below is an example of a cookie-style
request:
The following curl requests are used to obtain an authentication cookie.
After a successful authentication, the next URL (for example, one used to initiate a work order) can be called without providing the login and password parameters; this continues until the user is logged off.
Note: To enable CORS on an Apache server, replace the password= in the cookie request with api_key=.
|
Sample XML response for success:
<?xml version="1.0"?\>
<user time="2011-10-20 17:47:05 UTC" action="authenticate" id="1" login="admin"/>
Sample XML response for a bad password case:
<?xml version="1.0"?>
<error time="2011-10-20 17:45:39 UTC" action="status" id="0">#<RuntimeError:
Authentication failed></error>
Sample XML response for case in which the user does not exist:
<?xml version="1.0"?>
<error time="2011-10-20 17:48:09 UTC" action="status" id="0">#<RuntimeError:
Authentication failed></error>
http://localhost/aspera/orchestrator/users/logoff/xml
Sample XML response for logoff:
<?xml version="1.0"?>
<user time="2012-01-25 06:38:22 UTC" action="logoff" id="1" login="admin"/>