Docs‎ > ‎API Creator‎ > ‎Security‎ > ‎

Authentication

API calls communicate with the API Server using JSON/REST. 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 auth token is authorized to do.

For more information about authorization, see Authorization.

REST calls require the auth token (with a few exceptions). Calls that do not include an auth token are returned with HTTP status code 401.

An auth token is a (typically) long string with 2 nodes, such as abcdefg:1. The first part (abcdefgis the apikey. The second part (:1) is unused but maps to your roles for authorization.

For more information about auth tokens, see Auth Tokens.

Standard User Authentication Generation Process

Obtain an Auth Token

You can obtain an auth token using the automated-creation or manual-creation method.

Automated Creation

This is the most common method to obtain an auth token. Applications can obtain a new auth token during sign-on, using the API Creator key generation service. For testing purposes, you can create this via the REST Lab as shown below.

Example

In this example, you have a user defined as follows (this example using the built-in Authentication Provider). 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"} 
for the Default Authentication Provider: 
You can use response property "apikey" as the auth token value with every request to the server. API Creator uses this to find the roles for authorization. This generated key displays in the Auth Tokens list with a name like 'Temp key for demo [….]' and the User Identifier value for the key is set to 'demo'. A new key is generated for every successful @authentication request.

For more information about authorization, see authorization.

Manual Creation

If you have proper authorization, you can manually create an auth token using 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.

Use caution when overriding the string that Live API Creator specifies. We recommend that you access Live API Creator resources for the selected roles using the auth token. Edit the auth token value only if you want to make it public, and therefore more memorable.

  1. With your API project open, go to Manage, Auth Tokens, Key tab. The following image shows this page:
  2. 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.

Key

The actual auth token you would include in your code.

User identifier

The login ID that corresponds to this auth token. Set this if you associate auth tokens with named users. If you do provide a value, we recommend a name that is clearly different from an actual user's identifier.

Specify the Auth Token on API Calls

After you have obtained the auth token, you can specify it on all API calls using the following methods:

Specify the Auth Token in the HTTP Header

Specify the auth token in an HTTP header in the call. For example:

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 the API Server. 

(GET Requests Only) Specify the Auth Token in the URI

You can include the auth token in the URI for GET requests. We do not recommend this since browser caches, web log files, etc. contain the key in plaintext. Specify the auth token in the URI only when it is not convenient to put the auth token in a header, for example, if you want to try your API from a web browser).

Prerequisite: You have enabled this setting. Select the Permit Authorization parameter in URL checkbox on the API Properties > Settings page.

Specify the auth token in the URI. For example:

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

Authentication Provider

The authentication provider authenticates login credentials (typically a user/password) and returns a set of roles and optionally some extra information. You can supply your own provider to use corporate security services or use the provided default authentication provider. Sample authentication providers are available from GitHub for Windows Azure AD, SQL LDAP, and more.

API only

User definition applies to accessing your API.  

It does not apply to accessing the Logic Designer.


Use the Default Authentication Provider

To simplify development, Live API Creator includes a simplified authentication provider. This default authentication provider is selected by default. This authentication provider defines users and passwords and a service to convert a set of credentials into a usable auth token. If you plan to use auth tokens directly, choose None.

When you create a user, you specify the Id and the password. Live API Creator creates the auth token. For each user, you can also specify:
  • A set of authorized roles
  • A set of global values/objects
You can use the set of global values in resource and security filters, in addition to those you explicitly add, that the default authentication provider provides.

Manage the List of Valid UserId/Passwords in the Schema

Live API Creator maintains the list of valid userId/passwords in a schema. You can manage this list with supplied APIs or by way of Live API Creator.

Go to Manage, Users, User info.

Use a Custom Authentication Provider

Security involves authentication and authorization. You can define users in Live API Creator using default authentication (intended mainly for development). In most cases, production uses custom authentication, where you can authorize users using existing security data, such as LDAP and Microsoft Azure Active Directory (AD).

The Custom Authentication Provider is a plug-in JavaScript module that the system calls when a user authenticates using the special end point @authenticate. It is passed the credentials (user, login, etc), and returns the list of roles used for authorization.

Note:
 When you use a Custom Auth Provider, users you define in Live API Creator are not used.

The default authentication provider might be enough to get you started. You may 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. For more information about defining your own authentication provider using JavaScript, see Define a Custom Authentication Provider using JavaScript.

Live API Creator includes the following sample authentication providers:
  • HelloWorldAuthenticationProvider.js. This authentication provider 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. You can change the prompt and the secret word.
For more information about the Hello World authentication provider, see Hello World Authentication Provider.
  • StormpathAuthenticationProvider.js. This real provider uses Stormpath for authentication, roles, and user data. It demonstrates integration with LiveBrowser and with the Designer.
For more information about this authentication provider, see the Stormpath site.
  • RESTAuthSecurityProvider.js. This custom authentication provider is provided in the Business to Business Example.

For more information about the Business to Business Example, including the RESTAuthSecurityProvider.js custom authentication provider, see Business to Business Example.

Advanced Usage

You can change passwords and validate an existing auth token using the authentication service.

Disable an Auth Token

If the payload for the authentication request contains the two attributes 'apikey' and 'disable':true, the Auth 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 auth token is not found, for example:
 { "apikey": "1234567890abcdef12345", "disable": true }

This returns 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 is 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" }

and the following response is expected:

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

Password Change

You can change passwords (when the underlying authentication provider implements it) using authentication service. Enable this by providing the enablePasswordChange! query parameter, sending in the updated credentials (as required by the underlying authentication provider). The default authentication provider requires the newPassword attribute with a value containing the new password.

POST a message such as with '?enablePasswordChange!' the URL:

Note: 
The string is case-sensitive and includes 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, the changePasswordResult and changePasswordMesssage parameters are added. The changePasswordResult parameter has a value of 'success', 'failure', or 'notSupported'. The changePasswordMessage parameter is a string describing the result. For 'failure', this is the underlying reason.

Note: The login is considered successful and a new auth key generated and returned regardless of the result of the changePassword actions. 

Custom Authentication Providers

When your POST a password change authentication request, on successful login, the authenticate() method is called with 'true' value for the enablePasswordChange! argument. The authentication provider may implement or ignore as it sees fit.