Authentication and authorization

Authentication and authorization ensure secure access to the fulfillmenttools platform. This section explains how tokens are issued, how they are used in requests, how they can be refreshed, and how roles and permissions control access.

Authentication

More authentication information is available on the Google Identity Toolkit API website.

The fulfillmenttools platform is secured using an external Identity Provider (Google Identity Toolkit). This provider issues JSON Web Tokens (JWT) in exchange for a valid username and password. The JWT encodes attributes such as the username, role, and assigned facility. Authorization against the API requires including the issued JWT in every request as an HTTP header.

Providing the JWT

All authenticated requests must include the following header:

Authorization: Bearer {YOUR_ID_TOKEN}

Authentication request

To retrieve an authentication token for a user, send an HTTP POST request:

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

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

authKey, email, and password must be valid for the fulfillmenttools instance
The email must follow the format: <username>@ocff-<tenantName>-<environment>.com.
The identity platform enforces a rate limit of 2000 logins per 60 seconds. This limit can be raised if required.
Additional rate limits apply to calls for new tokens based on username and password (see Google Identity Platform Quotas).

Caching and sharing tokens between function invocations may be necessary in connector implementations to avoid exceeding quotas.

Authentication response

A successful response is similar to the following example:

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

Key attributes:

The idToken is the JWT that must be sent with every REST call to the fulfillmenttools API. It has an expiration period defined by the expiresIn attribute, which is 3600 seconds in this example. After this period, a new token must be requested.
The refreshToken should be used to obtain a new token without providing the user 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 request:

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 provides a preconfigured roles and permissions system. A valid authentication is required before authorization is applied. Roles determine which data a user can access. Custom roles can also be created. Permissions define individual actions within the system, such as editing users or creating orders. See User Management for details.

REST endpoints require specific permissions to be accessed. Endpoints are annotated with required permissions in the OpenAPI specification.

openapi: 3.0.0
info:
  title: Stock API
  version: 1.0.0
paths:
  /api/stocks:
    post:
      operationId: createStock
      summary: Create a stock
      deprecated: false
      description: ""
      x-fft-permissions:
        - STOCK_WRITE
        - STOCK_READ

Last updated 5 days ago