Our team recently took on the task of implementing Single Sign-On (SSO) from Active Directory to our client portal using AWS Cognito. It was an interesting project filled with learning opportunities and a few challenges. We want to share our experience and insights to help others who might be tackling a similar project.
Understanding the Tools
Before we dive in, let’s understand the tools and technologies involved in making this project happen:
Active Directory (AD): This is Identity Provider (IdP), responsible for authenticating users within the organization. Understanding its schema, attribute storage, and authentication mechanisms was essential for effective integration.
AWS Cognito: We used it as a Service Provider (SP), used for managing user identities and providing access to the client portal.
SAML (Security Assertion Markup Language): A critical component in the integration, SAML facilitates the exchange of authentication and authorization data between AD and AWS Cognito.
The Challenge
Our client, a financial services company, needed to integrate Active Directory (AD) with AWS Cognito to enable their financial advisors to seamlessly access customer documents through a single sign-on (SSO) system. The challenge was to create a secure, multi-tier setup that would allow advisors to authenticate via AD and gain access to resources managed by AWS Cognito without compromising security or user experience.
Key Insights
Understanding AWS Cognito and SAML
Our team works primarily with AWS, and our client was using AWS Cognito for customer identity and user management. AD was a 3rd party system that we needed to integrate to allow users seamless 1 click login. To accomplish this, the first step was understanding how AWS Cognito integrates with SAML-based identity providers like AD. We spent some time getting into the details of configuring identity providers, handling metadata, and managing SAML assertions. Here’s are some key insights:
Preparation:
- High-Level Design: We created a high-level design document to serve as a blueprint. This high level document outlined how the integration would work and interact with other components and services. This was such a valuable document that everyone ended up using to understand how this integration will work.
- Deep Dive into SAML: We invested time in understanding SAML authentication, studying the exchange of authentication and authorization data, and the roles of service providers (SP) and identity providers (IdP).
- Environment Planning: We set up development and staging environments to experiment with different configurations and understand AWS Cognito’s interaction with SAML IdPs. The issue here was that we had to manage multiple certificates and sometimes we had delays in getting the certificates. Also, there is a bigger potential in swapping certificates from multiple environments. This was a good approach because we could test in isolation, but it is a little bit cumbersome from a communication perspective.
Planning:
- Requirement Gathering: We collaborated with the client to define specific requirements for the integration, such as necessary attributes in the SAML assertions and their mappings to AWS Cognito user pools.
- Detailed Flowchart: We started getting deeper into HLD and we created a comprehensive flowchart detailing the integration process, mapping out steps from user authentication to the generation and validation of SAML assertions. This document continued to be a go to document for the integration and consensus.
- Security Review: Our team conducted a thorough review of security protocols to ensure compliance with industry standards and best practices. For this client, SOC 2 compliance was crucial, so we focused on:
- Data Encryption: Using TLS for data in transit and AWS Key Management Service (KMS) for data at rest.
- Logging and Monitoring: Implementing logging for all access and administrative activities using AWS CloudTrail to monitor for suspicious activities.
Continuous Learning:
- Staying Updated: We participated in relevant forums and communities to stay current with AWS services and SAML standards. AWS Cognito evolves, so we frequently review release notes to incorporate the latest best practices.
The Complexities of Attribute Mapping
Mapping user attributes between AD and AWS Cognito was more intricate than we expected. Gather as much information as possible from different stakeholders who understand different parts of the system. Also, make sure you have a process that will be followed when user attributes are changed.
Detailed Planning:
- Identify Necessary Attributes: It was crucial to have early identification of all necessary attributes and planning of their mappings between the systems. We started by listing every attribute we would need and understanding how each would be used in the context of our client portal and AWS Cognito.
- Attribute Mapping Matrix: We created a detailed matrix to document how each AD attribute should map to AWS Cognito attributes. This matrix became our reference point throughout the project, ensuring everyone was on the same page.
- Stakeholder Involvement: Engaging with stakeholders ensured all necessary attributes were accounted for and correctly mapped. We had several meetings with stakeholders to confirm our mappings and get their input on any special requirements.
Validation:
- Automated Scripts: We used automated scripts to validate attribute mappings, ensuring accuracy and completeness. These scripts ran checks to confirm that each attribute was correctly mapped and could be correctly read by AWS Cognito.
- Manual Verification: We also conducted manual verification to catch any discrepancies that automated scripts might miss. This involved manually logging in as different users and checking that all their attributes were correctly transferred.
Continuous Improvement:
- Feedback Loop: Establishing a feedback loop with users helped us gather insights on any issues related to attribute mappings. We encouraged users to report any problems they encountered, which helped us quickly address any issues.
- Regular Updates: We created an ongoing process to regularly update attribute mappings to accommodate changes in business requirements or updates in the identity provider’s schema. This was particularly important as the client’s requirements evolved over time.
Potential Points of Failure
Implementing SSO can present several potential points of failure. We proactively identified and addressed these risks:
Misconfiguration of SAML Metadata:
- Good Documentation: Documenting every single step of the configuration process in detail helped us avoid errors right from the start. This documentation was crucial for ensuring consistency and providing a clear reference for troubleshooting.
- Rigorous Testing: We tested the configuration extensively in various scenarios, not just the ideal ones, to ensure everything was set up correctly. This involved testing edge cases to make sure our setup could handle unexpected situations.
- Step-by-Step Implementation: Implementing and validating each step incrementally helped us catch errors early and avoid major setbacks. This incremental approach allowed us to test and verify each part of the system before moving on to the next.
Inaccurate Attribute Mapping:
- Automated Validation: We had scripts that automated the validation of attribute mappings, this saved us time and reduced errors. This automation was key to maintaining accuracy as the number of attributes and their complexity grew.
- Periodic System Reviews: We did regular system reviews and those ensured ongoing accuracy and caught potential issues early. These reviews involved both automated checks and manual reviews to ensure nothing was missed.
Security Vulnerabilities:
- Automate Certificate Rotation: If you don’t automate the rotation of self-signed certificates, prepare for issues when those expire. You need to ensure that certificates are always up-to-date. This process was crucial for maintaining security without requiring constant manual intervention. This is a very important part of this process.
- Implement Strict Access Controls: Having a good IAM policies minimized the risk of unauthorized access. We defined precise roles and permissions to ensure that only authorized users had access to sensitive resources.
- Security Audits: Regular security audits helped identify and mitigate potential vulnerabilities, keeping our system secure and compliant. These audits were covering everything from configuration settings to user access logs.
Product Changes
- Login/Signup/Forgot Password Flows: We had to rethink some authentication flows, keeping an eye on the bigger picture and how this piece fits within the larger system. This is especially important in enterprise applications. We redesigned these flows to ensure they were seamless and intuitive for users, while also integrating smoothly with the new SSO system.
- User Sync Across Systems: Managing user statuses across AD and AWS Cognito was challenging. Planning for scenarios like user deactivation in IdP and the appropriate response in SP was essential. We developed a robust syncing mechanism to ensure that user statuses were accurately reflected across both systems, and users were redirected appropriately based on their status.
Lessons Learned
There are many good lessons that we learned from this project. Here are some of them:
The Importance of Detailed Documentation:
- Configurations: Clear records of configuration settings ensure consistency and ease troubleshooting. Having detailed documentation meant we could quickly resolve any issues that arose.
- Mappings: Documenting attribute mappings with stakeholders ensures clarity and accuracy. This documentation was invaluable for maintaining alignment and preventing misunderstandings.
- Security Practices: Recording every security measure helps maintain high security standards. Detailed records of our security protocols ensured we met all compliance requirements.
Continuous Testing and Validation:
- Automated Tests: Automated tests validate configurations and mappings, saving time and reducing errors. These tests were a critical part of our validation process.
- Regular Reviews: Regular reviews catch and resolve issues promptly, keeping the implementation on track. These reviews helped us stay proactive rather than reactive.
Collaboration and Communication:
- Regular Meetings: Regular meetings with team members and stakeholders ensure everyone is on the same page. These meetings were key to maintaining alignment and addressing any issues promptly.
- Clear Updates: Frequent updates on progress and issues maintain transparency and trust. Keeping everyone informed helped build trust and ensured we could address any concerns quickly.
Iterative Development:
- Incremental Progress: Breaking the project into smaller tasks reduces complexity and manages risks. This approach helped us manage the project’s complexity and stay on track.
- Continuous Feedback: A continuous feedback loop with stakeholders helps gather insights and make necessary adjustments promptly. This feedback was essential for ensuring the project met all requirements.
- High-Level View: Always consider how the system pieces work together. This holistic view helped us avoid potential issues and satisfy all project requirements.
Conclusion
Implementing SSO from Active Directory to AWS Cognito is straightforward once you understand the technical aspects, from configuration to security. By focusing on preparation, continuous validation, and effective collaboration, we navigated potential challenges and achieved a successful implementation. We hope sharing these lessons helps you have a smoother process if you’re working on a similar project.
If you need a similar solution or have questions about your implementation, contact us at hello@agilno.com.
