Authentication & authorization

Authentication

More authentication information can be found on the Google Identity Toolkit API website.

The fulfillmenttools platform is secured using an external Identity Provider (Google Identity Toolkit) that issues JWT tokens in exchange for a valid username and password. This JWT token securely encodes (among other things) your username, your role, and which facility you are assigned to. Authorization against our API works by using an issued JWT Token in every request as an HTTP header.

Providing the JWT

All requests to the fulfillmenttools platform requiring authentication should contain the following auth header:

Authorization: Bearer {YOUR_ID_TOKEN}

Authentication request

To retrieve an authentication token for a given user, send an HTTP POST call to this API endpoint:

POST https://identitytoolkit.googleapis.com/v1/accounts:signInWithPassword?key={authKey}

{
    "email": "[email protected]",
    "password": "myPassword",
    "returnSecureToken": true
}

authKey, email and password have to be valid to your fulfillmenttools instance and are being given to you when the instance was created. The email must follow the format: "<username>@ocff-<tenantName>-<environment>.com".

Overall logins, the identity platform enforces a rate limit of 2000 logins in 60 seconds. This limit can be raised if needed.

Furthermore, there is an imposed rate limit on calls towards the Google Identity Toolkit for new tokens based on username & password (see Google Identity Platform - Quotas). This could be especially relevant for connector implementations as it might be feasible to cache & share tokens between function invocations.

Authentication response

As a result, an answer looks similar to this response:

{
  "kind": "identitytoolkit#VerifyPasswordResponse",
  "localId": "jdwBuqqYWdYoqWTH1Xv85EJJMpm2",
  "email": "[email protected]",
  "displayName": "Willy Wonka",
  "idToken": "eyJhbGciOiJSUzI1NiIsImtpZ...ynLgbiNgHJJxtBXSTSFnp2fA",
  "registered": true,
  "refreshToken": "AE0u-NeGDdHWPB0RjOYO...pRMKoncagBq30OFCJkEgpvyI",
  "expiresIn": "3600"
}

Two attributes in the above response are of special importance:

1. idToken is the actual JWT you need to send along every REST Call you issue against the fulfillmenttools API. It has an expiration period depicted by the attribute expiresIn. In this case, it is valid for 3600 seconds. After that, you need to get a fresh token.

2. refreshToken should be used to get a fresh token without providing the credentials again.

Every call to the fulfillmenttools API must include the JWT in an Authorization-Bearer header.

Token Refresh

To refresh a token, send an HTTP POST call to this API endpoint:

POST https://securetoken.googleapis.com/v1/token?grant_type=refresh_token&refresh_token={refreshToken}&key={authKey}

Authorization

fulfillmenttools have a simple roles and permissions system that cannot be edited currently. Depending on the role, the corresponding user has access to data (or not) for which he has the necessary authorization. The prerequisite is, of course, a valid authentication.

A user must always have exactly one assigned role, reflected in the JWT. That means a role switch is available after a token refresh.

There is a fixed set of roles a user can take within the platform:

Role	Facility affiliation	Description
FULFILLER	yes	Takes care of the operative workflow, such as picking or packing. Users have primarily access to operatively needed parts of the system.
SUPERVISOR	yes	Supervisor role extends the role of the Fulfiller. It is allowed to configure the settings of certain facilities.
ADMINISTRATOR	no	The Administrator of a fulfillmenttools system is allowed to access all the functionality.