@scloud/cdk-patterns/dist/Cognito.d.ts

Serverless CDK patterns for common infrastructure needs

import * as cognito from 'aws-cdk-lib/aws-cognito';
import { CfnUserPoolIdentityProvider, UserPool, UserPoolClient, UserPoolDomain, UserPoolIdentityProviderFacebook, UserPoolIdentityProviderGoogle } from 'aws-cdk-lib/aws-cognito';
import { IHostedZone } from 'aws-cdk-lib/aws-route53';
import { Construct } from 'constructs';
/**
 * Authentication setup with Cognito.
 *
 * This construct offers a couple convenience static methods for typical use cases:
 *  - Cognito.withSSO()
 *  - Cognito.withSocialLogins()
 *
 * To customise this construct, you'll need to call these methods in the following oprder:
 * - new Cognito()
 * - addGoogleIdp() (optional)
 * - addFacebookIdp() (optional)
 * - addSamlIdp() (optional, can be called more than once)
 * - createUserPoolClient()
 * - addCustomDomain() / addDomainPrefix()
 *
 * Once set up, you can call signInUrl() to get a URL for the hosted UI sign-in page.
 *
 * NB: IF you want to use a custom domain, there's an unexpected error where the CDK deployment
 * will fail unless there's an A record at the zone apex (at the time of writing) so you need to
 * add a record at the apex before you attempt to create a custom domain.
 *
 * @returns Information about the created UserPool
 */
