Skip to main content

Auth Architecture

Last Updated: 2026-03-06 Sources: innovation-sandbox-on-aws (auth-api.ts, rest-api-all.ts, authorizer-handler.ts, authorization.ts, authorization-map.ts, sso-handler, jwt.ts), .state/scps/*.json

Executive Summary​

The NDX:Try AWS platform implements a layered authentication and authorization model combining SAML 2.0 via AWS IAM Identity Center for user identity, JWT bearer tokens for stateless API authentication, role-based access control (RBAC) with three ISB roles (Admin, Manager, User), and GitHub OIDC for credential-less CI/CD deployments. All authentication flows converge in the Hub account (568672915267), where a Lambda authorizer validates JWT tokens against secrets stored in AWS Secrets Manager, with WAF-enforced IP allow-listing and rate limiting providing defence in depth at the API Gateway layer.

Authentication Architecture Overview​

1. IAM Identity Center (SAML 2.0) Configuration​

Identity Source​

PropertyValue
Identity SourceIdentity Center Directory (AWS Managed)
Regionus-west-2
SAML ApplicationInnovation Sandbox on AWS
Application Start URLhttps://isb.try.ndx.digital.cabinet-office.gov.uk
NameID Formaturn:oasis:names:tc:SAML:2.0:nameid-format:persistent

SAML Attribute Mappings​

AttributeSourcePurpose
Subject${user:subject}Unique user identifier (nameID)
email${user:email}User email address
name${user:name}Display name
department${user:department}Organization/Department

IdP Certificate Storage​

The IdP X.509 certificate used to validate SAML assertions is stored in AWS Secrets Manager:

  • Secret Name: /isb/<namespace>/Auth/IdpCert
  • Encryption: Customer-managed KMS key
  • Rotation: Manual (when the IdP certificate rotates, typically annually)

Source: auth-api.ts lines 91-101

User Groups​

GroupPurpose
ISB-AdminsPlatform administrators with full control
ISB-UsersStandard sandbox requesters
ISB-ManagersLease approval and operational management

2. SAML Authentication Flow​

SSO Handler Implementation​

The SSO handler is an Express.js application running inside a Lambda function, using @node-saml/passport-saml for SAML processing. It exposes the following routes via /api/auth/{action+}:

RouteMethodAuth RequiredPurpose
/auth/loginGETNoInitiate SAML authentication
/auth/login/callbackPOSTNoProcess SAML assertion
/auth/login/statusGETJWTCheck authentication status
/auth/logoutGETNoRedirect to IdP sign-out

Configuration: Loaded from AppConfig (global configuration) and Secrets Manager, including session duration, IdP URLs, and IdP audience.

Source: sso-handler/src/server.ts, sso-handler/src/config.ts

SAML Validation​

The passport-saml strategy validates:

  1. XML signature using the stored IdP X.509 certificate
  2. Audience restriction against the configured idpAudience
  3. Timestamp validity (NotBefore/NotOnOrAfter)

After validation, the handler resolves the user's ISB identity by calling User.getIsbUser(nameID), which assumes a cross-account role into the Identity Center account via IntermediateRole to query the Identity Center directory.

Source: sso-handler/src/user.ts

3. JWT Token Management​

JWT Structure​

The JWT tokens are signed using the jsonwebtoken library with HMAC-SHA256:

Payload:

{
  "user": {
    "displayName": "User Name",
    "userName": "user@example.gov.uk",
    "email": "user@example.gov.uk",
    "roles": ["User"]
  },
  "iat": 1709337600,
  "exp": 1709351400
}

Signing: jwt.sign({user: isbUser}, jwtSecret, {expiresIn: sessionDuration})

Session Duration: Configurable via AppConfig (auth.sessionDurationInMinutes)

Source: sso-handler/src/server.ts line 212, common/utils/jwt.ts

JWT Secret​

PropertyValue
StorageAWS Secrets Manager
Secret Name/isb/<namespace>/Auth/JwtSecret
EncryptionCustomer-managed KMS key
Length32 characters (alphanumeric + symbols)
RotationAutomatic every 30 days
Rotation LambdaJwtSecretRotator (reserved concurrency: 1)

Source: auth-api.ts lines 47-89

JWT Secret Rotation​

The rotation Lambda (secret-rotator-handler.ts) follows the four-step Secrets Manager rotation protocol:

  1. createSecret: Generates a new 32-character random password via GetRandomPasswordCommand and stores it as AWSPENDING
  2. setSecret: No-op (no external system to update)
  3. testSecret: No-op (JWT validation is inherently tested on next use)
  4. finishSecret: Promotes AWSPENDING to AWSCURRENT and demotes old version

Source: secret-rotator/src/secret-rotator-handler.ts

4. API Gateway Authorization​

Request Authorizer​

The API Gateway uses a Request-based Lambda authorizer (not Token-based), with identity sources drawn from the Authorization header, request path, and HTTP method:

const authorizer = new RequestAuthorizer(scope, "Authorizer", {
  handler: authorizerLambdaFunction.lambdaFunction,
  identitySources: [
    IdentitySource.header("Authorization"),
    IdentitySource.context("path"),
    IdentitySource.context("httpMethod"),
  ],
  resultsCacheTtl: Duration.minutes(5),
});

Cache TTL: 5 minutes (reduces Secrets Manager API calls)

Source: rest-api-all.ts lines 101-109

Authorization Flow​

Role-Based Access Control (RBAC)​

ISB defines three roles as a Zod enum: Admin, Manager, User.

Source: common/types/isb-types.ts line 5

The authorization map defines which roles can access which endpoints:

EndpointGETPOSTPATCHPUTDELETE
/leasesManager, Admin, UserUser, Manager, Admin---
/leases/{param}User, Manager, Admin-Manager, Admin--
/leases/{param}/review-Manager, Admin---
/leases/{param}/terminate-Manager, Admin---
/leases/{param}/freeze-Manager, Admin---
/leases/{param}/unfreeze-Manager, Admin---
/leaseTemplatesUser, Manager, AdminAdmin, Manager---
/leaseTemplates/{param}User, Manager, Admin--Admin, ManagerAdmin, Manager
/configurationsManager, Admin, User----
/accountsAdminAdmin---
/accounts/{param}Admin----
/accounts/{param}/retryCleanup-Admin---
/accounts/{param}/eject-Admin---
/accounts/unregisteredAdmin----

Source: authorizer/src/authorization-map.ts

Maintenance Mode​

When globalConfig.maintenanceMode is enabled, only Admin users and GET /configurations requests are allowed. All other requests receive a Deny policy.

Source: authorizer-handler.ts lines 63-70

5. WAF Protection​

The API Gateway has a regional WAF WebACL attached with five rules, evaluated in priority order:

PriorityRuleActionDescription
0IsbAllowListRuleBlock (non-matching)IP allow-list using X-Forwarded-For header; blocks requests not from allowed CIDRs
1IsbRateLimitRuleBlock (429)Rate-based rule: 200 requests per 60-second window per forwarded IP
2AWSManagedRulesCommonRuleSetOverride:noneAWS managed rules (excludes SizeRestrictions_BODY, SizeRestrictions_QUERYSTRING, CrossSiteScripting_BODY)
3AWSManagedRulesAmazonIpReputationListOverride:noneBlocks known malicious IPs
4AWSManagedRulesAnonymousIpListOverride:noneBlocks VPN/proxy/Tor exit nodes

Source: rest-api-all.ts lines 135-272

6. Cross-Account IAM Role Chains​

Hub to Pool Account​

The SSO handler and other Lambda functions use a two-hop role chain:

  1. Lambda execution role assumes IntermediateRole in the Hub account
  2. IntermediateRole assumes OrganizationAccountAccessRole in the target pool account

Hub to Identity Center Account​

For user lookups during SAML callback:

  1. SSO Handler Lambda assumes IntermediateRole
  2. IntermediateRole assumes the IDC role in the Identity Center account (specified by IDC_ROLE_ARN)

Source: sso-handler/src/user.ts lines 13-23

7. GitHub Actions OIDC Authentication​

GitHub Actions workflows authenticate to AWS using OIDC without long-lived credentials:

  1. Workflow requests a JWT from GitHub's OIDC provider
  2. AWS STS validates the JWT against token.actions.githubusercontent.com
  3. Trust policy conditions verify repository ownership (co-cddo/*) and audience (sts.amazonaws.com)
  4. STS returns temporary credentials (1-hour session)

See 51-oidc-configuration.md for the full OIDC provider and role inventory.

8. Security Controls Summary​

ControlImplementation
SAML Assertion ValidationX.509 signature, timestamp, audience restriction via passport-saml
JWT SigningHMAC-SHA256 with 32-character secret
JWT Secret RotationAutomatic 30-day rotation via Secrets Manager
Authorizer Caching5-minute cache TTL on API Gateway
RBAC EnforcementPath+method authorization map with three ISB roles
Maintenance ModeAppConfig-driven, restricts to Admin only
IP Allow-ListingWAF IP set on X-Forwarded-For header
Rate Limiting200 requests/minute per IP via WAF
Managed WAF RulesCommon Rule Set, IP Reputation, Anonymous IP List
HTTPS EnforcementCloudFront REDIRECT_TO_HTTPS, TLS 1.2+ minimum
Security HeadersHSTS, X-Frame-Options DENY, CSP, X-Content-Type-Options, Referrer-Policy
No Auth on SSO Endpoints/auth/{action+} explicitly uses AuthorizationType.NONE
Cross-Account RolesIntermediateRole with explicit trust, short-lived STS credentials
OIDC for CI/CDNo long-lived access keys; repository-scoped trust

Generated from source analysis. See 00-repo-inventory.md for full inventory.