Auth Schemes

Auth Schemes allow third party applications to make server-to-server calls to the Elements APIs without needing to login or supply user credentials. Auth Schemes leverage the use of JWTs to accomplish the task. In addition to creating user credentials, it is possible to use the signed JWTs to transparently sync user accounts information with existing services.

Once imported via auth scheme, users within Elements have the same privileges as if they had signed up directly with Elements. Furthermore, it is possible to provide short term API keys directly to a webapp, thereby obviating the need to use direct server to server calls in favor of having the page call Elements directly.

For help creating an auth scheme, see the Generating Auth Scheme article within the Auth Scheme section of this manual.

Creating a JWT From Third Party Code

Once you have defined your Auth Scheme in the console, you may use the private key associated with the scheme to make direct API calls.

The basic process for using the auth scheme to generate API keys are as follows: 1. Define an auth scheme. Either supply or allow Elements to generate a private/public key pair. 2. Import that private key pair into your existing web application. Ideally using your cloud provider's secure credential storage. 3. Generate a signed JWT using the private key associated with the auth scheme on your server application. 3. Once you have the signed JWT, you may use the token one of two ways: 1. Return the signed JWT to the web or mobile application via API call and allow the page or the application to make direct calls to Elements APIs. 2. Directly call the Elements APIs from the server application.

Note: never share your JWT Private Key with the client application. The private key is sensitive information and should always be treated as such.

Constructing the JWT

In order to successfully use the auth scheme, you must supply certain claims with the JWT. This supplies the information necessary for Elements to match the user to its own internal database.

Standard JWT Claims

The following section lists the standard JWT claims that Elements understands and how it interprets each claim when making a request. Refer to RFC-7519 Section 4.1 for a detailed explaination of standard registered claims.

iss - Issuer

iss represents the issuer of the token. This should be a valid identifier for your application. See the Application API for more information. If specified, this must match the unique name of an Application configured within Elements.

aud - Audience

aud represents the Audience. In the context of the Elements security model, this must match the configured auth scheme. If no configured auth scheme matches, then the server will fail the request.

exp - Expiration

exp represents the expiration date. Elements will reject any token which has expired. If left unspecified, the token will last indefinitely.

We do not recommend using permanent tokens as it creates a security vulnerability within your app.

sub - Subject

sub (or subject). This is the literal value used to key the user. See the elm_userkey below for more information.

Private Claims

In addition to standard JWT claims, Elements supports the following private claims. For more information on Private Claims, see RFC-7519 Section 4.3. Elements prefixes all claims with elm_ to avoid collisions with other private claim names.

elm_atype - Elements Auth Type

This must be present and must be the literal value custom. This is intended to futur proofing as Elements may support multiple auth scheme configurations based on changing requirements and needs.

elm_userkey - Elements User Key

This must be present and must contain the key of the user model through which Elements will uniquely identify the user. The supported values are as follows.

  • email - the user’s email address.
  • name - the user’s unique username.
  • facebookId - The user’s Facebook ID.
  • firebaseId - The user’s Firebase ID.
  • appleSignInId - The user's Apple Sign-In ID.
  • externalUserId - The User's external user ID.

In most cases we recommend passing your user's primary database ID to externalUserId which will ensure no name or email collisions in case a user changes or updates their email within your web application.

elm_user - Elements User

This is a full JSON document containing a User object. See Users and Profiles and the Swagger documentation for the contents of this document.

Upon receipt of the JWT containing this document, Elements will automatically sync the user information from the supplied document. In order to avoid excessive round-trip database traffic, Elements may opt to pool, batch, or otherwise delay updates to its own database when processsing JWT requests. However, the entire user document must exist in the JWT.