Identity Providers & Federation

/**
 * Create an identity provider
 * Configures external IdP integration for user pool federation
 */
class CreateIdentityProviderCommand {
  constructor(input: CreateIdentityProviderCommandInput);
}

interface CreateIdentityProviderCommandInput {
  /** The user pool ID */
  UserPoolId: string;
  
  /** Name for the identity provider */
  ProviderName: string;
  
  /** Type of identity provider */
  ProviderType: IdentityProviderTypeType;
  
  /** Provider-specific configuration details */
  ProviderDetails: Record<string, string>;
  
  /** Mapping between IdP attributes and user pool attributes */
  AttributeMapping?: Record<string, string>;
  
  /** List of IdP identifiers */
  IdpIdentifiers?: string[];
}

interface CreateIdentityProviderCommandOutput {
  /** The created identity provider */
  IdentityProvider: IdentityProviderType;
}

type IdentityProviderTypeType = 
  | "SAML"           // SAML 2.0 identity provider
  | "Facebook"       // Facebook Login
  | "Google"         // Google Sign-In
  | "LoginWithAmazon" // Login with Amazon
  | "SignInWithApple" // Sign in with Apple
  | "OIDC";          // OpenID Connect provider

/**
 * Update identity provider configuration
 * Modify settings for an existing identity provider
 */
class UpdateIdentityProviderCommand {
  constructor(input: UpdateIdentityProviderCommandInput);
}

interface UpdateIdentityProviderCommandInput {
  /** The user pool ID */
  UserPoolId: string;
  
  /** The identity provider name */
  ProviderName: string;
  
  /** Updated provider details */
  ProviderDetails?: Record<string, string>;
  
  /** Updated attribute mapping */
  AttributeMapping?: Record<string, string>;
  
  /** Updated IdP identifiers */
  IdpIdentifiers?: string[];
}

/**
 * Get identity provider details
 * Retrieve configuration for a specific identity provider
 */
class DescribeIdentityProviderCommand {
  constructor(input: DescribeIdentityProviderCommandInput);
}

interface DescribeIdentityProviderCommandInput {
  /** The user pool ID */
  UserPoolId: string;
  
  /** The identity provider name */
  ProviderName: string;
}

interface DescribeIdentityProviderCommandOutput {
  /** Identity provider configuration */
  IdentityProvider: IdentityProviderType;
}

/**
 * Delete an identity provider
 * Removes IdP integration from user pool
 */
class DeleteIdentityProviderCommand {
  constructor(input: DeleteIdentityProviderCommandInput);
}

interface DeleteIdentityProviderCommandInput {
  /** The user pool ID */
  UserPoolId: string;
  
  /** The identity provider name to delete */
  ProviderName: string;
}

/**
 * List identity providers for a user pool
 * Returns all configured identity providers
 */
class ListIdentityProvidersCommand {
  constructor(input: ListIdentityProvidersCommandInput);
}

interface ListIdentityProvidersCommandInput {
  /** The user pool ID */
  UserPoolId: string;
  
  /** Maximum number of providers to return */
  MaxResults?: number;
  
  /** Pagination token for retrieving more results */
  NextToken?: string;
}

interface ListIdentityProvidersCommandOutput {
  /** Array of identity providers */
  Providers: IdentityProviderType[];
  
  /** Pagination token for more results */
  NextToken?: string;
}

/**
 * Get identity provider by identifier
 * Find identity provider using IdP identifier
 */
class GetIdentityProviderByIdentifierCommand {
  constructor(input: GetIdentityProviderByIdentifierCommandInput);
}

interface GetIdentityProviderByIdentifierCommandInput {
  /** The user pool ID */
  UserPoolId: string;
  
  /** The IdP identifier to search for */
  IdpIdentifier: string;
}

interface GoogleProviderDetails {
  /** Google OAuth 2.0 client ID */
  client_id: string;
  
  /** Google OAuth 2.0 client secret */
  client_secret: string;
  
  /** Requested OAuth scopes (space-separated) */
  authorize_scopes?: string;
  
  /** Custom OIDC discovery endpoint */
  oidc_issuer?: string;
}

interface FacebookProviderDetails {
  /** Facebook App ID */
  client_id: string;
  
  /** Facebook App Secret */
  client_secret: string;
  
  /** Requested permissions (comma-separated) */
  authorize_scopes?: string;
  
  /** Facebook API version */
  api_version?: string;
}

interface AmazonProviderDetails {
  /** Login with Amazon client ID */
  client_id: string;
  
  /** Login with Amazon client secret */
  client_secret: string;
  
  /** Requested scopes (space-separated) */
  authorize_scopes?: string;
}

interface AppleProviderDetails {
  /** Apple Services ID */
  client_id: string;
  
  /** Apple Team ID */
  team_id: string;
  
  /** Apple Key ID for the private key */
  key_id: string;
  
  /** Apple private key (PEM format) */
  private_key: string;
  
  /** Requested scopes (space-separated) */
  authorize_scopes?: string;
}

interface OIDCProviderDetails {
  /** OIDC client ID */
  client_id: string;
  
  /** OIDC client secret */
  client_secret: string;
  
