API Gateway Authorizers

Overview

Each request from an external service to backend services passes through the **API Gateway**, which applies an optional authorizer for access control. Authorizers are configured within the User Account Service.

Service Resource Action Structure

The service_resource_action string defines specific permissions and is used by the Authorizer to match the requested action. The structure is uniform across both AppLevel and UserLevel.

1. ObjectType belongTo

Used to define access rights for a specific object type endpoint.

{
  service_resource_action:"{serviceTag}_{objectType}_{apiMethods}",
}

• **`{serviceTag}`:** Specifies the target **Service** name.
• **`{objectType}`:** Specifies the target **Resource** or Object (e.g., Config, Product).
• **`{apiMethods}`:** Specifies the permitted **Action** (e.g., Create, Get, Update).

2. Flow Schema Format

Used to define permissions for the flowSchema, which allows who can access it.

{
  service_resource_action:"{serviceTag}_{flowTag}_{flowTag}",
}

• **`{serviceTag}`:** Specifies the target **Service**.
• **`{flowTag}`:** A variable representing the specific **Resource** or **Action** (Flow).

Authorizer Levels

AppLevel

This level enforces application-wide permissions and has **no single owner**. Users granted application-level administrative rights can manage roles and settings across the entire service.

• Can change other user roles.
• Can create new roles.
• Change site-wide settings.
• Grants **SuperUser** permissions for lower-level RBAC (e.g., User level or Category level RBAC permissions).

Context: Permissions focus on **application-wide/system-level** rights.

allow the role permission to user appLevel

• SuperUser

can do all actions:

CREATE | UPDATE | DELETE | GET | LIST

• VerifiedUser

can do some actions:

CREATE | GET | LIST

• BasicUser

can do few actions:

GET

example rolePermission

• AppLevel:superUser (ObjectType belongTo)

{
  roleIdKey:"AppLevel_this-is-uuid-for-role-superUserA",
  service_resource_action:"ServiceTemplate_Config_Create",
  permission: "accept"
}

• AppLevel:verifiedUser (ObjectType belongTo)

{
   roleIdKey: "AppLevel_this-is-uuid-for-role-verifiedUserA",
   service_resource_action: "ServiceTemplate_Config_Create",
   permission: "accept"
}

• AppLevel:basicUser (ObjectType belongTo)

{
  userId: "this-is-uuid-for-user-basicUserA",
  roleIdKey: "AppLevel_this-is-uuid-for-role-basicUserA"
}

• AppLevel:basicUser (FlowSchema)

{
   roleIdKey: "AppLevel_this-is-uuid-for-role-basicUserA",
   service_resource_action: "ServiceTemplate_createSomething_createSomething",
   permission: "accept"
}

example UserRoles

• AppLevel:superUser

{
 userId: "this-is-uuid-for-user-superUserA",
 roleIdKey: "AppLevel_this-is-uuid-for-role-superUserA"
}

• AppLevel:verifiedUser

{
  userId: "this-is-uuid-for-user-verifiedUserA",
  roleIdKey: "AppLevel_this-is-uuid-for-role-verifiedUserA"
}

setting for authorizer appLevel

• APIv1 (REST API)

Uses the `arn` of the authorizer and `request` type in `function.yml`.

• • function.yml

LambdaFunctionHdrApi:
  events:
    - http:
        path: Lambda/LambdaAction
        method: post
        cors: true
        authorizer:
          arn: ${self:custom.iz_authorizerAppLevel}
          type: request
          resultTtlInSeconds: 0

• APIv2 (HTTP API)

Uses a centralized `authorizers` definition in `serverless.yml` and references the authorizer name in `function.yml`.

• • serverless.yml

provider:
  httpApi:
    cors: true
    payload: "2.0"
    authorizers: ${file(sls_yaml/generatedCode/source/Authorizer.yml)}

• • function.yml (Examples)

# ObjectType belongTo Matching ({serviceTag}/{objectType}/{action})
LambdaFunctionHdrApi:
  events:
    - httpApi:
        path: /{serviceTag}/{objectType}/{action}
        method: put
        authorizer: authorizerServiceSchema

