User Documentation / Client Developer Documentation / Developer Documentation
- Presentation
- Deployment
- Deploying with the AWS Amplify console
- Deploying with Existing UserPool
- Register a client
- CSS & UI components customization instruction
- Identity Providers
- OIDC Provider (oauth2)
- SAML Provider
- Social Providers
- Step 1: Register with Facebook to get a App ID and App Secret
- Step 2: Finish registering with Facebook
- Step 1: Register with Google to get a OAuth client ID and client secret
- Step 2: Finish registering with Google
- Step 1: Register with Amazon to get a Client ID and Client Secret
- Step 2: Finish registering with Amazon
- Migration instructions
- Uninstall
This document explains how to use the broker:
- How to deploy (and uninstall)
- How to customize
- How to migrate from an existing user pool system
The AWS Amplify Identity Broker is a centralized login solution. It is a component you can use to authenticate your user on all your websites and applications:
The broker will be deployed within your own AWS account and will be in your full control (see Deployment section).
Using the broker your users will have the same unique identity across all your websites and applications. The broker provides Single Sign On (SSO): your users will have to login only once to be authenticated on all your services (but can have different permission levels specific to every application).
Optionally you can add external IdP (Identity Providers) to the broker. Which means that the user can sign-in using your corporate (or your customer corporate) Active Directory or using Facebook, Google or Amazon login or any OIDC and SAML IdP. Technically you can add up to 300 IdPs to your broker (limit coming from Amazon Cognito documented here). Today user coming from any client will see the same list of IdPs but you can fork the broker project and customize the behavior to make the list dynamic and for example:
- show the corporate IdP to people accessing the broker from your office private network
- show a list of IdP specific to a customer by giving them a special URL (like a link with a get parameter flag)
- show a list of IdP specific to a client application
Note that even if your users login in with a 3rd party IdP they will have a unique and persistent identity within the broker (under the hood a Amazon Cognito user pool identity).
In term of UI customization because you are in control of the source code and the deployment infrastructure you can make any change you like. The same applies for flow customization where all the front end part are customizable using the broker and backend flows can be customized using Amazon Cognito Lambda Triggers. The broker already leverage some of these triggers to introduce special feature like i18n (internationalization).
Finally the broker is a living open source project and your contributions are welcome if you see a missing feature that can be useful to all the broker users. Please see the CONTRIBUTING guide and the Developer Documentation if you are interested by contributing.
Selecting an authentication flow is a critical decision in term of security. We support several options to allow you connecting existing application that supports only one specific flow.
The AWS Amplify identity broker exposes two standard Oauth2 authentication flows:
- Implicit flow: the simpler one. It require just a link from your app and for you to read a GET parameter. This flow only returns an id_token you should not use an id_token to authenticate a user against a backend. (see details below)
- PKCE flow: the most secured flow. It will require you to generate random strings, apply some hashed and exchange information two times with the broker.
Expand the section below to see the detailed flows:
Implicit flow
Flow entities are:
- User: the user and his browser
- Client Application: (like the one from our client demo project)
- Identity Broker : the main project
- DynamoDB: the broker storage layer
- Cognito: The Amazon Cognito service and endpoints
Implicit flow
Note: Accordingly to the what the Oauth2 BCP recommend we do not return the access_token in that flow but only the id_token.
PKCE flow
Flow entities are:
- User: the user and his browser
- Client Application: (like the one from our client demo project)
- Identity Broker : the main project
- DynamoDB: the broker storage layer
- Cognito: The Amazon Cognito service and endpoints
See Client Developer Documentation to see how to implement a client using these flows.
The project architecture is the following:
See Developer Documentation to see more detailed information on every component.
COST The project architecture is Serverless, you only pay when there is user activity plus a small amount of storage (website static assets, dynamodb tables). Overall the solution is very cost effective. Amazon Cognito will be the primary source of cost, see Amazon Cognito pricing to estimate your costs.
Prerequisites : In order to deploy the solution you need:
- an AWS account
- the AWS CLI installed with administrator credentials (installation-link)
- the AWS Amplify CLI (installation link), install and configure.
- this project will need some permissions in addition to what you get from
AdministratorAccess-Amplify
policy. Add the following permissions to an inline policy.
{
"Version": "2012-10-17",
"Statement": [
{
"Effect": "Allow",
"Action": [
"kms:CreateKey",
"kms:CreateAlias",
"kms:CreateGrant",
"kms:Decrypt",
"kms:DescribeKey",
"kms:EnableKeyRotation",
"kms:Encrypt",
"kms:PutKeyPolicy",
"kms:TagResource",
"kms:ScheduleKeyDeletion",
"kms:DeleteAlias",
"dynamodb:DescribeContributorInsights",
"dynamodb:DescribeKinesisStreamingDestination",
"lambda:GetFunctionCodeSigningConfig",
"s3:GetBucketPolicy",
"cloudfront:ListCloudFrontOriginAccessIdentities",
"sts:GetCallerIdentity"
],
"Resource": "*"
}
]
}
1. Clone the project or fork it
git clone [email protected]:awslabs/aws-amplify-identity-broker.git
Note: If you want to save your modification and settings under Git your should Fork this repository and work from your fork. You can also start with a clone, fork and add your fork as another remote.
2. Install all the dependencies
cd aws-amplify-identity-broker
npm install
3. Set your Hosted UI Domain Name
To set the Hosted UI domain name go to /amplify/backend/auth/amplifyIdentityBrokerAuth/parameters.json and edit the hostedUIDomainName
property. Be default it is "amplifyidbroker". When created, the Hosted UI domain name will take the form https://{hostedUIDomainName}-{environment}.auth.{region}.amazoncognito.com
WARNING: The Cognito domain name has to be unique among all AWS customers in your selected region. Conflicting domain name is a cause of deployment failure.
4. Set your User Pool's Federated Social Identity Providers
To set the social IdPs included in your user pool go to /amplify/backend/auth/amplifyIdentityBrokerAuth/parameters.json and edit authProvidersUserPool
and hostedUIProviderMeta
arrays. By default Facebook, Google, and LoginWithAmazon are configured but each can be removed based on which providers you want to allow users to sign in with. If you add them again after deployment you'll just have to redo the step 6, 7 and 8.
If you don't want any social provider just make the arrays authProvidersUserPool
and hostedUIProviderMeta
empty. For example:
"authProvidersUserPool": [],
"hostedUIProviderMeta": "[]",
When initializing your environment in Step 6 you will be prompted for a Client ID and Client secret for each social provider you included. You can get these by completing Step 1 of the provided instructions for each social provider found here
5. Delete the AWS demo environment file
Remove the file with the AWS dev & demo environment (amplify will create a new file with your environment information later)
rm -f ./amplify/team-provider-info.json
6. Initialize your environment
You need to have the AWS cli and AWS credentials in place before running this
amplify init
You will be prompted for a name for your environment.
If you defined any at step 4, you will be also be asked for a Client ID and Client secret for each social provider you included (If you don't have this information yet, you can enter "123456" for each value and edit later see section Identity Providers for details)
7. Configure config-overrides.js
The file config-overrides.js is used at compile time to configure the Single Page App. Edit the file and add the settings for your environment:
case "<your-amplify-environment-name>": localConfig = {
"providers": ["<a-corporate-SSO>", "Facebook", "LoginWithAmazon", "Google"]
};
If you do not need to federate just let the list empty:
case "<your-amplify-environment-name>": localConfig = {
"providers": []
};
The names entered has to match what the Amazon Cognito documentation ask for identity_provider
. See below on the page detail about how to setup federation for SAML, OIDC, Facebook, Google and Amazon as IdPs.
8. Publish the app
This command will create all the backend resources and the hosting bucket plus cloudfront distribution that will host the broker:
amplify publish
9. Setup your own domain (optional)
If you use Cloudfront directly (by default), you should setup your own domain following this guide.
If you plan to use AWS Amplify Console as a CI/CD pipeline to deploy, skip that step and go to Deploying with the AWS Amplify console section.
Once your domain associated with the broker, you need to indicate it inside amplify/team-provider-info.json:
"your-env-name": {
"awscloudformation": {
...
},
"categories": {
"auth": {
...
},
"function": {
"amplifyIdentityBrokerPostDeployment": {
"hostingDomain": "https://your-own-domain.com" <-- Here indicate the domain your Broker uses
},
...
}
}
}
After a change on the hostingDomain in amplify/team-provider-info.json, if you already deployed the project the Amplify CLI will not detect your change automatically. You will need to do the following command to propagate your change:
amplify push --force
To verify if the change have been propagated you can open one of the AWS Lambda within teh AWS console and look at the value of the environment variable HOSTING_DOMAIN
If you want to use the AWS Amplify console as your CI/CD pipeline to automate the deployment of the solution, you will need to set the following environment variable inside your AWS Amplify console app: (You would need to add only the variables corresponding to the social platforms you have configured during the Auth CLI setup):
AMPLIFY_FACEBOOK_CLIENT_ID
AMPLIFY_FACEBOOK_CLIENT_SECRET
AMPLIFY_GOOGLE_CLIENT_ID
AMPLIFY_GOOGLE_CLIENT_SECRET
AMPLIFY_AMAZON_CLIENT_ID
AMPLIFY_AMAZON_CLIENT_SECRET
Note: This variable requirement is a temporary workaround that may disappear in the future. We'll update this documentation accordingly.
Once the environment is created you'll need to add the necessary redirect rules manually. On the AWS console, go to AWS Amplify, select your app, on the left menu click on Rewrites and redirects and clic Edit to input the following values:
First Header | Second Header | Type |
---|---|---|
/oauth2/<*> | ...api-gateway-url.../oauth2/<*> | 200 |
/storage | ...api-gateway-url.../storage | 200 |
/.well-known/jwks.json | ...api-gateway-url.../.well-known/jwks.json | 200 |
/verifyClient | ...api-gateway-url.../verifyClient | 200 |
/clients | ...api-gateway-url.../clients | 200 |
/accountConfirmation | ...api-gateway-url.../accountConfirmation | 200 |
/dashboard | /index.html | 200 |
/settings | /index.html | 200 |
/logout | /index.html | 200 |
/<*> | /index.html | 404 |
Note: The ...api-gateway-url...
needs to be replaced by the entry point url of the API Gateway associated with your broker. You can find the value by going to the Amazon API Gateway service or by looking at the AWS CloudFormation service and reading at the output parameter RootUrl
of the template amplify-amplify-identity-broker-<env>-xxxxxx-apiamplifyIdentityBrokerApi-XXXXXXXXXXX
.
IMPORTANT The order of the redirect rules is important!
Your setup should look like that:
See the documentation for more info about how AWS Amplify console rules works.
Why do we need this? We need to add the redirect rules because when the AWS Amplify Console service deploys the broker he doesn't deploy the S3 and Cloudfront hosting but use a managed hosting. Therefore the behavior we set through the CloudFormation templates of this project are not applied and we need to reproduce the same settings within the AWS Amplify Console service context.
If you plan to configure your custom domain the process follow instructions from this guide.
NOTE: If you want do not want your custom domain to use the AWS Amplify console provided domain
https://master.XXXXXXXXXX.amplifyapp.com/
you have to tell the broker anyway.
Once done indicate your domain (or the AWS Amplify provided one) to the broker by updating your environment configuration on amplify/team-provider-info.json:
"your-env-name": {
"awscloudformation": {
...
},
"categories": {
"auth": {
...
},
"function": {
"amplifyIdentityBrokerPostDeployment": {
"hostingDomain": "https://your-own-domain.com" <-- Here indicate the domain your Broker uses
},
...
}
}
}
After a change on the hostingDomain in amplify/team-provider-info.json, if you already deployed the project the Amplify CLI will not detect your change automatically. You will need to do the following command to propagate your change:
amplify push --force
To verify if the change have been propagated you can open one of the AWS Lambda within the AWS console and look at the value of the environment variable HOSTING_DOMAIN
This project is setup with End-to-end Testing with Cypress.
If you use Amplify CICD Integration, you must either setup necessary step for testing or disable testing. You may only run test on specific branch.
Option 1: Setup Testing
- Visit Cognito Console.
- Create a test user.
- Login with the test user and set the password.
- Add the test user email and password as
CYPRESS_EMAIL
andCYPRESS_PASSWORD
in Amplify Environment Variable. - When test locally, run
npx cypress run --env EMAIL=<email>,PASSWORD=<password>
Option 2: Disable Testing
- Set Amplify Environment Variable
USER_DISABLE_TESTS
totrue
on branch. Visit Amplify Documentation for more detail.
You may also choose to deploy this application with existing UserPool.
Important Note: Some immutable setting of Existing UserPool may not align with this application. For example, Custom Attributes cannot be modified or deleted once created. Test it carefully with equivalent setting in development environment.
To deploy this application with existing UserPool follow the procedure below instead of normal deployment.
- Deploy AmplifyIdentityBroker without Cognito
- Create Cognito Client in existing Cognito
- Delete
amplify/team-provider-info.json
- Update
amplify/backend/backend-config.json
- Add property
"serviceType": "imported"
toamplifyIdentityBrokerAuth
- Add property
- Delete
amplify/backend/auth/amplifyIdentityBrokerAuth/amplifyIdentityBrokerAuth-cloudformation-template.yml
- Run
amplify init
- Run
amplify push
- Add required setting to existing Cognito following settings in
amplify/backend/auth/amplifyIdentityBrokerAuth/amplifyIdentityBrokerAuth-cloudformation-template.yml
(This step may affect existing application. Test it carefully with development environment)- Add Custom Attributes (Boolean attributes cannot be created with console, so use SDK or CLI)
- Associate Lambda Triggers
- Check other settings are set correctly (i.e. MFA, CognitoDomain, callback URLs, ...)
To use the identity broker you must:
- create a Cognito App and configure it
- (only for if you want the SSO dashboard) register your app in the Amazon DynamoDB table
amplifyIdentityBrokerClients
So the very first operation is to open your AWS console and to go to Amazon Cognito and open the UserPool associated with your broker. On the menu left go to App clients then at the bottom of the page clic on the link Add another app client. Enter a name (the exact name doesn't mater this is only for you), uncheck Generate client secret and clic on the button Create app client:
At this point make sure you take note of the client id. This client id is very important: you need to give it to the admin of the client application.
Once the app client created you need to configure it. On the left menu go to App client settings, look for your app client and do the following settings:
- Add your client redirect_uri (the one from your client website or app) and add also the URL of your broker as a redirect_uri
- Add your client logout URI (the one from your client website or app) and add also the URL + /logout of your broker as a logout uri
- Select the identity providers you want the broker to show when a user will come from that client app to login (you don't have to check all)
- Select Authorization code grant
- Select the scope you want to retrieve in the access_token delivered to this client app
Your setting page should look like this:
Registering an app for the dashboard
You don't need to do this if you do not want to use the SSO dashboard.
On the AWS console, go to Amazon DynamoDB and look at the table named amplifyIdentityBrokerClients-yourAmplifyEnv
. Then click on Items and Create Item button.
Enter an item like:
{
"client_id": "your-cognito-app-clien-id",
"client_name": "App name to be displayed on Dashboard",
"logback_uri": "https://yourclient.url.for.auto/login"
}
Click Create, your page should look like this:
A logback_uri is just a URL on your client app that start immediatly a PKCE flow (exactly has if the user had clicked on the login button).
The Broker code is based on React, aws-amplify and @aws-amplify/ui-react. While you can customize the CSS, JS and HTML anyway you want, we provide here several tips to make your change more efficient and easier to maintain.
We use CSS Variables to setup the color of the project.
In the file src/index.css we set the root color like that:
:root{
--amplify-primary-color: #008000;
--amplify-primary-tint: #0000FF;
--amplify-primary-shade: #008000;
}
For more option on the AWS Amplify UI component look at the Documentation
We've define all CSS extra properties in src/index.css, look at this file before any override.
The setup of federation with 3rd party Identity Providers has to be done within the Amazon Cognito User Pool associated with your running broker and a small change is to make on the broker itself to let him aware of the additional IdPs to display (see PREREQUISITE down below).
The changes made against the Amazon Cognito User Pool should be done within the AWS console.
PREREQUISITE:
To add identity providers, you need to insert these providers under the file config-overrides.js which is at the root of the project. You have to add the settings on the environment you like to modify.
Example:
case "production": localConfig = {
"providers": ["Provider1", "Provider2", "LoginWithAmazon", "Facebook", "Google"]
};
break;
Be exact with the name of your OIDC and SAML providers or strings that match what the Amazon Cognito documentation is asking identity_provider
for social federation.
Note that the label that appear in the button is displayed using the i18n AWS Amplify system. If you want to change the name edit the file src/strings.js and create label that match your provider name. Example:
Provider1: "Sign In with first provider",
Provider2: "Sign In with another provider",
AMAZON_SIGNIN: "Sign In with Amazon",
GOOGLE_SIGNIN: "Sign In with Google",
FACEBOOK_SIGNIN: "Sign In with Facebook",
See next sections for specific provider steps.
AFTER ANY IDP ADDITION:
After adding any IdP, make sure you Enable your provider on the app settings of the broker inside the Amazon Cognito user pool.
On the AWS console, on the Amazon Cognito User Pool page, go on App settings
and check the box you want to activate.
Your settings should look like something like this:
Follow the Amazon Cognito User Pool OIDC IDP documentation. Remember the name you choose for your provider, you have to use it inside config-overrides.js and src/strings.js as explained before.
Follow the Amazon Cognito User Pool SAML IDP documentation. Remember the name you choose for your provider, you have to use it inside config-overrides.js and src/strings.js as explained before.
Social Provider instructions taken from Amazon Cognito Documentation.
- Create a developer account with Facebook.
- Sign in with your Facebook credentials.
- From the My Apps menu, choose Create New App.
- Select For Everything Else, give your Facebook app a name and choose Create App ID.
- On the left navigation bar, choose Settings and then Basic.
- Note the App ID and the App Secret. You will use them when running
amplify init
- Choose + Add Platform from the bottom of the page.
- Choose Website
- Under Website, type your user pool domain with the /oauth2/idpresponse endpoint into Site URL.
- Choose Save changes
- Type your user pool domain into App Domains
- Choose Save changes.
- From the navigation bar choose Products and then Set up from Facebook Login.
- From the navigation bar choose Facebook Login and then Settings. Type your redirect URL into Valid OAuth Redirect URIs. It will consist of your user pool domain with the /oauth2/idpresponse endpoint.
- Choose Save changes.
- Create a developer account with Google.
- Sign in with your Google credentials.
- Choose Create Project
- Type in a project name and choose Create
- On the left navigation bar, choose OAuth consent screen
- Select your User Type and choose Create
- Type in an application name and choose Save
- On the left navigation bar, choose Credentials
- Create your OAuth 2.0 credentials by choosing OAuth client ID from the Create credentials drop-down list.
- Choose Web application. and type in a name for your OAuth 2.0 client
- Choose Create.
- Note the OAuth client ID and client secret. You will use them when running
amplify init
- Click edit on the OAuth 2.0 Client IDs you created in Step 1
- Type your user pool domain into Authorized JavaScript origins.
- Type your user pool domain with the /oauth2/idpresponse endpoint into Authorized Redirect URIs.
- Choose Save
Amazon
- Create a developer account with Amazon.
- Sign in with your Amazon credentials.
- You need to create an Amazon security profile to receive the Amazon client ID and client secret. Choose Apps and Services from navigation bar at the top of the page and then choose Login with Amazon.
- Choose Create a Security Profile.
- Type in a Security Profile Name, a Security Profile Description, and a Consent Privacy Notice URL.
- Choose Save.
- Choose Client ID and Client Secret to show the client ID and secret. You will use them when running
amplify init
- Hover over the gear and choose Web Settings, and then choose Edit.
- Type your user pool domain into Allowed Origins.
- Type your user pool domain with the /oauth2/idpresponse endpoint into Allowed Return URLs.
- Choose Save.
DISCLAIMER: Migrating credentials from an existing system to Amazon Cognito comes with the risk that these credentials have been exposed in the past. For better security it is recommended to force the users to recreate passwords. The documentation below shows how to migrate users and credentials for learning purpose only.
In this project we provide an example of a Lambda function that migrate users one at a time. For our demo we migrate the users from a legacy Amazon Cognito user pool to the broker user pool. If your pool of user is not Amazon Cognito you'll have to adapt the source code to match with your system APIs.
Linking the Trigger:
To use the user migration that is labeled amplifyIdentityBrokerMigration
, the following setting needs to be enable
-
In the AWS console go to Amazon Cognito -> User Pool -> _brokeruserpool
-
On the left side menu navigate to Triggers
- In the User Migration click the dropdown list and select Lambda function, if you are using the pre-built one with this project it should be label
amplifyIdentityBrokerMigration-YourENV
Important: Your app sends the username and password to Amazon Cognito. If your app has a native sign-in UI and uses the Amazon Cognito Identity Provider SDK, your app must use the USER_PASSWORD_AUTH flow, in which the SDK sends the password to the server (your app must not use the default USER_SRP_AUTH flow since the SDK does not send the password to the server in the SRP authentication flow). The USER_PASSWORD_AUTH flow is enabled by setting AuthenticationDetails.authenticationType to "USER_PASSWORD". Switch Authentication Flows
If you like to set a migration flow for a specific environment, follow the these steps:
-
After your calling your imports in src/App.js of your react frontend, the use the following example.
Example:
Amplify.configure({...awsconfig, Auth: { // OPTIONAL - Manually set the authentication flow type. Default is 'USER_SRP_AUTH' authenticationFlowType: Config.authenticationFlowType !== undefined ? Config.authenticationFlowType : "USER_SRP_AUTH", }, });
This will detect if your authenticationFlowType have been set or not yet, if the authenticationFlowType has not been set then USER_SRP_AUTH will be the assigned flow.
-
Lastly we need to set the "USER_PASSWORD" flow to the desired environment, navigate to config-overrides.js in the root folder and set code with the following example.
Example:
case "Your-ENV": localConfig = { // This is added to any ENV that want to use User-Migration, the authenication flow type need to be set to USER_PASSWORD_AUTH from default(USER_SRP_AUTH) "authenticationFlowType": "USER_PASSWORD_AUTH", }; break;
This will set your specific environment to USER_PASSWORD_AUTH.
Important note: the stack deletion will not delete all the resources to prevent accidental data loss. Especially, the UserPool won't be deleted by a stack deletion. If you really want to delete the user pool do the Step2 after the Step1.
To delete the broker, you have to run the following command:
amplify delete
Or if you have multiple environments in your amplify/team-provider-info.json you will run multiple time commands like:
amplify env remove <name-of-your-env>
Note: You cannot delete an environment currently checkout, you'll have to switch env before with amplify env checkout <my-other-env>
. At anytime you can see the list of env by typing amplify env list
Possible cause of failure:
- S3 bucket not empty: To solve this, in the AWS console, go to Amazon S3, open the S3 bucket that fail to delete, check all items and click delete. Then redo the stack deletion (using the AWS Amplify CLI or AWS CloudFormation)
Alternative method: AWS Cloudformation
Alternatively of using the AWS Amplify CLI is to go to AWS CloudFormation in the region where you have created the environment and deleting the root stack. This ensures that all the resources created by that stack are removed.
AWS Amplify console
If you deployed your environment through the AWS Amplify console, then you should delete it from the AWS Amplify console.
WARNING: Doing this will delete all your user identities and credentials. There is no way to restore this after (the AWS support can't do it neither). Make sure you know what you are doing before proceeding.
On the AWS Console, go to Amazon Cognito service page, then go to User Pool, select the user pool you want to delete anc click on Delete pool button at the top right corner: