The Good, The Ugly and The Bad…
This article serves as a practical guide on how-to implement Single Sign-On (SSO) for Amazone Web Services (AWS) using Microsoft Azure Active Directory (MS AAD) as an external SAML 2.0 Federated Identity Provider (IdP).
During this guide we will set-up an Azure AD Enterprise Application elaborating the AWS Service AWS SSO. We will totally set-up this Enterprise Application from scratch, being a Custom A.K.A. Non-gallery application.
I am fully aware that Microsoft has provided a Standard Enterprise Application called ‘Amazon Web Services (AWS)’. However this application was missing the integration with AWS SSO. Which you would need for decent Programmatic Access or AWS CLI SSO Support, or Organizational Multi-Account Support.
Apart from SSO we will also be automatically provisioning Azure AD Groups and Users to AWS SSO thanks to the System for Cross-domain Identity Management (SCIM) v2.0 protocol. The Roles (RBAC) within AWS for these automatically provisioned Users will be configured within AWS SSO, by mapping Groups/Users against Organizational Multi-Accounts and Permission Sets (Job Function Policy Sets). However futurewise, once RBAC has been provisioned this can be administered using the Azure AD Portal.
Let’s be clear that this set-up foresees in Federated Identities only. Let me repat that for you… Federated Identities only! Which means on an AWS IAM Level nothing actually gets added, changed or modified! So your IAM Users are left untouched, and so are your IAM Roles which you would use for AWS Services to assume. You can (should?) use AWS SSO for your User Accounts, and Service Accounts for e.g. running your CI/CD Pipelines, IaC.
Another great advantage of Azure AD Enterprise Application Integration is that you can optionally leverage Azure AD’s Multi Factor Authentication and Conditional Access Based Policies for accessing AWS.
During this guide we’ve set-up a demo scenario as follows:
Demo Scenario: Azure AD Groups and Users
| Group Name | Group Description | Group Members |
| AWS Development Administrators | Users with AdministratorAccess Rights in the Development Organization in AWS | “DevSecOps Engineer <devsecops.engineer@secotron.eu>” |
| AWS Development Viewers | Users with ReadOnlyAccess Rights in the Development Organization in AWS | “Development User <user.development@secotron.eu>” |
| AWS Production Administrators | Users with AdministratorAccess Rights in the Production Organization in AWS | “DevSecOps Engineer <devsecops.engineer@secotron.eu>” |
| AWS Production Viewers | Users with ReadOnlyAccess Rights in the Production Organization in AWS | “Production User <user.production@secotron.eu>” |
Demo Scenario: AWS Organizational Structure
| OU | Account |
| Root | Root Account |
| Root\E2E | Development Account |
| Root\E2E | Production Account |
Practical Guide: Stay with me, we’re in for the long run!
AWS: Activating AWS Single Sign-On (SSO) and retrieving our ‘AWS Federation Metadata XML File’
- From our AWS Management Console we need to activate AWS Single Sign-On (SSO). Be aware that the ‘AWS SSO’ service isn’t available within all regions.
- Visit https://console.aws.amazon.com/singlesignon
- Choose your AWS Region where you want to deploy ‘AWS SSO’ Service
- Click the ‘Enable AWS SSO’ button
- Setup an external Identity Source (SAML 2.0 IdP) as our Identity Provider
- Click the ‘1 – Choose your identity source’ Option
- Click the ‘Change’ Button next to Identity Source to choose an external Identity Source
- Click the ‘External identity provider’ Option
- Click ‘Download metadata file’ to retrieve the ‘AWS Federation Metadata XML File’
Azure AD: Creating our Custom Enterprise Application and activating Single Sign-On using our ‘AWS Federation Metadata XML File’
- From our Azure AD Portal we need to register our Custom Enterprise Application
- Visit https://aad.portal.azure.com/
- Open the ‘Azure Active Directory’ Blade
- Choose the ‘Enterprise applications’ Manage Option
- Click the ‘New application’ Button
- Choose the ‘Non-gallery application’ Tile
- Name your application ‘Amazon Web Services Single Sign-On (SSO)’ and click the ‘Add’ Button
- Next we will Set-up Single Sign-On for our new application using our ‘AWS Federation Metadata XML File’
- Choose the ‘Single sign-On’ Manage Option
- Choose the ‘SAML’ Tile
- Click the ‘Upload metadata file’ Button
- Select our ‘AWS Federation Metadata XML File’ and click the ‘Add’ Button*
* In case you get an error, download our ‘AWS Federation Metadata XML File’ again from the AWS SSO Management Console
- Confirm the ‘Entity ID’ and ‘ACS URL’ for IdP-Initiated SSO by clicking the ‘Save’ Button and close the window
- Click the ‘No, I will test later’ Button
- We need to add extra Claims required by AWS SSO
- Click the ‘Pencil’ Icon at ‘Step 2 – User Attributes & Claims’
- Click the ‘Add new claim’ Button
- Add the following 3 Claims (Role, RoleSessionName, SessionDuration)*
* Feel free to alter the SessionDuration Time for the Session Requests
| Name (Claim) | Namespace | Source | Source attribute |
| Role | https://aws.amazon.com/SAML/Attributes | Attribute | user.assignedroles |
| RoleSessionName | https://aws.amazon.com/SAML/Attributes | Attribute | user.userprincipalname |
| SessionDuration | https://aws.amazon.com/SAML/Attributes | Attribute | 900 |
- Next we will deploy a SAML Signing Certificate on our Custom Enterprise Application
- Click the ‘Pencil’ Icon at ‘Step 3 – SAML Signing Certificate’
- Click the ‘New Certificate’ button
- Click the ‘Save’ Button and close the window
- Downlad our ‘AzureAD Federation Metadata XML File’ to upload to AWS Single Sign-On (SSO)
- Click the ‘Federation Metadata XML – Download’ Link*
* In case you don’t see the Links yet, re-open the window by clicking the ‘Single sign-on’ Manage Option. This is due to the SAML Signing Certificate still deploying in the background.
AWS: Uploading our ‘AzureAD Federation Metadata XML File’ to AWS Single Sign-On (SSO)
- We continue on our AWS SSO Console and upload our retrieved ‘AzureAD Federation Metadata XML File’
- Click the Identity provider metadata-‘Browse’ Button and select your ‘AzureAD Federation Metadata XML File’
- Click the ‘Next: Review’ Button
- Type ‘CONFIRM’ and click the ‘Change identity source’ Button
- Click the ‘Return to settings’ Button
AWS/AzureAD: Setting up our custom ‘AWS User Portal’ URL or ‘AzureAD Sign on Url’
- From our AWS SSO Console we will customize and retrieve our ‘User Portal’ URL from where we left off
- Click the User Portal-‘Customize’ Button
- Choose your custom User Portal TenantID (e.g. ‘secotron’) and click the ‘Save’ Button
- From our Azure AD Portal we continue from where we left off and will modify our ‘Sign on URL’ from our Custom Enterprise Application
- Click the ‘Pencil’ Icon next to ‘1 – Basic SAML Configuration’
- Fill in your custom ‘Sign on URL’, click the ‘Save’ Button and close the window
AzureAD: Finish Custom Enterprise Application Properties
- From the AZure AD Portal we will assign a custom Logo for our application and verify that the application is published to the concerning users.
- Choose the ‘Single sign-On’ Manage Option
- Upload an Icon file (215px X 215px)
- Verify the application is ‘Visible to users?’ is set to ‘Yes’
- Click the ‘Save’ Button
- In case you’re interested you can always check out some other nice options at some other blades such as the ‘Self-service’, ‘Conditional Access’, ‘Audit Logs’, etc.
AWS/AzureAD: Configure automatic provisioning of Users and Groups using the Cross-domain Identity Management (SCIM) v2.0 protocol
- From the Azure AD Portal we will provision our Azure AD Groups holding our Users by adding them to our Customer Enterprise Application
- Choose the ‘Users and groups’ Manage Option
- Click the ‘Add user’ Button
- Click the ‘Users and groups’ Tile
- Choose your Azure AD Groups to provision to AWS SSO, and click the ‘Select’ Button
- Click the ‘Assign’ Button
- From the AWS SSO Console we will Enable Automatic Provisioning for our External Identity Provider (IdP) using the Cross-domain Identity Management (SCIM) v2.0 protocol and retrieve our SCIM Endpoint URL and Access Token
- Click the ‘Enable automatic provisioning’ Link
- Click the ‘Show token’ Link*
* For safety reasons it’s maybe best to temporarily copy these credentials to a safe place
- From the Azure AD Portal we will Enable Automatic Provisioning to AWS SSO using the retrieved SCIM Endpoint URL and Access Token from AWS SSO
- Choose the ‘Provisioning’ Manage Option
- Click the ‘Get started’ Button
- Choose the ‘Automatic’ Option
- Provide the ‘Tenant URL’ (SCIM Endpoint URL) and ‘Secret Token’ (Access Token) and click the ‘Test Connection’ Button
- Confirm the Connection is Working
- Provide your notification monitoring ‘Email’, check the ‘Send an email notification when a failure occurs’ and click the ‘Save’ Button
- To avoid any issues during the synchronization process we have to make sure we limit the phone numbers to a single value attribute, as AWS SSO currently does not support multiple values.
- Unfold the ‘Mappings’ section and click the ‘Provision Azure Active Directory Users’ Link
- Click the ‘Delete’ Button next to the telephoneNumber attribute
- Click the ‘Save’ Button and close the window
- Click ‘Yes’ to confirm the warning message
- Make sure that only Assigned users and groups are being synchronized, unless you want otherwise.
- Select or verify the Scope is set to ‘Sync only assigned users and groups’ and click the ‘Save’ Button
- Start the provisioning of Groups and Users from Azure AD to AWS SSO.
- Set the ‘Provisioning Status’ to ‘On’ and click the ‘Save’ Button
- Verify or troubleshoot the automatic provisioning of Groups and Users from Azure AD to AWS SSO.
- Choose the ‘Provisioning’ Manage Option
- Verify there are no errors listed*
* In case of any errors you can always troubleshoot using the ‘Azure AD Enterprise Application – Audit Logs’ or ‘AWS CloudTrails’. Mostly these will be due to incorrect data formats or inputs.
AWS: Assign Permission Sets on AWS Account Levels for Azure AD Provisioned Groups and/or Users
- From the AWS SSO Console we verify Azure AD (IdP) Groups and Users have been automatically provisioned to AWS SSO.
- Click ‘Groups’ Navigation Option
- Click ‘Users’ Navigation Option
- We need to create multiple ‘permission set’ to assign to provisioned Azure AD Groups and/or Users on AWS Account Levels. We will create two of them according to our Azure AD Groups ‘Administrators’ & ‘Viewers’, which correspondingly will use the ‘AdministratorAccess’ & ‘ReadOnlyAccess’ rights in the form of so called ‘Job Function Policies’
- Click ‘AWS Accounts’ Navigation Option and click the ‘Permission sets’ Tab
- Click the ‘Create permission set’ Button
- Choose the ‘Use an existing job function policy’ Option
- Choose the ‘AdministratorAccess’ Job Function Policy and click the ‘Create’ Button
- Repeat the same process for the ‘ViewOnlyAccess’ Job Function Policy
- Assign permission sets to provisioned Azure AD Groups and/or Users on AWS Account Levels. We will assign both permission sets we just created to each of the E2E Accounts.
- Click ‘AWS Accounts’ Navigation Option and click the ‘AWS Organization’ Tab
- Select both E2E Accounts (‘Production Account’, ‘Development Account’) and click the ‘Assign users’ Button
- Click the ‘Groups’ Tab
- Select the ‘*Administrator*’ Groups and click the ‘Next: Permission sets’ Button
- Select the ‘AdministratorAccess’ Permission Set and click the ‘Finish’ Button
- Repeat the same process for the ‘ViewOnlyAccess’ Permission Set
- Click the ‘Proceed to AWS Accounts’ button and verify the Permission Sets have been assigned
AWS: Logon to AWS Management Console using AWS SSO with Azure AD as our IdP
- Using our Azure AD credentials we should now be able to logon to AWS using our previously setup AWS SSO Portal URL and open the AWS Management Console.
- Visit ‘https://secotron.awsapps.com/start‘ or use the Microsoft My Applications Portal at ‘https://myapplications.microsoft.com‘
- After being redirected you should be able to logon using your Azure AD Credentials
- Since we have optionally MFA configured on our Enterprise Application and Azure AD Tenant we are asked to perform Multi Factor Authentication
- Click the ‘Management Console’ links next to one of the assigned accounts
- We now have access to the AWS Management Console!
AWS: Logon to AWS for Programmatic Access using AWS SSO with Azure AD as our IdP
- Using our Azure AD credentials we should now be able to logon to AWS using our previously setup AWS SSO Portal URL and request our Programmatic Access Credentials.
- Visit ‘https://secotron.awsapps.com/start‘ or use the Microsoft My Applications Portal at ‘https://myapplications.microsoft.com‘
- After being redirected you should be able to logon using your Azure AD Credentials
- Since we have optionally MFA configured on our Enterprise Application and Azure AD Tenant we are asked to perform Multi Factor Authentication
- Click the ‘Command line or programmatic access’ links next to one of the assigned accounts
- Copy the provided credential sets for use with e.g. AWS CLI
AWS: Logon to AWS CLI using AWS SSO with Azure AD as our IdP
- Using our Azure AD credentials we should now be able to logon to the AWS CLI using our previously setup AWS SSO Portal URL and setup our AWS CLI SSO Enabled Profile for the ‘Development Account’ with the ‘ViewOnlyAccess’ Permission Set. We will register this profile with the name ‘dev-viewonly’.
- Start configuring ‘dev-viewonly’ profile using SSO
$ aws configure sso --profile dev-viewonly- Provide SSO start URL
$ aws configure sso --profile dev-viewonly
SSO start URL [None]: https://secotron.awsapps.com/start- Provide your AWS SSO Portal Region, which has to match the one you chose earlier
$ aws configure sso --profile dev-viewonly
SSO start URL [None]: https://secotron.awsapps.com/start
SSO Region [None]: eu-central-1- Next your browser will automatically open to perform the actual authentication process
$ aws configure sso --profile dev-viewonly
SSO start URL [None]: https://secotron.awsapps.com/start
SSO Region [None]: eu-central-1
Attempting to automatically open the SSO authorization page in your default browser.
If the browser does not open or you wish to use a different device to authorize this request, open the following URL:
https://device.sso.eu-central-1.amazonaws.com/
Then enter the code:
S**J-J**L
- Since we have optionally MFA configured on our Enterprise Application and Azure AD Tenant we are asked to perform Multi Factor Authentication
- Click the ‘Sign in to AWS CLI’ Button
- We receive a confirmation message that we have now successfully signed in
- Our AWS CLI will now ask us for which account we want to register the profile, in this example we select the ‘Development Account’
$ aws configure sso --profile dev-viewonly
SSO start URL [None]: https://secotron.awsapps.com/start
SSO Region [None]: eu-central-1
Attempting to automatically open the SSO authorization page in your default browser.
If the browser does not open or you wish to use a different device to authorize this request, open the following URL:
https://device.sso.eu-central-1.amazonaws.com/
Then enter the code:
S**J-J**L
There are 2 AWS accounts available to you.
Production Account, user.production@secotron.eu (285868560562)
> Development Account, user.development@secotron.eu (101454761189)- After choosing the account, we can configure the Default Region for the AWS CLI Profile. Of course this doesn’t have to necessarily match the AWS SSO Hosted Region.
$ aws configure sso --profile dev-viewonly
SSO start URL [None]: https://secotron.awsapps.com/start
SSO Region [None]: eu-central-1
Attempting to automatically open the SSO authorization page in your default browser.
If the browser does not open or you wish to use a different device to authorize this request, open the following URL:
https://device.sso.eu-central-1.amazonaws.com/
Then enter the code:
S**J-J**L
There are 2 AWS accounts available to you.
Using the account ID 101454761189
The only role available to you is: ViewOnlyAccess
Using the role name "ViewOnlyAccess"
CLI default client Region [None]: eu-west-3- Enter your default CLI Output format (e.g. ‘json’)
$ aws configure sso --profile dev-viewonly
SSO start URL [None]: https://secotron.awsapps.com/start
SSO Region [None]: eu-central-1
Attempting to automatically open the SSO authorization page in your default browser.
If the browser does not open or you wish to use a different device to authorize this request, open the following URL:
https://device.sso.eu-central-1.amazonaws.com/
Then enter the code:
S**J-J**L
There are 2 AWS accounts available to you.
Using the account ID 101454761189
The only role available to you is: ViewOnlyAccess
Using the role name "ViewOnlyAccess"
CLI default client Region [None]: eu-west-3
CLI default output format [None]: json- We have successfully configured the profile!
$ aws configure sso --profile dev-viewonly
SSO start URL [None]: https://secotron.awsapps.com/start
SSO Region [None]: eu-central-1
Attempting to automatically open the SSO authorization page in your default browser.
If the browser does not open or you wish to use a different device to authorize this request, open the following URL:
https://device.sso.eu-central-1.amazonaws.com/
Then enter the code:
S**J-J**L
There are 2 AWS accounts available to you.
Using the account ID 101454761189
The only role available to you is: ViewOnlyAccess
Using the role name "ViewOnlyAccess"
CLI default client Region [None]: eu-west-3
CLI default output format [None]: json
To use this profile, specify the profile name using --profile, as shown:
aws s3 ls --profile dev-viewonly
$- We are now ready to start using our new AWS CLI SSO Enabled Profile called ‘dev-viewonly’. As an example we will create a new S3 Bucket with it.
- List all S3 Buckets
$ aws --profile dev-viewonly s3 ls
2020-05-31 03:04:58 dev-s3-general
$- In case you have been signed out or your tokens have expired you can refresh your profile tokens using the sso login command subset.
- Refresh AWS CLI SSO Profile Tokes
$ aws sso login --profile dev-viewonly
Attempting to automatically open the SSO authorization page in your default browser.
If the browser does not open or you wish to use a different device to authorize this request, open the following URL:
https://device.sso.eu-central-1.amazonaws.com/
Then enter the code:
P**V-P**L
Successully logged into Start URL: https://secotron.awsapps.com/startGreat to see you made it this far! Hope you had a wonderful journey.
SECOTRON | Thomas geens
Super useful post, just followed it and worked well. Quick note: I had to use the following URL for the SAML claims, I think the URL you used above may be outdated.
Instead of: https://aws.amazon.com/SAML/Attributes
I used: https://signin.aws.amazon.com/saml
Thanks!