@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
TypeScript
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 {};