export declare class Cognito extends Construct {
    id: string;
    userPool: UserPool;
    domain: UserPoolDomain | undefined;
    userPoolClient: UserPoolClient;
    googleIdp: cognito.UserPoolIdentityProviderGoogle | undefined;
    facebookIdp: cognito.UserPoolIdentityProviderFacebook | undefined;
    samlIdps: cognito.CfnUserPoolIdentityProvider[];
    /** Typically there's only one callback URL */
    callbackUrl: string;
    /** All callback URLs, including any alternative URL will be visible in this properly */
    callbackUrls: string[];
    /** Optional logout URL */
    logoutUrl: string | undefined;
    constructor(scope: Construct, id: string, props?: Partial<cognito.UserPoolProps>);
    addGoogleIdp(googleClientId: string, googleClientSecret: string): UserPoolIdentityProviderGoogle;
    addFacebookIdp(facebookAppId: string, facebookAppSecret: string): UserPoolIdentityProviderFacebook;
    /**
     * Add a SAML sso identity provider.
     *
     * You can call this method more than once to add multiple SAML providers.
     *
     * @param SamlProviderName Name in the Cognito hosted UI under "Sign in with your corporate ID"
     * @param FederationMetadataUrl SAML XML URL (e.g. Azure)
     * @param FederationMetadataXml SAML metadata XML (e.g. Google Workspace)
     */
    addSamlIdp(SamlProviderName: string, FederationMetadataUrl?: string, FederationMetadataXml?: string): CfnUserPoolIdentityProvider;
    /**
     * Create a Cognito User Pool Client.
     *
     * If you want to add identity providers such as Google, Facebook or saml sso you'll need to call addGoogleIdp(), addFacebookIdp() and/or addSamlIdp() first.
     *
     * @param enableEmail Whether to enable email as a sign-up/sign-in method.
     * @param callbackUrl Allowed callback URL on your app to receive an authentication code (?code=...)
     * @param alternativeCallbackUrls Zero or more additonal authorized callback URL, for example if you wneed to allow localhost in a development environment.
     * @returns cognito.UserPoolClient
     */
    createUserPoolClient(callbackUrl: string, enableEmail?: boolean, logoutUrl?: string, ...alternativeCallbackUrls: string[]): UserPoolClient;
    /**
     * Add a custom domain name to the Cognito User Pool.
     *
     * AWS recommends auth.<domain> for custom domains, which is the default if you don't pass a value for domainName.
     *
     * NB at the time of writing there's a hard limit of 4 custom Cognito domains per AWS account.
     *
     * You can either add a custom domain or a domain prefix, but not both.
     *
     * @param zone The HostedZone in which to create an alias record for the user pool.
     * @param domainName Leave this out to use the recommended `auth.<domain>`, or pass a fully qualified domain name.
     */
    addCustomDomain(zone: IHostedZone, domainName?: string): void;
    /**
     * Set a domain prefix for the URL of the Cognito User Pool.
     *
     * This will set the user pool URL to https://<domainPrefix>.auth.<region>.amazoncognito.com
     *
     * You don't have to set a custom domain prefix. If you don't, the prefix will be generated by AWS.
     *
     * If can set a custom domain prefix, or a custom domain, but not both.
     *
     * @param domainPrefix Leave this out to use the recommended `auth.<domain>`, or pass a fully qualified domain name.
     */
    addDomainPrefix(domainPrefix: string): void;
    /**
     * Constructs a URL for the hosted UI sign-in page.
     *
     * You'll need to call either addCustomDomain() or addDomainPrefix() first.
     *
     * @param callbackUrl Optional: defaults to the this.callbackUrl.
     */
    signInUrl(callbackUrl?: string): string;
    /**
     * @deprecated Use withSSOMetadataUrl() or withSSOMetadataXml() instead.
     *
     * Creates a Cognito instance configured for SAML sso (e.g. Azure or Google Workspace).
     *
     * You'll need to pass either a federationMetadataUrl or a federationMetadataXml.
     *
     * You'll want to pass either a domain prefix (creates https://<prefix>.auth.<region>.amazoncognito.com) or a
     * zone (and optionally domainName) if you don't pass a domainName the user pool url will be https://auth.<zoneName>
     *
     * NB at the time of writing AWS has a hard limit of 4 custom Cognito domains so if you're running multiple user pools
     * in a single AWS account you may need to use domain prefixes.
     */
    static withSSO(scope: Construct, id: string, callbackUrl: string, samlProviderName: string, federationMetadataUrl?: string | undefined, federationMetadataXml?: string | undefined, zone?: IHostedZone, domainName?: string, domainPrefix?: string, logoutUrl?: string, ...alternativeCallbackUrls: string[]): Cognito;
    /**
     * Creates a Cognito instance configured for email login.
     *
     * You'll want to pass either a domain prefix (creates https://<prefix>.auth.<region>.amazoncognito.com) or a
     * zone (and optionally domainName) if you don't pass a domainName the user pool url will be https://auth.<zoneName>
     *
     * NB at the time of writing AWS has a hard limit of 4 custom Cognito domains so if you're running multiple user pools
     * in a single AWS account you may need to use domain prefixes.
     */
    static withEmailLogin(scope: Construct, id: string, callbackUrl: string, zone?: IHostedZone, domainName?: string, domainPrefix?: string, logoutUrl?: string, ...alternativeCallbackUrls: string[]): Cognito;
    /**
     * Creates a Cognito instance configured for Social logins (Google and Facebook) and optionally email.
     *
     * You'll want to pass either a domain prefix (creates https://<prefix>.auth.<region>.amazoncognito.com) or a
     * zone (and optionally domainName) if you don't pass a domainName the user pool url will be https://auth.<zoneName>
     *
     * NB at the time of writing AWS has a hard limit of 4 custom Cognito domains so if you're running multiple user pools
     * in a single AWS account you may need to use domain prefixes.
     */
    static withSocialLogins(scope: Construct, id: string, callbackUrl: string, googleClientId?: string, googleClientSecret?: string, facebookAppId?: string, facebookAppSecret?: string, enableEmailLogin?: boolean, zone?: IHostedZone, domainName?: string, domainPrefix?: string, logoutUrl?: string, ...alternativeCallbackUrls: string[]): Cognito;
    /**
     * Creates a Cognito instance configured for SAML sso where you have a metadata URL (e.g. Azure).
     *
     * You'll need to pass a federationMetadataUrl (e.g. provided by Azure).
     *
     * If configuring an 'Enerprise Application' in Azure, the "Identifier (Entity ID)" will be:
     *
     *  urn:amazon:cognito:sp:<user pool id> (e.g. <region>_XyZaBcD1E)
     *
     * The "Reply URL (Assertion Consumer Service URL)" will be:
     *
     * https://<Your user pool domain>/saml2/idpresponse
     *
     * With an Amazon Cognito domain prefix:
     *  https://<yourDomainPrefix>.auth.<region>.amazoncognito.com/saml2/idpresponse
     * With a custom domain:
     *  https://<Your custom domain>/saml2/idpresponse
     *
     * see: https://docs.aws.amazon.com/cognito/latest/developerguide/cognito-user-pools-saml-idp.html
     *
     * You'll want to pass either a domain prefix (creates https://<prefix>.auth.<region>.amazoncognito.com) or a
     * zone (and optionally domainName) if you don't pass a domainName the user pool url will be https://auth.<zoneName>
     *
     * NB at the time of writing AWS has a hard limit of 4 custom Cognito domains so if you're running multiple user pools
     * in a single AWS account you may need to use domain prefixes.
     */
    static withSSOMetadataUrl(scope: Construct, id: string, callbackUrl: string, samlProviderName: string, federationMetadataUrl?: string | undefined, zone?: IHostedZone, domainName?: string, domainPrefix?: string, logoutUrl?: string, ...alternativeCallbackUrls: string[]): Cognito;
    /**
     * Creates a Cognito instance configured for SAML sso where you have a metadata XML file (e.g. Google Workspace).
     *
     * You'll need to pass federationMetadataXml data as a string (e.g. downloaded from your Google Workspace).
     *
     * If configuring an 'App' in Google Workspace (under "Apps/Web and mobile apps" in the admin console) the "ACS URL" will be:
     *
     * https://<Your user pool domain>/saml2/idpresponse
     *
     * With an Amazon Cognito domain prefix:
     *  https://<yourDomainPrefix>.auth.<region>.amazoncognito.com/saml2/idpresponse
     * With a custom domain:
     *  https://<Your custom domain>/saml2/idpresponse
     *
     * The "Enitiy ID" will be:
     *
     *  urn:amazon:cognito:sp:<user pool id> (e.g. <region>_XyZaBcD1E)
     *
     * see: https://docs.aws.amazon.com/cognito/latest/developerguide/cognito-user-pools-saml-idp.html
     *
     * In Google Workspace you'll need to set "Use access" to e.g. "ON for everyone" (oe select an organisational unit).
     * NB it's usually best to test Google Worspace sso in incognito mode as if you're already signed in you may get a 403 error.
     * This is possibly because your local cached credentials haven't yet updated with access to the App.
     *
     * You'll want to pass either a domain prefix (creates https://<prefix>.auth.<region>.amazoncognito.com) or a
     * zone (and optionally domainName) if you don't pass a domainName the user pool url will be https://auth.<zoneName>
     *
     * NB at the time of writing AWS has a hard limit of 4 custom Cognito domains so if you're running multiple user pools
     * in a single AWS account you may need to use domain prefixes.
     */
    static withSSOMetadataXml(scope: Construct, id: string, callbackUrl: string, samlProviderName: string, federationMetadataXml?: string | undefined, zone?: IHostedZone, domainName?: string, domainPrefix?: string, logoutUrl?: string, ...alternativeCallbackUrls: string[]): Cognito;
}