Single Sign-On into AWS with KeyCloak


The single goal of this article is to provide AWS CLI and Console access to users that exist within your KeyCloak realm.


At this time, AWS is unable to sync users and groups because KeyCloak does not support System for Cross-domain Identity Management (SCIM) 2.0. There is an open feature request for this functionality.


Log in to the AWS Console using your root account or admin IAM user. You will use the AWS Console to configure SSO.

Click Enable AWS SSO to begin the setup wizard. You will wait a few moments for AWS to configure some resources.
Select AWS Single Sign-On from the AWS service menu.
AWS will configure some defaults for your account.
(1) Click on Settings and then (2) click on “Change” next to Identity Source.
Download the AWS SSO SAML metadata by clicking the link. Save this file, we will use it for configuring Keycloak.

Enter the Admin Console for KeyCloak.

Within the KeyCloak admin console, navigate to your Realm, Clients, and then Create a new Client.
Under “Import” click “Select file” and upload the AWS SSO Metadata file from the last step performed in the AWS Console. Click “Save” when your screen looks similar to above.
After clicking “Save” you will be redirected to the Client Settings Page. Add a friendly Name and disabled “Client Signature Required”. AWS does not sign this request according to my experimentation. Scroll to the bottom of the page and click “Save” once more.
From the Realm Settings page, export your SAML 2.0 Identity Provider Metadata by right-clicking on the link and Save Link As.
Switching back to the AWS console window, upload the KeyCloak SAML metadata file by clicking “Browse”. The “Next: Review” button will activate once the this has completed.
After clicking the “Next: Review” you will be presented with a warning. Follow the instructions and click “Change identity source”. This should be a low-risk operation if you are not using AWS SSO currently and this is your first-time configuration.

Since KeyCloak does not support syncing users into AWS, you must add a user manually. This can be semi-automated using the API, but outside the scope of this article. We will proceed manually to fully conceptualize the process.

Under the Users section, click Add user.
Fill out the form. Username should be the user’s email address in KeyCloak. This is the default identifier.
For adding permissions, it is recommended you create role-based groups.
Now that the user is created, it is time to create permission to the account.
Navigate to the AWS accounts page > Permission sets > Create permissions set. Follow the wizard. If you do not have a ton of experience writing IAM policies, I would recommend choosing “Use an existing job function policy”. This is a managed policy set that AWS provides reasonable defaults. I chose “PowerUserAccess” in my first-time setup.
With the permission set, it’s time to allow the user to access the AWS account using the SSO profile. Select the checkbox next to your AWS account, then click Assign Users.
Assign the Permission set to the group by selecting it and clicking “Finish”.


Click the User portal URL link to begin the authentication process.
Clicking the User portal URL link in the AWS SSO dashboard should initiate a SAML authentication flow. If it does not, review the settings and refer to AWS SSO Troubleshooting Guide.
If authentication was successful, your screen should look similar to this. The AWS Account (1) indicates that we have granted this SSO user access to retrieve credentials backed by the PowerUser IAM policy.

Clicking Command line or programatic access will yield credentials to permission actions associated with the PowerUser role. The inline documentation is pretty complete, I encourage you to read it.

Alternatively there is a link that will provide the graphical console experience.


The traditional approach of creating an IAM user for each person that needs AWS access is tedious, error-prone, and not secure unless you have tight management around users. Creating a central authority of identity is critical for security as a business scales and becomes more reliant on external systems.

This configuration simplifies and fortifies the user on-boarding into AWS over dedicated IAM user accounts in that the distribution of credentials is tied to your organizations identity provider and is automated through a self-service portal.

While this article uses KeyCloak as the Identity Provider there are many commercial offerings that support more advanced features such as SCIM, eliminating the need to manually create a record in the AWS SSO User’s table.

To reiterate this process is still superior to IAM users. During the off-boarding phase, access to credentials is disabled when the user is locked within the identity provider. The record in the AWS SSO Users table only allows a successful auth event when the identity provider provides a valid response. Without the blessing from the IdP, the user will be unable to access the AWS account anymore.

In my setup, I have an internal redirect from https://<fqdn>/aws to the User portal URL. While the User portal URL is customizable, having the ability to control the entire URL is appealing for memory’s sake.

I hope that this may help other people looking for guidance on setup.