Authentication

Authentication
calac41
Authentication (also known as identity management) controls who can see and use your APIs. API calls communicate with the API Server using JSON/REST. The REST API is always accessed using an authentication token. Authentication tokens are required for all REST calls except the 
@authentication
@heartbeat
, and 
@license
 resource endpoints.
Your API can:
  • Validate API user login credentials (username/password combination) using the built-in authentication provider.
    For more information about how to manage API users using the built-in authentication provider, including how to associate API users to an authentication token by defining the email address as the login ID that corresponds to this authentication token, see Manage API Users using the Built-in Authentication Provider.
  • Use authentication tokens directly.
This information in this article is about how to use authentication tokens directly. The articles in this section describe how to administrate API users.
For more information about authentication providers, see Authentication Providers.
In this article:
 
 
3
 
 
How to Generate API User Authentication
API user authentication results in a new authentication token. The authentication token indicates a set of roles that define what the API user is authorized to do. The client passes this authentication token on all subsequent requests. 
Use the following process to generate API user authentication:
Obtain an Authentication Token
Applications can obtain an authentication token using one of the following methods:
For more information about authentication tokens, including a list of authentication token attributes, see Auth Tokens.
Obtain an Authentication Token Dynamically During Sign-On
You can authenticate an API user and obtain an authentication token dynamically during sign-on using the 
@authentication
 resource endpoint. Clients can use the authentication token with every request to the server. API Server calls the custom authentication provider. API Server is passed the credentials (for example, user and login) and returns the list of roles it uses for authorization.
API Server generates a new authentication token for every successful request to the 
@authentication
 resource endpoint.
The following is an example.
URL:
 
The following URL obtains the authentication token using the 
@authentication
 resource endpoint for the
built-in authentication
authentication provider:
http://<base_api_creator_url>/rest/default/demo/v1/
@authentication
Payload:
 
The following request body defines the authorized API user:
{
"username": "<the API user's username>",
"password": "<the API user's password>"
}
Response:
 
