Skip to content

Demo202509 Specific Designs

Arda’s Platform will use OAuth2 as the primary authentication and mechanism for user identification. For Demo202509,
Authentication will rely on a hybrid approach of Oauth2 based on AWS Cognito for the Front End and BFF, and a Bearer
Token mechanism for the Backend API endpoints.

User Authentication Information

The Backend API endpoints require this information available at the time of the request:

  1. User ID: A unique identifier for the user. This must be a Human readable identifier.
  2. Tenant ID: The identifier for the subscriber organization to the Arda Platform on behalf of which the request is made.
  3. An additional Role may be introduced as an improvement on the Demo202509 release. This is a String from a set of Enumerated values.

Storage of Authentication Information

The three fields will be stored in the Cognito User Pool.

User ID

Stored as the cognito username.

Tenant ID

Role

  • Demo202509: Stored as a String in a custom attribute that is configured at User Sign Up time, the possible values are:
    • PUBLIC
    • USER
    • ADMIN
    • ARDA
  • Long Term: The Role will be replaced by either a more complex structure to reflect the user’s permissions for different Tenants or a reference to a user profile to use in the Access Decision Service.

Transmission of Authentication Information between FrontEnd and Backend

Long Term Direction

Front-End Application (running on the browser or mobile devices), BFF, and Backend will use a single JSON Web Token (JWT) issued by the OAuth2 server. The JWT will transmit the User ID, Tenant ID, and Role information. No other headers or mechanisms will be used.

The three data elements will be included in the JWT token issued by the OAuth2 server.

  • User ID will be the sub claim in the JWT token. The other two elements will be included as custom claims.
  • Tenant ID As a custom claim tenant in the JWT token encoded as JSON array of UUIDs.
  • Role may evolve into a more complex structure in the future, or it may be replaced by a reference to a set of permissions to be interpreted by an Access Decision Service.

Demo202509

Front-End application and BFF will use the JWT issued by the OAuth2 server to authenticate between them.

BFF will authenticate to the Backend API endpoints using a Bearer Token, with a custom API Key. BFF and Backend API endpoints will communicate over HTTPS to protect the API Key and the rest of the header information.

The three data elements will be included in the JWT token issued by the OAuth2 server.

  • User ID will be included in a custom header field: X-Author
  • Tenant ID will be included in a custom header field: X-Tenant-ID
  • Role: is TBD at this point (Aug 15 2025), the current design is to include it in a header named X-Role-ID

Important

It is the responsibility of the BFF to ensure that the User ID, Tenant ID, and Role are included in the request to the Backend API endpoints and that they correspond with the values in the JWT Token received from the Application.

The BFF at this point is the only component that will be able to access the API Backend and is considered “Trusted” by the Backend API endpoints if the Bearer Token matches the one configured in the Backend Services.

Values for “SYSTEM” Access.

The BFF, as a trusted component may need to access system services in the backend without a specific user logged in, in particular for the Sign-up and sign-in processes. For these cases, the values for the Authentication Values need to be:

  1. Bearer Token: The value configured for the BFF.
  2. User ID: SYSTEM
  3. Tenant ID: SYSTEM
  4. Role: ARDA

If time allows, the System User will also be configured in the Cognito User Pool and the BFF may need to authenticate to it to obtain these values but this is not a priority for the Demo202509 release.

Scenarios

Sign Up

See the Sign Up Use Case for the overall flow of
the Sign-Up process.

Sign In and Access to Protected Resources

See the Sign In Use Case for the overall flow of the Sign-In process with JWT authentication. (Long Term Direction). The Hybrid flow follows the same scenario except for the section Successful Access to Protected Resource which is:

uml diagram

Details on URL Redirects

Cognito requires any redirect URLs to be registered in order to be allowed. This registration is static and is done at the time the Cognito User Pool and Application Client are created.

To overcome this limitation, the BFF will use the following convention to redirect users to the correct URL.

  1. The Cognito Pool and Application Client will register a general single URL for redirects, by default, this will be https://<app-host>/redirect. See the Naming of Hosts and Routes for the value of <app-host>.
  2. The BFF, when requesting authentication from the Cognito User Pool as part of trying to access a protected resource will send an additional query parameter in the URL and set the redirect value for Cognito to the URL above.

The URL for Cognito will look like:

https://<cognito-authentication-request>?target=<URL-encoded-target-URL>

Cognito will then call the BFF with the query parameter target and the BFF can verify and proceed with the redirect to the Browser.

Note that the encoding of target depends only on the BFF, so it can be made as sophisticated as needed for security, with the only requirement that the BFF can decode it. It is possible to even encode it with an encryption key that is secured in the BFF.

© 2025 Arda Systems, All rights reserved

Comments