Adding and managing SAML
identity providers in a user pool
After you configure your identity provider to work with Amazon Cognito, you can add it to
your user pools and app clients. The following procedures demonstrate how to create,
modify, and delete SAML providers in an Amazon Cognito user pool.
- AWS Management Console
-
You can use the AWS Management Console to create and delete SAML identity providers
(IdPs).
Before you create a SAML IdP, you must have the SAML metadata document
that you get from the third-party IdP. For instructions on how to get or
generate the required SAML metadata document, see Configuring your third-party SAML identity provider.
To configure a SAML 2.0 IdP in your user pool
-
Go to the Amazon Cognito
console. If prompted, enter your AWS
credentials.
-
Choose User Pools.
-
Choose an existing user pool from the list, or create a user pool.
-
Choose the Social and external providers
menu and then select Add an identity
provider.
-
Choose a SAML IdP.
-
Enter a Provider name. You can pass this
friendly name in an identity_provider request
parameter to the Authorize endpoint.
-
Enter Identifiers separated by commas. An
identifier tells Amazon Cognito it should check the email address a user
enters when they sign in, and then direct them to the provider
that corresponds to their domain.
-
Choose Add sign-out flow if you want
Amazon Cognito to send signed sign-out requests to your provider when a
user logs out. You must configure your SAML 2.0 IdP to send
sign-out responses to the
https://mydomain.us-east-1.amazoncognito.com/saml2/logout
endpoint that is created when you configure managed login. The
saml2/logout endpoint uses POST binding.
If this option is selected and your SAML IdP expects a
signed logout request, you must also provide your SAML IdP
with the signing certificate from your user pool.
The SAML IdP will process the signed logout request and
sign out your user from the Amazon Cognito session.
-
Choose your IdP-initiated SAML sign-in
configuration. As a security best practice, choose
Accept SP-initiated SAML assertions
only. If you have prepared your environment to
securely accept unsolicited SAML sign-in sessions, choose
Accept SP-initiated and IdP-initiated SAML
assertions. For more information, see SAML session initiation
in Amazon Cognito user pools.
-
Choose a Metadata document source. If
your IdP offers SAML metadata at a public URL, you can choose
Metadata document URL and enter that
public URL. Otherwise, choose Upload metadata
document and select a metadata file you
downloaded from your provider earlier.
We recommend that you enter a metadata document URL if
your provider has a public endpoint instead of uploading a
file. Amazon Cognito automatically refreshes metadata from the
metadata URL. Typically, metadata refresh happens every 6
hours or before the metadata expires, whichever is
earlier.
-
Map attributes between your SAML provider and your
user pool to map SAML provider attributes to the
user profile in your user pool. Include your user pool required
attributes in your attribute map.
For example, when you choose User pool
attribute
email, enter the SAML attribute name as it appears
in the SAML assertion from your IdP. If your IdP offers sample
SAML assertions, you can use these sample assertions to help you
to find the name. Some IdPs use simple names, such as
email, while others use names like the
following.
http://schemas.xmlsoap.org/ws/2005/05/identity/claims/emailaddress
-
Choose Create.
- API/CLI
-
Use the following commands to create and manage a SAML identity
provider (IdP).
To create an IdP and upload a metadata document
-
AWS CLI: aws cognito-idp
create-identity-provider
Example with metadata file: aws cognito-idp
create-identity-provider --user-pool-id
us-east-1_EXAMPLE
--provider-name=SAML_provider_1
--provider-type SAML --provider-details file:///details.json
--attribute-mapping
email=http://schemas.xmlsoap.org/ws/2005/05/identity/claims/emailaddress
Where details.json contains:
"ProviderDetails": {
"MetadataFile": "<SAML metadata XML>",
"IDPSignout" : "true",
"RequestSigningAlgorithm" : "rsa-sha256",
"EncryptedResponses" : "true",
"IDPInit" : "true"
}
If the <SAML metadata
XML> contains any instances of the
character ", you must add \ as an
escape character: \".
Example with metadata URL: aws cognito-idp
create-identity-provider --user-pool-id
us-east-1_EXAMPLE
--provider-name=SAML_provider_1
--provider-type SAML --provider-details
MetadataURL=https://myidp.example.com/sso/saml/metadata
--attribute-mapping
email=http://schemas.xmlsoap.org/ws/2005/05/identity/claims/emailaddress
-
AWS API: CreateIdentityProvider
To upload a new metadata document for an IdP
-
AWS CLI: aws cognito-idp
update-identity-provider
Example with metadata file: aws cognito-idp
update-identity-provider --user-pool-id
us-east-1_EXAMPLE
--provider-name=SAML_provider_1
--provider-details file:///details.json --attribute-mapping
email=http://schemas.xmlsoap.org/ws/2005/05/identity/claims/emailaddress
Where details.json contains:
"ProviderDetails": {
"MetadataFile": "<SAML metadata XML>",
"IDPSignout" : "true",
"RequestSigningAlgorithm" : "rsa-sha256",
"EncryptedResponses" : "true",
"IDPInit" : "true"
}
If the <SAML metadata
XML> contains any instances of the
character ", you must add \ as an
escape character: \".
Example with metadata URL: aws cognito-idp
update-identity-provider --user-pool-id
us-east-1_EXAMPLE
--provider-name=SAML_provider_1
--provider-details
MetadataURL=https://myidp.example.com/sso/saml/metadata
--attribute-mapping
email=http://schemas.xmlsoap.org/ws/2005/05/identity/claims/emailaddress
-
AWS API: UpdateIdentityProvider
To get information about a specific IdP
-
AWS CLI: aws cognito-idp
describe-identity-provider
aws cognito-idp describe-identity-provider
--user-pool-id us-east-1_EXAMPLE
--provider-name=SAML_provider_1
-
AWS API: DescribeIdentityProvider
To list information about all IdPs
-
AWS CLI: aws cognito-idp
list-identity-providers
Example: aws cognito-idp list-identity-providers
--user-pool-id us-east-1_EXAMPLE
--max-results 3
-
AWS API: ListIdentityProviders
To delete an IdP
-
AWS CLI: aws cognito-idp
delete-identity-provider
aws cognito-idp delete-identity-provider --user-pool-id
us-east-1_EXAMPLE
--provider-name=SAML_provider_1
-
AWS API: DeleteIdentityProvider
To set up the SAML IdP to add a user pool as a relying party
-
The user pools service provider URN is:
urn:amazon:cognito:sp:us-east-1_EXAMPLE.
Amazon Cognito requires an audience restriction value that matches this URN in the
SAML response. Configure your IdP to use the following POST binding endpoint
for the IdP-to-SP response message.
https://mydomain.us-east-1.amazoncognito.com/saml2/idpresponse
-
Your SAML IdP must populate NameID and any required
attributes for your user pool in the SAML assertion. NameID is
used for uniquely identifying your SAML federated user in the user pool.
Your IdP must pass each user’s SAML name ID in a consistent, case-sensitive
format. Any variation in the value of a user's name ID creates a new user
profile.
To provide a signing certificate to your SAML 2.0 IDP
-
To download a copy of the the public key from Amazon Cognito that your IdP can use
to validate SAML logout requests, choose the Social and external
providers menu of your user pool, select your IdP, and under
View signing certificate, select Download
as .crt.
You can delete any SAML provider you have set up in your user pool with the Amazon Cognito
console.
To delete a SAML provider
-
Sign in to the Amazon Cognito
console.
-
In the navigation pane, choose User Pools, and choose
the user pool you want to edit.
-
Choose the Social and external providers menu.
-
Select the radio button next to the SAML IdPs you wish to delete.
-
When you are prompted to Delete identity provider,
enter the name of the SAML provider to confirm deletion, and then choose
Delete.
