AWS SSO is a cloud-based single sign-on (SSO) service that makes it easy to centrally manage SSO access to all of your AWS accounts and cloud applications.
What is the role of AWS SSO?
If you consider any organization, employees in that organization will have access to multiple applications. These applications can be custom built or third-party SaaS apps. Some examples timesheet app, payroll app or a intranet web portal. If the organization has an enterprise Identity provider, employees will be able to Single Sign-on to all these apps.
One way to make this work is to build a dashboard with links to all these internal & external apps so that users can sign-in to this dashboard and launch these apps. This is easier from a user perspective because users don’t have to remember or bookmark each application URL in their browser. Instead, users can login to a single unified dashboard and see all the apps that they are authorized to access.
AWS SSO provides this dashboard where users can login and see all the apps they are authorized to access. When the user launches any app, AWS SSO will Single Sign-On the user to the target App using SAML 2.0 federation. SAML 2.0 is a industry standard protocol that is widely used for Single Sign-On.
How to configure?
You can watch this video on how to configure Single Sign-On between AWS SSO & SAML Test Application
In this blog, I will list down the steps to enable AWS SSO, configure some test users and add a custom Spring SAML App application to the AWS SSO dashboard. Users can then login to AWS SSO dashboard and Single Sign-on to this Spring SAML app.
There are few prerequisites for setting up this integration:
- AWS Account — business or free tier.
- Knowledge on Java Spring
- Eclipse or any Java based IDE to run the Spring app
- Knowledge on SAML 2.0 protocol
Step 1 : Setup AWS SSO and test user to login to AWS SSO
- Login to AWS Management console and navigate to AWS SSO service. When you access this service for the first time, it will show Enable AWS SSO button.
- Click Enable button and it will take few seconds to show the dashboard
- You should see a “User portal URL” in the bottom of the Dashboard screen
- You can open an incognito window and navigate to this URL. If it works fine, it should show a login page with username field
- Go back to the Dashboard and select Users > Add User
- You can create a new user. Don’t forget to select “Generate a one-time password …” option
- You can proceed to the next screen and click Add user
- If it is successful, you should see a page with the username, one-time password and user portal URL
- Open a new incognito window, enter the user portal URL and login using the ssouser1 credentials
- After resetting the password, you should see this page. Since no applications are added, it will show this page which is fine.
Step 2 : Setup Java SAML sample app in Eclipse
- I am not listing down all the steps for setting up Java Spring project in Eclipse
- You can download the SAML app from https://github.com/spring-projects/spring-security-saml
- Import the project as a Maven project in eclipse
- You should see two projects. Add a tomcat server and deploy the webapp
- If there are no errors, you should see this page http://localhost:8080/java-saml-tookit-jspsample/ with a Login button
Step 3 : Configure Java SAML app SP metadata in AWS SSO
- In the Java project, there is a SAML configuration file onelogin.saml.properties
- SP Entity ID is available in onelogin.saml2.sp.entityid property. You can modify this property according to your requirements. I set it as onelogin.saml2.sp.entityid = http://localsp.example.com
- Go back to AWS SSO > Applications > Add a new application and select “Add a custom SAML 2.0 Application”
- Change the Display name to Java SAML App
- Go to Application Metadata section and select don’t have metadata option
- Enter these values from onelogin.saml.properties file in Java project
- Save changes and navigate to Attribute Mappings tab
- Add the following mappings and save changes
- Navigate to Assigned Users tab and assign ssouser1 to this application
- Navigate back to Configuration tab and download the “AWS SSO SAML metadata” file
Step 4 : Configure AWS SSO SAML IDP metadata in Java SAML app
- Open the AWS SSO IDP metadata file in a notepad
- Copy the entityID value
- Set the entity ID value to onelogin.saml2.idp.entityid property in onelogin.saml.properties
- Copy the <SingleSignOnService> Location URL from AWS SSO IDP metadata
- Set the Location URL to onelogin.saml2.idp.single_sign_on_service.url in onelogin.saml.properties
- Copy the <ds:X509Certificate> certificate value from AWS SSO IDP metadata
- Set the certificate value to onelogin.saml2.idp.x509cert in onelogin.saml.properties
- Also set the onelogin.saml2.debug to true and onelogin.saml2.strict to false in onelogin.saml.properties
Step 5 : Test the SP-Initiated SSO flow
- AWS SSO supports both SAML SP-Initiated and IDP-Initiated flows
- Start the tomcat server in eclipse and access this URL http://localhost:8080/java-saml-tookit-jspsample/
- On clicking “Login and access …” button, it should post a SAML AuthN request and take you to AWS SSO login page where you can enter the username “ssouser1”
- Both Mozilla and Chrome browsers have SAML plug-in which will show the SAML requests / responses. It is very useful for debugging purpose.
- After entering the password in next page and clicking the login button, AWS SSO will post a SAML Assertion response back to Java SAML app
- Java SAML App should single sign-on the user and show the user attribute details
Step 6 : Test the IDP-Initiated SSO flow
- Go to AWS SSO Dashboard and copy the user portal URL
- Navigate to this URL and it should show the login page
- You should see the Java SAML app tile
- On clicking the tile, it should automatically launch the Java SAML app in a new tab and show all the user attributes similar to a SP-Initiated SSO flow
This concludes the setup. I hope you enjoyed this blog.
Please ask your questions in the comments section.