  /** OIDC issuer URL */
  oidc_issuer: string;
  
  /** Requested scopes (space-separated) */
  authorize_scopes?: string;
  
  /** Additional request parameters */
  authorize_request_params?: Record<string, string>;
}

interface SAMLProviderDetails {
  /** SAML metadata document URL or XML content */
  MetadataURL?: string;
  MetadataFile?: string;
  
  /** SAML SSO URL */
  SSORedirectBindingURI?: string;
  
  /** SAML SLO URL */
  SLORedirectBindingURI?: string;
  
  /** SAML entity ID */
  IDPEntityID?: string;
  
  /** Request signing certificate */
  RequestSigningCertificate?: string;
  
  /** Encrypt SAML assertions */
  EncryptedAssertions?: string;
}

import {
  CognitoIdentityProviderClient,
  CreateIdentityProviderCommand
} from "@aws-sdk/client-cognito-identity-provider";

const client = new CognitoIdentityProviderClient({ region: "us-east-1" });
const userPoolId = "us-east-1_example123";

// Google Sign-In setup
const googleProvider = await client.send(new CreateIdentityProviderCommand({
  UserPoolId: userPoolId,
  ProviderName: "Google",
  ProviderType: "Google",
  ProviderDetails: {
    client_id: "123456789-abcdefghijklmnop.apps.googleusercontent.com",
    client_secret: "your-google-client-secret",
    authorize_scopes: "email profile openid"
  },
  AttributeMapping: {
    email: "email",
    name: "name",
    picture: "picture",
    given_name: "given_name",
    family_name: "family_name"
  }
}));

// Facebook Login setup
const facebookProvider = await client.send(new CreateIdentityProviderCommand({
  UserPoolId: userPoolId,
  ProviderName: "Facebook",
  ProviderType: "Facebook", 
  ProviderDetails: {
    client_id: "your-facebook-app-id",
    client_secret: "your-facebook-app-secret",
    authorize_scopes: "email,public_profile"
  },
  AttributeMapping: {
    email: "email",
    name: "name",
    picture: "picture",
    given_name: "first_name",
    family_name: "last_name"
  }
}));

// Sign in with Apple setup
const appleProvider = await client.send(new CreateIdentityProviderCommand({
  UserPoolId: userPoolId,
  ProviderName: "SignInWithApple",
  ProviderType: "SignInWithApple",
  ProviderDetails: {
    client_id: "com.yourcompany.yourapp",
    team_id: "YOUR_APPLE_TEAM_ID",
    key_id: "YOUR_APPLE_KEY_ID",
    private_key: "-----BEGIN PRIVATE KEY-----\n...\n-----END PRIVATE KEY-----",
    authorize_scopes: "email name"
  },
  AttributeMapping: {
    email: "email",
    name: "name"
  }
}));

interface SAMLAttributeMapping {
  /** Map SAML assertion attributes to Cognito attributes */
  email?: string;
  name?: string;
  given_name?: string;
  family_name?: string;
  phone_number?: string;
  
  /** Custom attribute mappings */
  [customAttribute: string]: string | undefined;
}

// SAML IdP with metadata URL
const samlProvider = await client.send(new CreateIdentityProviderCommand({
  UserPoolId: userPoolId,
  ProviderName: "CorporateAD",
  ProviderType: "SAML",
  ProviderDetails: {
    MetadataURL: "https://corp.example.com/adfs/services/trust/mex",
    IDPEntityID: "http://corp.example.com/adfs/services/trust",
    RequestSigningCertificate: "-----BEGIN CERTIFICATE-----\n...\n-----END CERTIFICATE-----"
  },
  AttributeMapping: {
    email: "http://schemas.xmlsoap.org/ws/2005/05/identity/claims/emailaddress",
    name: "http://schemas.xmlsoap.org/ws/2005/05/identity/claims/name",
    given_name: "http://schemas.xmlsoap.org/ws/2005/05/identity/claims/givenname",
    family_name: "http://schemas.xmlsoap.org/ws/2005/05/identity/claims/surname",
    department: "http://schemas.example.com/identity/claims/department"
  },
  IdpIdentifiers: ["corp.example.com"]
}));

// SAML IdP with metadata file content
const samlProviderFromFile = await client.send(new CreateIdentityProviderCommand({
  UserPoolId: userPoolId,
  ProviderName: "Azure AD",
  ProviderType: "SAML",
  ProviderDetails: {
    MetadataFile: `<?xml version="1.0" encoding="UTF-8"?>
      <md:EntityDescriptor xmlns:md="urn:oasis:names:tc:SAML:2.0:metadata">
        <!-- SAML metadata XML content -->
      </md:EntityDescriptor>`,
    EncryptedAssertions: "false"
  },
  AttributeMapping: {
    email: "http://schemas.xmlsoap.org/ws/2005/05/identity/claims/name",
    name: "http://schemas.microsoft.com/identity/claims/displayname"
  }
}));

