Creating APIs‎ > ‎Security‎ > ‎

Authentication

Authentication (also known as identity management) controls who can see and use your APIs. API calls communicate with the API Server using JSON/REST.

How to Generate User Authentication

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. Almost all REST calls require the auth token, with a few exceptions.

For more information about authorization, see Authorization.

Use the following process to authenticate a user:

  1. Obtain an auth token.
  2. Specify the auth token on API calls.

Obtain an Auth Token

The API Creator key generation service (the authentication service) automatically creates auth tokens. You can also create them using the API Creator, the API, or the command line.

For more information about auth tokens, including a list of auth token attributes, see Auth Tokens.

Obtain an Auth Token Automatically During Sign-On

Applications can obtain a new auth token during sign-on using the authentication service. This is the most common method of obtaining an auth token. For testing purposes, you can create this by way of the REST Lab.

Example

In this example, you obtain an auth token in a URLdefine an authorized user in the request body using the @authentication resource endpoint for the built-in authentication provider, and then POST the credentials.

URL:

http://localhost:8080/rest/default/demo/v1/@authentication

Request body:

{ "username": "demo", "password": "Password1"}

The following image shows this example on the Execute, REST Lab, Request tab:

The generated auth token is shown as the apikey property value in the Response section. You can use the auth token with every request to the server. API Server determines what authenticated API calls are authorized to do by looking at the roles assigned to the auth token.

The auth token displays on the Manage, Auth Tokens, Key tab in the Auth Tokens list with a name such as "Temp key for demo [….]." The key's User identifier field is set to 'demo'. A new auth token is generated for every successful @authentication request.

For more information:

Obtain an Auth Token using API Creator

If you have proper authorization, you can obtain an auth token using API Creator. These are auth tokens that are not associated with any user and typically used for machine-to-machine situations. In many ways, they are like plaintext passwords and you should use care in sharing the auth tokens.

Important! 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 open, go to Manage, Auth Tokens, Key tab and click Add.
  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.

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 auth token. Set this if you associate auth tokens with named users. If you specify a value, we recommend a value that is different from an actual user's identifier.

Required: No

The auth token is created.

Specify the Auth Token on API Calls

After you have obtained the auth token, you can specify it on all API calls by specifying the auth token in the HTTP header or in the URI.

Specify the Auth Token in the HTTP Header

The name of the header is Authorization. The authorization prefix indicates that this header is specifically for the API Server.

Note: It is easy to get confused. While named authorization, the Authorization header is used for authentication. This is dictated by the HTTP standard.

For all calls including GET, as an HTTP header. For example:

Authorization: CALiveAPICreator <apikey>:1

(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 auth token 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 authorized users of this API to specify their auth token on the URL. For more information about authorizing users to specify authorization parameters in URLs, see API Properties.

For GET calls, as a URL parameter. For example:

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

Important! Specifying auth tokens in a REST call as a URL parameter can be convenient for debugging but is not secure.

Authentication Provider

The authentication provider authenticates login credentials (typically a user/password) and returns a set of roles and optionally some extra information.

Note: User definition applies to accessing your API. It does not apply to accessing API Creator.

Security involves authentication and authorization. You can define users in API Creator using:

  • The built-in authentication provider.

In most cases, production uses custom authentication, where you can authorize users using existing security data, such as Lightweight Directory Access Protocol (LDAP), Microsoft Azure Active Directory (AD), and OAuth. The built-in authentication provider might be enough to get you started.

  • A custom authentication provider using JavaScript.

You can supply your own authentication provider to use corporate security services. Live API Creator includes authentication provider samples.

For more information about these samples, see Authentication Providers.

The following image shows the Authentication provider field where you define the authentication provider for your API, on the Create, API Properties, Details tab:

For more information:

Use the Built-in Authentication Provider

To simplify development, you can use the built-in authentication provider, which is specified by default. This authentication provider defines users and passwords and the authentication service.

You also can:

  • Define authorized users for APIs using the built-in authentication provider, including the login ID, password, and roles, and API Creator converts a set of credentials into a usable auth token using the authentication service.
  • (For each user) Specify a set of authorized roles and global values/objects.

For more information about setting authorization and global values, including auth token globals, see Role-Based Endpoint Access.

  • Use the set of global values, in addition to those values you explicitly add, in the resource and security filters that the built-in authentication provider provides.

For more information about the built-in authentication provider, including how to add users programmatically using the REST API, see Manage Users using the Built-in Authentication Provider.

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 API Creator.

Go to Manage, Users, User info.

Use a Custom Authentication Provider

For more information about defining a custom authentication provider using JavaScript, including information about the @authenticate endpoint, see Define a Custom Authentication Provider using JavaScript.

For more information about this API option, see API Properties.

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 apikey attributes and the disable attribute is set to 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, given the following payload:

 { "apikey": "1234567890abcdef12345", "disable": true }

The following response (if the auth token is still valid and active) is expected:

 { "apikey": "1234567890abcdef12345", "disabled": true }

Revalidate the Auth Token

If the payload for the authentication request contains a single apikey attribute, the authentication provider is not called. Instead, the auth token 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 auth token (with its original expiry) is returned.

For example, you can POST the following message:

 { "apikey": "1234567890abcdef12345" }

The following response is expected:

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

Change the Password Using the Authentication Provider

You can change passwords (when the underlying authentication provider implements it) using authentication provider. Enable this by providing the enablePasswordChange! query parameter, sending in the updated credentials (as required by the underlying authentication provider). The built-in 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 built-in 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 you 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.