Authentication

Authentication
lac31
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 user login credentials (username/password combination) using the built-in authentication provider.
    For more information about managing users using the built-in authentication provider, including how to associate a user to an authentication token by defining the email address as the login ID that corresponds to this authentication token, see Manage Users using the Built-in Authentication Provider.
  • Use authentication tokens directly.
The information in this article is about how to use authentication tokens directly.
For more information about authentication providers, see Authentication Providers.
In this article:
3
How to Generate User Authentication
User authentication results in a new authentication token. This authentication token is passed on all subsequent requests and indicates a set of roles that define what the authentication token is authorized to do.
Use the following process to generate 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 obtain an authentication token dynamically during sign-on using the 
@authentication
 resource endpoint. You can use the authentication token with every request to the server. API Server determines what authenticated API calls are authorized to do by looking at the roles that are assigned to the authentication token. A new authentication token is generated for every successful 
@authentication
 request.
You can create the authentication token by way of the REST Lab.
The following is an example.
URL:
The following URL obtains the authentication token using the 
@authentication
 resource endpoint for the built-in authentication provider:
http://<base_api_creator_url>/rest/default/demo/v1/
@authentication
Payload:
The following request body defines the authorized user:
{
"username": "<the admin user's username>",
"password": "<the admin user's password>"
}
Response:
The following response is expected:
{
"apikey": "<the generated authentication token>"
"expiration": <the authentication token's expiration date>"
"email": "<the admin user's email address>"
You can 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 any user and typically used for machine-to-machine situations. In many ways, they are like plaintext passwords. Use care in sharing the authentication tokens.
Use caution 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.
  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 users.
    Best Practice:
     If you specify a value, we recommend a value that is different from an actual user's identifier.
    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 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 this value, 
CA Live API Creator
 omits the realm from the WWW-Authenticate Challenge response and 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 Project.
  2. Define the authentication provider as the built-in authentication provider.
    For more information about how to define the authentication provider, see Authentication Providers.
  3. Enable HTTP basic authentication.
    For more information about how to enable HTTP Basic Authentication, see API Properties.
  4. Add a user and assign a role.
    For more information about how to add users and assign roles to users, see Manage 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.
    curl --trace - -X GET "http://demo:[email protected]:8080/rest/default/demo/v1/demo:customer"
    Basic auth uses 
    demo:Password
     as the 
    <username>:<password>
    .
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 the header name is 
Authorization
CA Live API Creator
 uses this header for authentication. The name of the header is dictated by the HTTP standard.
Specify the Authentication Token in the URI
Prerequisite:
 You have authorized users of this API to specify their authentication token on the URL.
For more information about how to authorize 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 user had logged in successfully with 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.