Cognito Service

AWS Cognito provides the authentication and authorization infrastructure for the Arda Platform. One Cognito instance is deployed per Partition (Environment).

Service Components

Component	Description
User Pool	User directory with custom attributes (`tenant`, `role`)
Resource Server	Declares custom OAuth2 scopes
M2M Client Application	Machine-to-machine authentication using `client_credentials` flow
Web Client Application	User-facing authentication using `authorization_code` (OIDC) flow
Post-Signup Lambda Trigger	Auto-confirms new users
Password Reset Lambda Trigger	Sends password recovery emails
User Pool Domain	Hosts the Cognito-managed UI and OAuth2 endpoints

Custom Scopes

Scopes are declared on the Resource Server and are hierarchically inclusive (each scope implicitly includes access to all less-privileged scopes):

Scope	Access Level
`public`	Publicly accessible resources; no authentication required
`lite`	Freemium or limited subscription resources
`subscription`	Full commercial subscription resources
`arda`	Arda-internal resources only
`system`	Internal system processes only

Custom User Attributes

Attribute	Description
`custom:tenant`	Tenant ID associated with the user: `<tenant-name>::<tenant-uuid>`
`custom:role`	User’s role: one of `public`, `lite`, `subscriber`, `admin`, `system`

Custom attributes are strings only (max 2048 chars). JSON objects, arrays, and nested structures are not supported.

OAuth2 Flows

Client	Flow	Use Case
M2M Client	`client_credentials`	Backend-to-backend API authentication
Web Client	`authorization_code` (OIDC)	User-facing web application login

CloudFormation Exports

All exports use the prefix <infrastructure>-<partition> (e.g., alpha002-dev):

Export Name Suffix	Description	Example
`-API-UserPoolId`	Cognito User Pool ID	`alpha002-dev-API-UserPoolId`
`-API-UserPoolDomain`	Cognito-hosted UI domain	`alpha002-dev-API-UserPoolDomain`
`-API-WebClientId`	Web Client App Client ID	`alpha002-dev-API-WebClientId`
`-API-WebSecretName`	Secrets Manager name for Web Client secret	`alpha002-dev-API-WebSecretName`
`-API-M2MClientId`	M2M Client App Client ID	`alpha002-dev-API-M2MClientId`
`-API-M2MSecretName`	Secrets Manager name for M2M Client secret	`alpha002-dev-API-M2MSecretName`
`-ResourceServerId`	Resource Server ID	`alpha002-dev-ResourceServerId`

Published Secrets

Secret Name	Description
`<infrastructure>-<partition>-API-WebSecretName`	Web Client secret
`<infrastructure>-<partition>-API-M2MSecretName`	M2M Client secret

CDK Integration

To import Cognito outputs in another CDK stack:

// Via CDK
const userPoolId = cdk.Fn.importValue('alpha002-dev-API-UserPoolId');

// Via PartitionAuthn static method
const exports = PartitionAuthn.importValues(partitionLocator);

Future Extensions

Integration with external OIDC providers (Google, LinkedIn)
Per-tenant role definitions for finer-grained RBAC
Multi-tenant user associations (one user, multiple tenants)
Facility-level scoping within tenants