UNPKG

@fntio/infra-client

Version:

Self-hosted AWS access portal: credential vending, target-account trust, and grant-driven private networking as CDK stacks and constructs.

114 lines (113 loc) • 6.71 kB
import * as cognito from "aws-cdk-lib/aws-cognito"; /** `loginMethods.federation` — sign in with an external OIDC provider (Entra, Okta, Ping, * Keycloak, Google Workspace…), validated at synth (resolveFederation). Runbook: wiki * Runbooks-Users, "Federated sign-in (SSO)". */ /** One custom claim copied from the provider's token onto the user (a `custom:<key>` pool * attribute) and into the portal's own ID token. */ export interface FederatedClaim { /** The provider's claim name the value comes from (Entra's `oid`, Okta's `employeeNumber`…). */ readonly from: string; /** Cap on the stored value, 1–2048 (Cognito's ceiling). Default 256. */ readonly maxLen?: number; /** Shown next to the value in the admin directory and activity. Default: the key. */ readonly label?: string; } export interface FederatedProvider { /** Cognito provider name — the `identity_provider` the login page asks for and the prefix of * auto-created usernames. Letters, digits, `-`; ≤32 chars; unique. Treat as permanent: renaming * orphans every linked identity. */ readonly name: string; /** Sign-in button text. Default: `name`. */ readonly label?: string; /** Only `"oidc"` today; `"saml"` fails at synth until it is built. */ readonly type: "oidc"; /** The provider's issuer, exactly as its discovery document states it (Cognito fetches * `<issuerUrl>/.well-known/openid-configuration` at deploy). */ readonly issuerUrl: string; readonly clientId: string; /** Secrets Manager ARN holding the client secret as a PLAIN string (not JSON), in the * deployment's region. The value never enters the repo or the template. */ readonly clientSecretArn: string; /** Pin a secret version after rotating it — CloudFormation only re-reads the secret when * the provider resource changes. Omit to read the current version on the next deploy. */ readonly clientSecretVersionId?: string; /** OAuth scopes requested from the provider. Default `openid profile email`; `openid` is required. */ readonly scopes?: readonly string[]; /** Standard Cognito attributes (camelCase, e.g. `givenName`) → provider claim. `email` defaults * to `"email"` and cannot be dropped: it is the invite-linking key and the user's name. */ readonly attributeMapping?: Readonly<Record<string, string>>; /** Custom claims to carry, keyed by the attribute name. PERMANENT for the pool's life: Cognito * can neither rename nor remove custom attributes (50 max). */ readonly claims?: Readonly<Record<string, FederatedClaim>>; /** Extra hosts the provider's sign-in may redirect through (a tenant's own ADFS, `login.live.com`). * Allowlist semantics: wiki Configuration-Reference, `allowedHosts`. */ readonly allowedHosts?: readonly string[]; } export interface ResolvedFederatedClaim { readonly key: string; readonly from: string; readonly maxLen: number; readonly label: string; } export interface ResolvedFederatedProvider { readonly name: string; readonly label: string; readonly issuerUrl: string; readonly clientId: string; readonly clientSecretArn: string; readonly clientSecretVersionId?: string; readonly scopes: readonly string[]; /** CDK attribute-mapping keys → provider claim; `email` always present. */ readonly attributeMapping: Readonly<Partial<Record<StandardAttributeKey, string>>> & { readonly email: string; }; readonly claims: readonly ResolvedFederatedClaim[]; /** Hosts the desktop shell allows in-view for this provider (issuer host first). */ readonly hosts: readonly string[]; } export interface ResolvedFederation { readonly providers: readonly ResolvedFederatedProvider[]; /** Union of every provider's claim keys — one `custom:<key>` pool attribute each, capped at * the widest `maxLen` any provider asks for; the label is the first provider's. */ readonly claimKeys: readonly ResolvedFederatedClaim[]; } /** The keys CDK's AttributeMapping accepts (minus `custom`, which `claims` drives). Typed against * CDK so a typo fails tsc, not a deploy. */ declare const STANDARD_ATTRIBUTE_KEYS: readonly ["address", "birthdate", "email", "familyName", "gender", "givenName", "locale", "middleName", "fullname", "nickname", "phoneNumber", "profilePicture", "preferredUsername", "profilePage", "timezone", "lastUpdateTime", "website"]; export type StandardAttributeKey = (typeof STANDARD_ATTRIBUTE_KEYS)[number]; export declare const MAX_CUSTOM_ATTRIBUTES = 50; /** Cognito links at most 5 identities to a user; each provider may cost two (the invite-time * email link plus the trigger's subject link on a mismatch), so two providers is the safe ceiling. */ export declare const MAX_PROVIDERS = 2; export declare const MAX_CLAIM_LEN = 2048; /** Validate + default `loginMethods.federation`; `undefined` when absent or empty. Every * rule here fails a deploy or a sign-in later, silently. */ export declare function resolveFederation(federation: readonly FederatedProvider[] | undefined, region: string): ResolvedFederation | undefined; /** `{{resolve:secretsmanager:…}}` for the provider's client secret — resolved by CloudFormation * at deploy, so the plaintext is in neither the synthesized template nor the repo. */ export declare function clientSecretReference(p: ResolvedFederatedProvider): string; /** Every standard attribute plus the mapped claims — what a client may read into ID tokens. */ export declare function readAttributes(claimKeys: readonly ResolvedFederatedClaim[]): cognito.ClientAttributes; /** Every standard attribute, plus the mapped claims ONLY for the federation client: Cognito * writes a mapped attribute through the signing-in client, and that same permission lets a * user's self-service call set it — so no client a local session can hold gets it. */ export declare function writeAttributes(claimKeys: readonly ResolvedFederatedClaim[], opts: { claims: boolean; }): cognito.ClientAttributes; /** CDK AttributeMapping for one provider: the standard keys plus `custom:<key>` for each claim. */ export declare function providerAttributeMapping(p: ResolvedFederatedProvider): cognito.AttributeMapping; /** What config.json carries — public ids only (the frontend's login buttons + labels, the * desktop shell's navigation allowlist). */ export declare function federationAppConfig(f: ResolvedFederation, clientId: string): { clientId: string; providers: { name: string; label: string; hosts: string[]; }[]; claims: { key: string; label: string; }[]; }; export {};