Docs‎ > ‎CA Live API Creator‎ > ‎Security‎ > ‎

Authentication

All communication with the API Creator server is done by API calls using JSON/REST.  This is the only way to talk to a server.  User Authentication results in a new Auth Token, which is passed on all subsequent requests, and indicates a set of roles that define what the API key is authorized to do.

Auth Token

Every REST call must be done with an Auth Token (with a few exceptions).  Any call that does not include an AuthToken will return immediately with HTTP status code 401.

An Auth Token is a (typically) long string with 2 nodes, such as abcdefg:1.  The first part is known as the apikey (abcdefg). The second part (:1) is currently unused, but will be used for stronger authentication in a future release.  Internally, the system maps this to your roles for authorization.

Creating an Auth Token

As described below, you must supply an Auth Token on every request.  This sections shows that you can create (obtain) anAuth Token in one of two ways described below.


Automated creation

Most commonly, applications can obtain a new API Key during sign-on, using API Creator key generation service.   For testing purposes, you can create this via the REST Lab as shown below.  

Let's assume you have a user defined as follows (this example using the built-in Authentication Provider):


As shown below, use the special @authentication Resource End Point:
  •  a URL such as 
       http://localhost:8080/rest/default/demo/v1/@authentication
  • and POST credentials such as 
       { "username": "demo", "password": "Password1"} 
    (as 
    shown below) for the Default Authentication Provider: 


The response property "apikey" is Auth Token value you will use with every request to the server.  The system uses this to find the roles for authorization.  This generated key will appear in the Auth Token list (left menu) with a name like 'Temp key for demo [….]' and the User Identifier value for the key will be set to 'demo'.  A new key is generated for every successful @authentication request.

Manual creation

Alternatively, if you have proper authorization, you can manually create an Auth Token using the API Creator.   These are keys that are NOT associated with any user and typically used for machine-to-machine situations.  In many ways, they are like plaintext passwords and care should be used in sharing the keys.

The system will specify a string which you can override.  Do so with care - an Auth Token is all that's required to access the system resources for the selected roles. The only time you should edit the value of an Auth Token is if you want to make it public, and therefore more memorable.

In the diagram below:

  • Key is the actual Auth Token you would include in your code
    • Key label is an identifying string appropriate for recognizing in a list (e.g., using the Rest Lab)
  • User Identifier - manual keys are not associated with any user.  The value here is optional and used only for reporting.  If you do provide a value, we recommend a name that is clearly different from an actual user's identifier.



Supplying an Auth Token

You obtain an Auth Token as described above.  This section illustrates that, once obtained, you must supply it on all API calls.  You can specify your Auth Token in one of two ways:

In an HTTP Header

The call can include an HTTP header of the following form:

Authorization: CALiveAPICreator abcdefg:1

Header Name

It's easy to get confused.  While named authorization, this header is used for authentication.

This is dictated by the HTTP standard.
The name of the header is Authorization.  The authorization prefix indicates that this header is specifically for CA Live API Server. 

In the URI (GET requests only)

It is possible to include the Auth Token apikey in the URI for GET requests.  This is NOT recommended as browser caches, web log files, etc. will contain the key in plaintext.  When not convenient to put the API key in a header (for instance if you want to try your API from a web browser),  specify it in the URI (only for GET) as follows:

curl -G https://server.acme.com/rest/val/demo/v1/customer?auth=abc123def456ghi789:1
   

NOTE: You must enable this feature by setting API Properties/Settings "Permit Authorization parameter in URL"

Authentication Provider

The Authentication Provider authenticates that login credentials (typically a user / password) are correct, and returns a set of roles, and optionally some extra information.  You can supply your own provider to utilize corporate security services, or use the provided default, as described in the subsections below.

API only

User definition applies to accessing your API.  

It does not apply to accessing the Logic Designer.


Default Authentication Provider

To simplify development, API Creator pre-supplies a simplified Authentication Provider that returns an Auth Token based on a typical User Id / Password scheme as described below.  You elect this option when you create your project with Authentication Provider as Built-in Authentication.



The list of valid UserId/Passwords is maintained in a schema automatically created for your project by API Creator.  You can manage this list with supplied APIs, or via the API Creator:



When you create User, you specify the Id and the Password.  The system then creates an Auth Token.  For each User, you can also specify:
  • a set of authorized Roles

  • a set of Global Values/Objects
The Default Authentication Provider makes a set of global values available you can use in Resource and Security filters, in addition to those you explicitly add.

Custom Authentication Provider

The default authentication provider might be enough to get you started, but you will often need to use some external system, such as an LDAP server.

You can define your own authentication provider by writing a JavaScript function, loading it as a library into your project, and registering it as an authentication provider. This is described in detail in this page.

There are sample authentication providers:

    HelloWorldAuthenticationProvider.js - an extremely simple provider, that accepts a single value which must be the secret word specified in its configuration.  We recommend you use this in the Demo project to get familiar with the mechanisms required.  This example is configurable so you can change the prompt and the secret word.

    StormpathAuthenticationProvider.js - this is a real provider.  This uses Stormpath for authentication, roles and user data.  It demonstrates integration with LiveBrowser and with the Designer.

    RESTAuthSecurityProviderJS is provided in the Business to Business Sample.





Advanced Usage

In addition to the above standard user authentication/API key generation process above, the authentication service can be used to change passwords and validate an existing API key.

Disable an Auth Token
If the payload for the authentication request contains the two attributes 'apikey' and 'disable':true, the Auth Token will be disabled.  This is idempotent and will be considered a success even if the key has already expired or has been marked as disabled.  An error will be returned if the Auth Token is not found
  
 { "apikey": "1234567890abcdef12345", "disable": true }

This will return a result of (if the Auth Token is still valid and active)
   
 { "apikey": "1234567890abcdef12345", "disabled": true }
   
Auth Token Re-Validation
If the payload for the authentication request contains a single 'apikey' attribute, the authentication provider is NOT called.  Instead, the Auth Token apikey is validated, and checked for expiration.  The existing expiration date for the Auth Token will be returned.

If expired, an expired error is returned.  If valid, a normal response is returned as though the user HAD logged in successfully with username and password.  The existing apikey (with its original expiry) is returned.

POST a message such as

  
 { "apikey": "1234567890abcdef12345" }


Result is

     
  { "apikey": "1234567890abcdef12345", "expiration": "2014-12-31T23:59:59.999"} 

Password Change
The authentication service can also be used to change passwords (when the underlying authentication provider implements it.)  This must be enabled by providing the query parameter enablePasswordChange! AND sending in the updated credentials (as required by the underlying authentication provider).  For the default authentication provider, an attribute 'newPassword' with a value containing the new password is necessary.

POST a message such as with '?enablePasswordChange!' the URL.  Note the case-sensitive string with the trailing exclamation(!) mark.

  
 {"username": "myname", "password": "mypassword", "new_password": "mynewpassword"}


Note the 'new_password' is Authentication Provider dependant.  In this case, the default authentication provide understands the 'new_password' value.

In addition to the standard values returned, two additional parameters of changePasswordResult and changePasswordMesssage will be added.
changePasswordResult will be one of 
'success', 'failure', 'notSupported'.
changePasswordMessage will be a string describing the result.  For 'failure', this will be the underlying reason

Note, that the login WILL be considered successful and a new API Key generated and returned regardless of the result of the changePassword actions.
 
Custom Authentication Providers
When a password change authentication request is POST'd, on successful login, the authenticate() method will be called with 'true' value for 'enablePasswordChange!' argument.  The authentication provider may implement or ignore as it sees fit.