AWS Cognito is a fantastic product that handles everything to do with your app’s users, so you don’t have to. You don't have to think about authentication, user profiles, user management, or ensuring that passwords are handled properly. AWS Cognito also handles federation with other systems.
I was asked a question recently;
I've used the Serverless framework to create a small app to support internal business functions. It's a private application and we're using AWS Cognito to secure it, but we need to use our Office365 logins. Is it possible to set this up?
In this post, we look at implementing AWS Cognito with federation against Office365. I'm assuming that you are already using API Gateway, AWS Lambda and AWS Cognito to provide login functionality. It's not immediately obvious to federate Cognito with Office365, so I thought it would be good to put together a short tutorial.
Let’s get started!
Firstly, we’ll jump into Office365 Azure AD Admin center, click Azure Active Directory, choose ‘App Registrations’ and then click ‘Endpoints’.
Select the Federation Metadata Document copy and keep this handy for the moment. This is a unique federation definition that is associated to your Azure AD tenant.
Open your AWS Console, navigate to your existing Cognito User Pool and click on Federation from the left-hand menu. Click the SAML option for external federated identity providers.
Paste the Office365 tenant federated metadata URL into the metadata document URL box. Put in a friendly provider name. Click Create Provider.
Click Attribute Mapping under Federation, choose the SAML tab and put in the attributes you want to capture across. In my case, I want to capture email addresses.
Under App integration, choose Domain Name. This is what we'll use as the Reply URL. Put in a friendly name for your user pool into the domain prefix.
Click General Settings and make a note of your Pool Id. It will be used later.
Open Azure AD Admin console. Choose Azure Active Directory, then App Registrations from the menu. Click New Application Registration and type in a friendly name. The Sign-On URL can be a link to the login page to your app. Click Create.
In the Registered App, choose Properties. The App ID URI is the field that checks the SAML. This is also known as an Audience URI or SP Identity URI.
This is the link between Cognito and AzureAD.
Cognito uses a unique App ID with a standard convention that cannot be changed. It has the following format:
so in my case it is:
Unfortunately, when trying to change this setting, the AzureAD web interface provides a really unhelpful popup message explaining that only URLs are accepted into the App ID field. This is a bug.
To get around this bug, we download the AzureAD Powershell from powershellgallery.com. If you have Windows 10, you can install it by typing: Install-Module -Name AzureADPreview
Follow the steps to set the App ID using powershell:
- Put in your username and password for your Azure AD Office365 subscription
- Get the ObjectId for the application you're trying to set the App ID for
- Set-AzureADApplication -ObjectId OBJECTGUIDHERE -IdentifierUris "urn:amazon:cognito:sp:XXXXXXXXXXX"
- Run Get-AzureADApplication -ObjectId OBJECTGUIDHERE |fl to confirm that the setting correctly applied.
Once the App ID has been set, go back to Azure AD Admin Console and choose Reply URLs under the App registration settings. Using the domain name configured in AWS Cognito, set the Reply URL to be:
In my case, I'll set it to be:
Modify the Callback URLs and Sign Out URLs fields to be your app's login and logout URLs.
https://FRIENDLYDOMAINPREFIX.auth.REGION.amazoncognito.com/oauth2/authorize?identity_provider=FRIENDLYPROVIDERNAME&redirect_uri=http://localhost:3000&response_type=TOKEN&client_id=CLIENTID&scope=aws.cognito.signin.user.admin email openid phone profile
Now you should be able to log in using Office365!
Here you can see the redirection happen and we're back at our app!
If there are any problems between, review the Additional Technical information in the Azure Sign In page. It's very easy to miss, but normally has some very useful information in there to help you work out why SAML isn't working as expected.
If you're receiving an error stating that Application with identifier ‘urn:amazon:cognito:sp:eu-west-1_zfYOQp1Hl’ was not found in the directory <uuid>, it means that the App ID is not set correctly. Set it to be the urn:amazon:cognito:sp:XXXXXXXXXXX URI as described in this article.
Do you have an authentication problem? Need some DevOps consulting around AWS Cognito and AWS Lambda? Reach out to email@example.com and we'll get in touch!