# Flow Schema Matching ({serviceTag}/{flowTag}/{flowTag})
LambdaFunctionHdrApi:
  events:
    - httpApi:
        path: /{serviceTag}/{flowTag}/{flowTag}
        method: put
        authorizer: authorizerServiceSchema

UserLevel

Permissions at this level are **linked to a specific user ID**. The user corresponding to that ID is considered the **owner** and always retains full permissions for their own resources.

• All permissions are linked to one user id.
• The current user is the owner and always has full permissions for their user id.
• Available roles are shared by all users.
• Only the creator of a role can make subsequent changes (initial state).

Context: Permissions focus on **accessing resources tied to a specific User ID**; requires Target ID scoping in the API path.

example permissions:

• Can administer user roles/permissions linked to this user ID.
• Can administer sell offers for this user.

allow the role permission to user

• SuperUser

can do all actions:

CREATE | UPDATE | DELETE | GET | LIST

• VerifiedUser

can do some actions:

CREATE | GET | LIST

• BasicUser

can do few actions:

GET

example rolePermission

• Role permissions are created either via seed data or the API endpoint: RolePermissionCreateHdrApi (https://us-east-2.console.aws.amazon.com/apigateway/home?region=us-east-2#/apis/rwnhg855jd/resources/y8erkk)

• UserLevel:verifiedUser (ObjectType belongTo)

{
  roleIdKey:"UserLevel_this-is-uuid-for-role-verifiedUserA_this-is-uuid-for-user-verifiedUserB",
  service_resource_action:"VariantStandard_Product_AddProduct",
  permission: "accept"
}

• roleIdKey Structure: The key consists of 3 parts separated by underscores (`_`). The final part (e.g., `this-is-uuid-for-user-verifiedUserB`) represents the **targetId** or the UUID of the user to whom the permission is specifically tied.

• UserLevel:flowSchema (Flexible)

{
  roleIdKey:"UserLevel_this-is-uuid-for-role-basicUserA_this-is-uuid-for-user-basicUserB",
  service_resource_action:"VariantStandard_CreateSomething_CreateSomething",
  permission: "accept"
}

example userRoles

• User roles are created via the API endpoint: UserRolesCreateHdrApi (https://us-east-2.console.aws.com/apigateway/home?region=us-east-2#/apis/rwnhg855jd/resources/y8erkk)

• UserLevel:verifiedUser

{
  userId: "this-is-uuid-for-user-verifiedUserB",
  roleIdKey: "UserLevel_this-is-uuid-for-user-verifiedUserA_this-is-uuid-for-user-verifiedUserB"
}

setting for authorizer userLevel

• APIv1 (REST API)

For LambdaFunctionHdrApi userlevel, the API path must include a **target ID suffix** to specify the resource owner.

• • function.yml

LambdaFunctionHdrApi:
  events:
    - http:
        path: Lambda/LambdaAction${self:custom.api_path_targetid_suffix}
        method: post
        cors: true
        authorizer:
          arn: ${self:custom.iz_authorizerUserLevel}
          type: request
          resultTtlInSeconds: 0

• APIv2 (HTTP API)

Utilizes the centralized authorizer definition and path placeholders to scope access to the target user ID.

• • serverless.yml

provider:
  httpApi:
    cors: true
    payload: "2.0"
    authorizers: ${file(sls_yaml/generatedCode/source/Authorizer.yml)}

• • function.yml (Examples)

# ObjectType belongTo Matching (e.g., UnitType/unitType/create/{targetUserId})
LambdaFunctionHdrApi:
  events:
    - httpApi:
        path: /UnitType/unitType/create/{targetUserId}
        method: put
        authorizer: authorizerIdentifiers

# Flow Schema Matching
LambdaFunctionHdrApi:
  events:
    - httpApi:
        path: /{serviceTag}/{flowTag}/{flowTag}/{targetId}
        method: put
        authorizer: authorizerIdentifiers