Docs‎ > ‎Logic Designer‎ > ‎Security‎ > ‎

Authentication

All communication with the Espresso Logic 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 API key, which is passed on all subsequent requests, and indicates a set of roles that define what the API key is authorized to do.

API Keys

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

An API Key is a (typically) long string with 2 nodes, such as abcdefg:1.  The first part is the API key (abcdefg). The second part 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 API key

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


Automated creation

Most commonly, applications can obtain a new API Key during sign-on, using Espresso's 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://houston.d.espressologic.com/rest/abl/demo/v1/@authentication
  • and POST credentials such as 
       { "username": "sam", "password": "Password1"} 
    (as 
    shown below) for the Default Authentication Provider: 


The response property "apikey" is the 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 API Keys 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 API key using the Logic Designer.   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 API Key is all that's required to access the system. The only time you should edit the value of an API key is if you want to make it public, and therefore more memorable.

In the diagram below:

  • Key is the actual API Key you would include in your code
    • API 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 API Key

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

In a header

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

Authorization: Espresso 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 Espresso prefix indicates that this header is specifically for Espresso Logic Server. 

In the URI (GET requests only)

It is possible to include the API Key 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://eval.espressologic.com/rest/val/demo/v1/customer?auth=abc123def456ghi789:1
   

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, Espresso Logic pre-supplies a simplified Authentication Provider that returns an API Key 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 Espresso Logic.  You can manage this list with supplied APIs, or via the Logic Designer:



When you create User, you specify the Id and the Password.  The system then creates an API Key.  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 two 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 Espresso Logic 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.


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.

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

This will return a result of (if the API Key is still valid and active)
     { "apikey": "1234567890abcdef12345", "disabled": true }
   
API Key Re-Validation
If the payload for the authentication request contains a single 'apikey' attribute, the authentication provider is NOT called.  Instead, the API Key is validated, and checked for expiration.  The existing expiration date for the API Key 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.