Application Design Framework (ADF)

IAM Session Broker application

Use case

A multi-tenant SaaS offering composes multiple applications. Applications use a shared IAM Session Broker library to scope user access to their tenant’s boundary. SaaS provider wants to build a shared IAM Session Broker application instead to reduce operational overhead and improve security posture. The application should initially support the ABAC authorization strategy.

Business flow

• SaaS admin registers users for Yellow and Blue tenants
• Yellow user authenticates
• Yellow user downloads Yellow data

Features and stories

Feature: Temporary credentials for applications

• Job story: Allow applications to self-register and de-register
• Job story: Generate temporary credentials scoped to user tenant boundary

Requirements

Business

• Require the applications to use ABAC with ${aws:PrincipalTag/key} variable in policies for scoping access
• Require the applications to register and provide the following access metadata:
  • Access role name (e.g. DocumentsAPIDataAccess)
  • Session tag key (e.g. TenantID)
  • JWT claim name (e.g. custom:tenant_id)
  • JSON Web Key (JWK) Set URL (e.g. https://cognito-idp.<Region>.amazonaws.com/<userPoolId>/.well-known/jwks.json)
• Use the assumed-role session principal (service) role name for application name during registration
• Authorize the registration requests for assumed-role session principals in the same account
• Authorize the temporary security credentials requests for a registered application and a valid JWT
• Validate the JWT by public keys in the registered application JWK Set URL
• Return the scoped temporary security credentials by assuming the access role. Tag the session with the registered session tag key and JWT claim name value as the session tag key value.

Technical

• Organize the access metadata by application name
• Generate SDKs for multiple programming languages from service specification
• Collect audit logs for security and compliance
• Use AWS STS to request temporary security credentials
• Cache the returned temporary security credentials to reduce latency
• Throttle applications on tenant-level to protect against noisy-neighbor

Architecture

Technical flow

1. Yellow user authenticates using Identity Provider and gets a JWT
2. Yellow user accesses the Application with JWT to download Yellow data
3. Application calls IAM Session Broker to acquire Yellow-scoped temporary security credentials
4. IAM Session Broker verifies the JWT and returns Yellow-scoped temporary security credentials
5. Application returns Yellow data to the user

Application boundaries

Context

We need to define application boundaires based on the technical flow.

Decision

Create IAM Session Broker and Identity Provider applications. IAM Session Broker returns tenant-scoped temporary security credentials based on JWT claims for registered applications. Identity Provider is not described in this example for brevity.

Consequences

IAM Session Broker is on the critical path for upstream applications. Hence, it should maintain the agreed upon service level objectives (SLOs). Users drive the requests volume to IAM Session Broker, because the user-agent provides the JWT. Hence, IAM Session Broker performance characteristics should take interactive flows as the baseline.

IAM Session Broker components

Context

We need to define IAM Session Broker components based on the technical flow.

Decision

Create the following components:

API Gateway should authorize requests and throttle if needed to prevent the “noisy neighbor” problem. API Gateway should proxy all authorized and non-throttled requests to API. API should 1/ fetch access metadata from Access Database 2/ call Temporary Security Credentials Provider to assume the Service Role 3/ call Temporary Security Credentials Provider using the Service Role credentials to assume the access role 4/ return the scoped temporary security credentials.

API Gateway

Use Amazon API Gateway HTTP API with IAM authorization. Use Lambda proxy integration for API. Leverage usage plans to prevent the “noisy neighbor” problem. Use the Lambda authorizer as the API key source (example) and application name as the API key.

API

Use Lambda function for compute and Powertools for AWS Lambda (Python) for application. Use Lambda provisioned concurrency to reduce latency. Cache applications scoped temporary security credentials to further reduce latency.

Request	Description	Request body	Response
POST /applications	Register an application	{  “AccessRoleName”: “…”,  “SessionTagKey”: “…”,  “JWTClaimName”: “…”,  “JWKSetURL”: “…“ }
GET /credentials?jwt=X	Return scoped temporary security credentials		{  “AccessKeyId”:”…”,  “SecretAccessKey”:”…”,  “SessionToken”:”…“ }

Access Database

Use Amazon DynamoDB table. The table should store the registered access metadata.

Data model (designed using NoSQL WorkBench for DynamoDB):

Temporary Security Credentials Provider

Use AWS Session Token Service (AWS STS). Other options include AWS IAM Roles Anywhere and AWS IoT Core credential provider. Choose AWS STS because there is currently no requirement to support on-premises applications and/or certificate-based authentication use cases.

Service Role

Create IAMSessionBroker IAM role. Creating a dedicated Service Role enables flexibility for the IAM Session Broker architecture. Applications should trust the Service Role to assume their access role. The service role doesn’t have any permissions. Per requirements, applications and IAM Session Broker should be in the same account. The applications access role’s trust policy acts as an IAM resource-based policy. When a resource-based policy grants access to a principal in the same account, no additional identity-based policy is required (documentation).

Note: Applications access role trust policy uses the IAMSessionBroker role ID once saved. Deleting or altering the IAMSessionBroker role will require applications to update their access role’s trust policy to apply the new IAMSessionBroker role ID.

Consequences

To support cross-account scenarios, we would need to replace API Gateway HTTP API by API Gateway REST API, because HTTP API doesn’t support resource policies at the time of this writing.

API uses role chaining: 1/ assume Service Role 2/ assume application access role. Role chaining limits the role session to a maximum of one hour. In the worst case scenario, the API will need to call Temporary Security Credentials Provider (AWS STS) every hour for a specific application.

Service discovery

Context

We need to decide on a service discovery strategy to allow applications discover IAM Session Broker API endpoint without managing configuration files.

Decision

Use DNS for service discovery. Use the following naming convention for domain hierarchy:

<application>.<region>.<environment>.<product>.<top-level domain>

Example:

iam-session-broker.eu-west-1.gamma.saas-platform.example.com

Delegate the product sub-domain to a dedicated AWS account so that each product team can manage DNS zones for their applications. Using the above approach, applications can construct the IAM Session Broker API endpoint at deployment time.

Consequences

This approach supports cross-environment (account and Region) use cases by relying on naming convention.

Code

Toolchain

• Python: 3.9.11
• AWS CDK CLI version: 2.175.1
• AWS CDK library version: 2.175.1

Git repositories

• IAM Session Broker: iam-session-broker
• Identity Provider: identity-provider

Project structure

IAM Session Broker

The project structure aligns with the architectural diagram, so that programmers can quickly find the code for each component.

service/
  api/
    app/
      main.py  # Business logic application - Powertools for AWS Lambda (Python)
    compute.py
  access_database.py
  api_gateway.py
  service_role.py
  service_stack.py
contstants.py
main.py  # Resources configuration application - AWS CDK

Backlog

Appendix

API Gateway HTTP API with IAM authorizer Lambda proxy integration payload example

{
    "version": "2.0",
    "routeKey": "$default",
    "rawPath": "/applications",
    "rawQueryString": "",
    "headers": {
        "accept": "application/xml",
        "accept-encoding": "gzip, deflate",
        "authorization": "AWS4-HMAC-SHA256 Credential=ASIA3YC54HEJWX32ILMG/20230317/eu-west-1/execute-api/aws4_request, SignedHeaders=host;x-amz-date;x-amz-security-token, Signature=1b0063ba301f7668d5c7c982e505609db52ad83c3a879c311047acf6205cb760",
        "content-length": "0",
        "content-type": "application/json",
        "host": "d0cfuu2ujg.execute-api.eu-west-1.amazonaws.com",
        "user-agent": "python-requests/2.28.2",
        "x-amz-content-sha256": "e3b0c44298fc1c149afbf4c8996fb92427ae41e4649b934ca495991b7852b855",
        "x-amz-date": "20230317T170215Z",
        "x-amz-security-token": "<redacted>",
        "x-amzn-trace-id": "Root=1-64149d18-046d89152552d1da34770913",
        "x-forwarded-for": "85.250.125.159",
        "x-forwarded-port": "443",
        "x-forwarded-proto": "https"
    },
    "requestContext": {
        "accountId": "111111111111",
        "apiId": "d0cfuu2ujg",
        "authorizer": {
            "iam": {
                "accessKey": "ASIA3YC54HEJWX32ILMG",
                "accountId": "111111111111",
                "callerId": "AROA3YC54HEJ7ZID2KGLH:user@example.com",
                "cognitoIdentity": null,
                "principalOrgId": "aws:PrincipalOrgID",
                "userArn": "arn:aws:sts::111111111111:assumed-role/AWSReservedSSO_DeveloperAccess_073t3cf358b80610/user@example.com",
                "userId": "AROA3YC54HEJ7ZID2KGLH:user@example.com"
            }
        },
        "domainName": "d0cfuu2ujg.execute-api.eu-west-1.amazonaws.com",
        "domainPrefix": "d0cfuu2ujg",
        "http": {
            "method": "POST",
            "path": "/applications",
            "protocol": "HTTP/1.1",
            "sourceIp": "85.250.125.159",
            "userAgent": "python-requests/2.28.2"
        },
        "requestId": "B7170h_-DoEEPzA=",
        "routeKey": "$default",
        "stage": "$default",
        "time": "17/Mar/2023:17:02:16 +0000",
        "timeEpoch": 1679072536104
    },
    "isBase64Encoded": false
}

This site is open source. Improve this page.