Simplify external SAML identity provider integration with Amazon Cognito user pools using automated metadata extraction

Public sector organizations and technology vendors across industries—from healthcare and education to public safety and citizen services—struggle with complex identity integration requirements when deploying applications across multiple facilities and jurisdictions. For example, public sector healthcare independent software vendors (ISVs) deploying patient engagement platforms across government facilities face a common bottleneck: manual Amazon Cognito user pools metadata exchange with various state facilities’ SAML identity providers. A healthcare ISV rolling out telehealth solutions to more than 50 Department of Veterans Affairs (VA) medical centers must coordinate with each facility’s identity team to share user pools service provider (SP) metadata, await their configuration, and subsequently receive identity provider (IdP) metadata for completing Cognito integration. This manual process extends deployment timelines from weeks to months, delaying critical patient services. This post demonstrates how organizations can eliminate these integration delays using an automated metadata extraction solution built on Amazon Web Services (AWS) that provides self-service access to Amazon Cognito user pools metadata through a serverless REST API.

The challenges with manual metadata exchange

Identity federation enables single sign-on between a service provider (Cognito user pools) and external SAML identity providers by exchanging metadata containing essential configuration information. This metadata includes entity identifiers, service endpoints, and digital certificates required for secure authentication. However, traditional Cognito metadata exchange relies on manual processes that create significant operational overhead, as shown in the following flow diagram.

Figure 1: Diagram illustrating the manual metadata exchange and integration workflow between Amazon Cognito and an external SAML identity provider

Organizations deploying applications across multiple customer environments encounter numerous operational challenges. One major issue is coordination complexity, where security and operations teams must manually share configuration files, creating bottlenecks and inefficiencies. The approval process presents another significant hurdle, as security reviews and approvals can stretch from weeks to months for each environment. Additionally, manual processes increase the risk by potentially leading to errors and inconsistencies between different environments. As organizations scale, these manual workflows become increasingly difficult to manage. For public sector ISVs, these challenges are amplified when deploying across government agencies with varying security requirements and approval processes. A single application deployment might require integration with multiple separate identity systems across various customers, each with its own configuration requirements and workflows.

Automated metadata extraction solution overview

The Amazon Cognito Metadata Extractor solution eliminates manual metadata exchange by providing a serverless REST API that automatically generates and serves identity federation metadata for Cognito user pools. Built using AWS Serverless Application Model (AWS SAM), the solution includes:

• AWS Lambda function – Extracts real-time metadata from Cognito user pools and external identity providers
• Amazon API Gateway – Provides secure RESTful endpoints for metadata retrieval
• AWS Identity and Access Management (IAM) roles – Implements least-privilege access to Cognito services
• HTML test interface – Enables browser-based testing and generation, along with other standard mechanisms

Architecture overview

The solution follows a straightforward serverless architecture where identity provider administrators make HTTP GET requests to retrieve current user pools metadata. The Lambda function queries Amazon Cognito to obtain the latest configuration, including certificates and service endpoints, then formats this information into standards-compliant metadata XML. The following diagram shows this architecture.

Figure 2: Serverless architecture diagram showing automated identity metadata XML extraction from Amazon Cognito user pools through API Gateway and Lambda function integration

This approach delivers several significant benefits to organizations. Real-time accuracy is ensured as the metadata continuously reflects the current Cognito configuration, including any certificate rotations. External Identity administrators gain self-service capabilities, allowing them to retrieve metadata independently without needing to coordinate with service provider teams. The solution’s scalability is enhanced through a single API endpoint that can serve multiple identity providers and user pools (within an account) simultaneously. The streamlined process is illustrated in the diagram below.

Figure 3: Diagram depicting the streamlined metadata exchange and integration process between Amazon Cognito and an external SAML identity provider, facilitated by the Amazon Cognito Metadata Extractor solution

Implementation and usage

The solution provides two primary endpoints for metadata retrieval. General user pool metadata returns basic service provider metadata, including Entity ID (or identifier) to represent the SAML audience, Assertion Consumer Service URL (or Reply URL) as the destination for the SAML response, and Single Logout Service (SLS) URL:

GET /metadata/{userPoolId}

Provider-specific metadata returns comprehensive metadata including signing and encryption certificates for specific external identity providers within the Cognito user pool:

GET /metadata/{userPoolId}/{providerName}

The following screenshot shows a sample metadata XML generated by the solution.

Figure 2: Representative metadata XML from Amazon Cognito User pools, generated through the deployed solution

Measurable benefits and use cases

The automated metadata extraction solution addresses several common identity integration challenges:

• Enterprise identity integrations – Organizations with multiple business units can provide self-service metadata access to identity administrators, reducing IT overhead and deployment coordination requirements.
• DevOps automation – Continuous integration/continuous deployment (CI/CD) pipelines can programmatically retrieve updated metadata during infrastructure deployments, eliminating manual configuration steps and reducing deployment dependencies.
• Certificate rotation management – When identity certificates are rotated, external identity providers can automatically fetch updated metadata without manual intervention, maintaining service continuity during certificate lifecycle management.
• Multi-environment deployments – Development, staging, and production environments each expose their own metadata endpoints, enabling independent deployment workflows and reducing cross-environment coordination requirements.

Extending the solution

Organizations can enhance the basic implementation with additional capabilities:

• Metadata caching – Implement Amazon CloudFront distribution for serving static or frequently accessed metadata to reduce latency
• Webhook notifications – Trigger external systems when SP metadata or certificate changes occur
• Automatic updates – Add support for handling SP metadata changes and certificate rotations
• Batch operations – Support multiple user pool queries in a single request for large-scale deployments

Conclusion

Manual Cognito metadata exchange creates unnecessary friction in identity integration workflows, particularly for organizations deploying across multiple customer environments and identity providers. The Amazon Cognito Metadata Extractor solution eliminates these bottlenecks by providing automated, self-service access to current identity metadata through a cost-effective serverless API.

By implementing this solution, organizations can reduce identity integration timelines, minimize configuration errors, and enable scalable deployment workflows that support rapid business growth and emergency response requirements.

Next steps

Visit the Sample Amazon Cognito Metadata Extractor GitHub repository to deploy the solution in your AWS environment. The repository includes complete deployment instructions, sample code, and testing tools to get you started quickly. Transform your identity integration workflows today and accelerate your application deployments with simplified identity metadata exchange.

For comprehensive guidance on Amazon Cognito identity provider integration, explore the Amazon Cognito Developer Guide. To learn more about AWS identity and access management best practices, visit the AWS Security Blog for the latest implementation guidance and security recommendations.