2. Authentication-Related Calls

July 14, 2021

On this page

getSessionKeyUser
getSessionKeyInfo
getJwtToken
getIdentityToken

These are the calls you need when user is already logged-in (your application or service has obtained a session key from somewhere) and you would like to retrieve information about the current session. This is the data that verifyUser usually outputs: who is the user, what group they belong to and what are their authentication tokens.

getSessionKeyUser returns the full dataset. Its output is equal to verifyUser.

getJwtToken and getIdentityToken return just one field each: the current session's "Erply JWT" (JSON Web Token) and "Identity JWT", respectively. Both are present in getSessionKeyUser as well.

getSessionKeyInfo returns two more data points which are not available elsewhere: current session's creation time and expiration time.

verifyOAuthToken
createUserFromOAuthToken

These calls are meant for integrations with corporate Single Sign-On (SSO) systems. The requirement is that the Single Sign-On system must output JSON Web Tokens.

verifyOAuthToken can validate a provided JWT. If the token is valid, and the user name exactly matches a user name in Erply, the user is logged in to Erply.

If such user does not exist in Erply yet, it can be created with createUserFromOAuthToken. Erply will inspect the permissions in JWT and expects one of them to identify the user's group.

To set up an integration, you need to call setOAuthConfiguration and 1) specify the SSO system's public key URL, 2) describe how token permissions map to Erply user group IDs.

This configuration can be retrieved with getOAuthConfiguration.

verifyIdentityToken
createUserFromIdentityToken

The following article has a few more details on the Identity service in general.

These API calls make up an integration that predates the current automatic sync of users from Erply to Identity. Here, the premise was that Erply's and Identity's user registries are separate, and Identity was treated effectively as a standalone SSO system. These calls implement the same kind of workflow that we later re-created, more generically, with verifyOAuthToken and createUserFromOAuthToken (see above).

Still, verifyIdentityToken is useful for two use cases:
  1. If user initially logged into Identity and worked with an Identity app, and the app would like to "redirect" user to Erply back office, the verifyIdentityToken call can "exhange" the JWT for a session key.
  2. Or, if a backend service has been given an Identity JWT (for whatever reason), and the service needs to make additional calls to Erply API, it can similarly "exchange" the token for an session key.
The verifyIdentityToken call:
  1. Validates an Identity JWT.
    1. (Or an Erply JWT, for that matter. Identity and Erply JWTs have both been created with the same cryptographic key, so this call can validate both.)
  2. If there is a user with the exact same user name (email address) in Erply, creates and returns a session key for that user.
  3. If there is no user with that username, you can create it with createUserFromIdentityToken.
    1. After creating the user, it is possible to retry calling verifyIdentityToken — but since the created user does not belong to a user group, it would return an error code. This can be resolved by account administrator by editing the user (in Settings > Users in back office) and assigning the user a group.
When making the verifyIdentityToken call repeatedly with the same token, it always returns the same session. Only if the "stored" ("cached") session has expired, it will create a new one; but the lifetime of the session is set equal to the lifetime of the token.
 

switchUser

This call is for point-of-sale applications, to implement user switching with PIN.

As the name implies, "user switching" requires someone else to be logged in first; if nobody has authenticated yet with their user name and password, it is not possible to switch, either. The call requires the previous user's session key.