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 can be found 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 typical response looks like:

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

Key attributes:

• idToken: The JWT required for all REST calls. It expires after the period defined in expiresIn (e.g., 3600 seconds).

• refreshToken: Used to obtain a new token without re-entering credentials.

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 in serverless contexts

In serverless environments, functions often subscribe to message queues that trigger updates (e.g., listing updates). Since no shared memory or database is available, each function invocation may need to obtain a token before performing updates.

This can cause quota issues if implemented naively. The identity platform enforces a rate limit of 2000 logins per 60 seconds.

Option 1: Best Practice Use an external Identity Provider with the client credentials flow (signInWithIdp). This avoids per-user login limits. See Client-Credential-Flow with IdP for a detailed explanation.

Option 2: 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, there may occur quota errors while trying to obtain a token.

• To address this issue, create multiple user accounts (e.g., 20) and randomly select one to request tokens. This distributes load and prevents exceeding per-user limits.

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