// Generic OIDC provider
const oidcProvider = await client.send(new CreateIdentityProviderCommand({
  UserPoolId: userPoolId,
  ProviderName: "CustomOIDC",
  ProviderType: "OIDC",
  ProviderDetails: {
    client_id: "your-oidc-client-id",
    client_secret: "your-oidc-client-secret", 
    oidc_issuer: "https://auth.example.com",
    authorize_scopes: "openid email profile",
    authorize_request_params: JSON.stringify({
      response_type: "code",
      prompt: "select_account"
    })
  },
  AttributeMapping: {
    email: "email",
    name: "name",
    given_name: "given_name",
    family_name: "family_name",
    picture: "picture"
  }
}));

/**
 * Link identity provider to existing user (Admin)
 * Connect federated identity to existing Cognito user
 */
class AdminLinkProviderForUserCommand {
  constructor(input: AdminLinkProviderForUserCommandInput);
}

interface AdminLinkProviderForUserCommandInput {
  /** The user pool ID */
  UserPoolId: string;
  
  /** Existing Cognito user to link to */
  DestinationUser: ProviderUserIdentifierType;
  
  /** Source federated identity to link */
  SourceUser: ProviderUserIdentifierType;
}

interface ProviderUserIdentifierType {
  /** Identity provider name */
  ProviderName?: string;
  
  /** Provider attribute name (usually "Cognito_Subject") */
  ProviderAttributeName?: string;
  
  /** Provider attribute value (user identifier) */
  ProviderAttributeValue?: string;
}

/**
 * Disable identity provider for user (Admin)
 * Unlink federated identity from user account
 */
class AdminDisableProviderForUserCommand {
  constructor(input: AdminDisableProviderForUserCommandInput);
}

interface AdminDisableProviderForUserCommandInput {
  /** The user pool ID */
  UserPoolId: string;
  
  /** Federated identity to disable */
  User: ProviderUserIdentifierType;
}

import {
  CognitoIdentityProviderClient,
  CreateIdentityProviderCommand,
  ListIdentityProvidersCommand,
  UpdateUserPoolClientCommand,
  DescribeUserPoolClientCommand
} from "@aws-sdk/client-cognito-identity-provider";

const client = new CognitoIdentityProviderClient({ region: "us-east-1" });
const userPoolId = "us-east-1_example123";
const clientId = "your-client-id";

// 1. Set up multiple identity providers
const providers = await Promise.all([
  // Google
  client.send(new CreateIdentityProviderCommand({
    UserPoolId: userPoolId,
    ProviderName: "Google",
    ProviderType: "Google",
    ProviderDetails: {
      client_id: "google-client-id",
      client_secret: "google-client-secret",
      authorize_scopes: "email profile openid"
    },
    AttributeMapping: {
      email: "email",
      name: "name",
      picture: "picture"
    }
  })),
  
  // Facebook  
  client.send(new CreateIdentityProviderCommand({
    UserPoolId: userPoolId,
    ProviderName: "Facebook",
    ProviderType: "Facebook",
    ProviderDetails: {
      client_id: "facebook-app-id",
      client_secret: "facebook-app-secret",
      authorize_scopes: "email,public_profile"
    },
    AttributeMapping: {
      email: "email",
      name: "name"
    }
  })),
  
  // Corporate SAML
  client.send(new CreateIdentityProviderCommand({
    UserPoolId: userPoolId,
    ProviderName: "Corporate",
    ProviderType: "SAML",
    ProviderDetails: {
      MetadataURL: "https://corp.example.com/saml/metadata",
      IDPEntityID: "http://corp.example.com/saml"
    },
    AttributeMapping: {
      email: "http://schemas.xmlsoap.org/ws/2005/05/identity/claims/emailaddress",
      name: "http://schemas.xmlsoap.org/ws/2005/05/identity/claims/name"
    }
  }))
]);

// 2. Update app client to support all identity providers
const clientDetails = await client.send(new DescribeUserPoolClientCommand({
  UserPoolId: userPoolId,
  ClientId: clientId
}));

await client.send(new UpdateUserPoolClientCommand({
  UserPoolId: userPoolId,
  ClientId: clientId,
  ClientName: clientDetails.UserPoolClient!.ClientName,
  SupportedIdentityProviders: [
    "COGNITO",    // Native Cognito authentication
    "Google",     // Google Sign-In
    "Facebook",   // Facebook Login  
    "Corporate"   // Corporate SAML
  ],
  CallbackURLs: ["https://myapp.com/callback"],
  LogoutURLs: ["https://myapp.com/logout"],
  AllowedOAuthFlows: ["code"],
  AllowedOAuthScopes: ["email", "openid", "profile"],
  AllowedOAuthFlowsUserPoolClient: true
}));

// 3. List all configured providers
const allProviders = await client.send(new ListIdentityProvidersCommand({
  UserPoolId: userPoolId
}));

console.log("Configured identity providers:", 
  allProviders.Providers.map(p => p.ProviderName)
);

// Users can now authenticate with:
// - https://your-domain.auth.us-east-1.amazoncognito.com/oauth2/authorize?identity_provider=Google&...
// - https://your-domain.auth.us-east-1.amazoncognito.com/oauth2/authorize?identity_provider=Facebook&...
// - https://your-domain.auth.us-east-1.amazoncognito.com/oauth2/authorize?identity_provider=Corporate&...