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}

Integration Hints for Serverless Integration

The integration may run in a serverless context and is often subscribed to a message queue, which gives updates to an entity that should be updated at fulfillmenttools.

Let's assume that this queue publishes listing updates, and the integration needs to update the corresponding listing in the fulfillmenttools platform.

In a serverless infrastructure, typically, no shared database or memory is present to share JWT tokens. Therefore, for each listing update, the function needs to obtain a token and then perform the listing update. This can cause issues if implemented naively, since the Google Identity Platform - Quotas limitations apply.

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

Option 1: Best Practice

If you use an external IDP (recommended), you can use the client credentials flow and use this token to authenticate via signInWithIdp. See Client-Credential-Flow with IdP for a detailed explanation. This approach prevents the per-user limit from affecting your usage.

Option 2: Iterate over Multiple Users

Due to the limitations of the Google Identity Platform (Google Identity Platform - Quotas), users cannot log in multiple times in parallel. After making several token requests, you may encounter quota errors while trying to obtain a token.

To address this issue, we recommend creating multiple user accounts (e.g., 20) and randomly selecting one of these users to request the token. This approach helps distribute the load across different users, preventing any single user's limit from being exceeded.

Authorization

fulfillmenttools has a simple, preconfigured roles and permissions system. 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. Furthermore, it is possible to create custom roles, see User Management for details.

There is a fixed set of preconfigured 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.