The following response is expected:
{
"apikey": "<the generated authentication token>"
"expiration": <the authentication token's expiration date>"
"email": "<the API user's email address>"
 You can create the authentication token and test the
@authentication
resource endpoint in the REST Lab.
Obtain an Authentication Token using API Creator
With proper authorization, you can obtain an authentication token using API Creator.
These authentication tokens are not associated with API users and are typically used for machine-to-machine situations. In many ways, they are like plaintext passwords. Use care in sharing the authentication tokens. Use care when overriding the string that 
CA Live API Creator
 specifies. We recommend that you access resources for the selected roles using the authentication token. Edit the authentication token value only if you want to make the authentication token public.
Follow these steps:
 
  1. With your API open, in the Manage section, click 
    Auth Tokens
    .
    The Key page appears by default.
  2. Click 
    Add
    .
  3. Modify the following fields and then save your changes:
     
    Auth Token label
     
    The identifying string appropriate for recognizing in a list, for example, Rest Lab.
     
    Token
     
    The value that must be passed along for the REST calls to be properly authenticated. You can specify a value or you can use the randomly-generated value.
     
    User identifier
     
    The login ID that corresponds to this authentication token. Define this field if you associate authentication tokens with API users.
     
     
    Best Practice: 
    If you specify a value, we recommend a value that is different than the identifier for an API user.
     
     
    Required: 
    No
The authentication token is created.
Use HTTP Basic Authentication to Return an Authentication Token
When you enable HTTP basic authentication for an API, you can use HTTP basic authentication to return an authentication token. API Server passes the username and password for the API user it receives to the authentication provider. The HTTP basic authentication username cannot contain a colon (:).
When validated, API Creator generates the authentication token. 
CA Live API Creator
 avoids calling the authentication provider for each request by caching this generated authentication token for a short timeframe.
Your authentication provider might force the authentication provider to be called more frequently by setting the expiry time for the token to be short.
CA Live API Creator
 uses the 
Realm (Protection Space)
 value for the realm in the WWW-Authenticate Challenge response. If you do not specify a 
Realm (Protection Space)
 value, 
CA Live API Creator
 omits the realm from the WWW-Authenticate Challenge response. 
CA Live API Creator
 encodes the value with UTF-8 before it sends it. It replaces invalid characters within the realm-quoted string with an ASCII space (x20) characters.
HTTP authentication references:
How HTTP Basic Authentication Works in API Creator
To see how HTTP basic authentication works in API Creator, complete the following:
  1. Create an API.
    For more information about how to create an API, see Create your API.
  2. Define the 
    built-in authentication
     authentication provider as the authentication provider for the API.
    For more information, see API Properties.
  3. Enable HTTP basic authentication.
    For more information about how to enable HTTP Basic Authentication, see API Properties.
  4. Add an API user and assign a role to the API user.
    For more information about how to add API users and assign roles to API users if you are using the built-in authentication provider, see Manage API Users using the Built-in Authentication Provider.
  5. Perform a GET on a resource using a browser or using an HTTP client tool such as cURL.
    For example:
    The URL in this example is for the single-user demonstration package of 
    CA Live API Creator
     that is based on Jetty.
    curl --trace - -X GET "http://demo:[email protected]:8080/rest/default/demo/v1/demo:customer"
     
    demo:Password
     is the 
    <username>:<password>
     that basic auth uses.
Specify the Authentication Token on API Calls
Prerequisite:
 You have obtained the authentication token. You can specify the authentication token using the following methods:
  • (GET requests only) Specify it in the URI.
     This method is not secure. This method is recommended only when it is not convenient to put the authentication token in a header. For example, if you want to try your API from a Web browser. Browser caches and web log files contain the authentication token in plaintext.
Specify the Authentication Token in the HTTP Header
Specify the authentication token in the HTTP header using the following syntax:
Authorization: CALiveAPICreator
<apikey>
:1
The header name is 
Authorization
. The authorization prefix indicates that this header is specifically for API Server.
While header name is 
Authorization
 , this header is used for authentication. The name of the header is dictated by the HTTP standard.
Specify the Authentication Token in the URI
Prerequisite: You have authorized API users to specify their authentication token on the URL.
For more information about authorizing API users to specify authorization parameters in URLs, see API Properties.
You can specify an authentication token in a REST call as a URL parameter only for GET requests. Use the following syntax:
curl -G https://server.acme.com/rest/acme/myproject/v1/customer?auth=
<apikey>
:1
View your Generated Authentication Tokens
With your API open, in the Manage section, click 
Auth Tokens
. The authentication token is listed in the authentication tokens list with a name such as 
Temp key for demo [….]
.
Advanced Usage
You can change passwords and validate an existing authentication token using the authentication service.
Disable an Authentication Token
You can disable the authentication token by including the 
apikey
 attribute and setting the 
disable
 attribute to 
true
 in the payload:
Use the following syntax in the payload:
{ "apikey": "1234567890abcdef12345", "disable": true }
 
Response
 
If the authentication token is still valid and active, the following response is expected:
{ "apikey": "1234567890abcdef12345", "disabled": true }
The authentication token is disabled. This is idempotent and is considered a success even if the key has already expired or has been marked as disabled. An error is returned if the authentication token is not found.
Revalidate the Authentication Token
You can revalidate the authentication token and check the expiration date by including the 
apikey
 attribute in the payload.
Use the following syntax in the payload of a POST request:
{ "apikey": "1234567890abcdef12345" }
 
Response
 
The following response is expected:
{ "apikey": "1234567890abcdef12345", "expiration": "2014-12-31T23:59:59.999"}
The existing expiration date for the authentication token is returned. If the authentication token has expired, an expired error is returned. If the authentication token is valid, a normal response is returned as though the API user had logged in successfully to API Creator using their username and password. The existing authentication token (with its original expiry) is returned.
Post Password Change Authentication Requests with Custom Authentication Providers
When you POST a password change authentication request, on successful log in, 
CA Live API Creator
 calls the 
authenticate()
 method with 'true' value for the 
enablePasswordChange!
 argument. Your custom authentication provider may implement or ignore as it sees fit.