Menu
Amazon Cognito
Developer Guide (Version Last Updated: 08/26/2017)

Creating SAML Identity Providers for Your User Pool

A SAML 2.0 identity provider is an entity in Amazon Cognito that describes an identity provider (IdP) that supports the SAML 2.0 standard. You can create and manage a SAML IdP in the AWS Management Console, or with Amazon Cognito CLI or Amazon Cognito API calls.

On the Identity provider tab, you can create SAML 2.0 identity providers (IdP) directly for use with your user pool.

Note

SAML federation support in Amazon Cognito User Pools is independent of Amazon Cognito Federated Identities.

Amazon Cognito User Pools acts as a service provider (SP) on behalf of your application. Amazon Cognito supports SP-initiated single sign-on (SSO) as described in section 5.1.2 of the SAML V2.0 Technical Overview. The redirect endpoint for the POST binding is https://<domain_prefix>.auth.<region>.amazoncognito.com/saml2/idpresponse.

Note

Any SAML identity providers that you created in a user pool during the public beta before August 10, 2017 have redirect URLs of https://<yourDomainPrefix>.auth.<region>.amazoncognito.com/login/redirect. If you have one of these SAML identity providers from the public beta in your user pool, you must either:

  • Replace it with a new one that uses the new redirect URL.

  • Update the configuration in your SAML identity provider to accept both the old and new redirect URLs.

All SAML identity providers in Amazon Cognito will switch to the new URLs, and the old ones will stop working on October 31, 2017.

SAML IdP Authentication Flow

Developers can easily integrate the SAML-based IdPs of their customers into their apps.

  1. The app starts the sign-up and sign-in process by directing the user to the UI hosted by AWS. A mobile app uses a web view to show the pages hosted by AWS.

  2. Typically Amazon Cognito User Pools determines the identity provider for the user from the user's email address.

    Alternatively, if the app gathered information before directing the user to Amazon Cognito User Pools, it provides that information to Amazon Cognito through a query parameter.

  3. The user is redirected to the identity provider.

  4. The IdP authenticates the user if necessary. If the IdP recognizes that the user has an active session, the IdP skips the authentication to provide a single sign-in (SSO) experience.

  5. The IdP POSTs the SAML assertion to Amazon Cognito User Pools.

  6. The user's profile can be created or updated in the AWS Management Console, or the Amazon Cognito CLI or API.

  7. After verifying the SAML assertion and collecting the user attributes (claims) from the assertion, Amazon Cognito User Pools returns OIDC tokens to the app for the now signed-in user.

The following diagram shows the authentication flow for this process:


                    Authentication flow diagram for using SAML IdP with Amazon Cognito user
                        pool.

When a user authenticates, the user pool provides ID, access, and refresh tokens. The ID token is a standard OIDC token for identity management, and the access token is a standard OAuth 2.0 token. The ID and access tokens expire after one hour, but your app can use the refresh token to get new tokens without having the user re-authenticate. As a developer, you can choose the expiration time of refresh tokens, and therefore how frequently users need to reauthenticate. If the user has authenticated through an external IdP (i.e., they are a federated user), your app still uses the Amazon Cognito tokens with the refresh token to determine how long until the user reauthenticates, regardless of when the external IdP's token expires. The user pool automatically uses the refresh token to get new ID and access tokens when they expire. If the refresh token has also expired, the server automatically initiates authentication through the pages in your app that are hosted by AWS.

Creating and Managing a SAML Identity Provider (AWS Management Console)

You can use the AWS Management Console to create and delete SAML identity providers.

Before you create a SAML identity provider, you need the SAML metadata document that you get from the third-party identity provider (IdP). For instructions on how to get or generate the required SAML metadata document, see Integrating Third-Party SAML Identity Providers with Amazon Cognito User Pools.

You need to choose names for your SAML providers. The string format is [\w\s+=.@-]+ and can be up to 40 characters long.

You can also optionally choose identifiers for your SAML providers. An identifier uniquely resolves to an identity provider associated with your user pool. Typically each identifier corresponds to a domain that belongs to the company that the IdP represents. For a multitenant app that can be used by different companies, identifiers can be used to redirect users to the correct IdP. Since there can be multiple domains owned by the same company, you can provide multiple identifiers.

You can associate up to 50 identifiers with each SAML provider. Identifiers must be unique across the identity provider.

For example, suppose that you built an app that can be used by employees of two different companies, A and B. Company A owns domainA.com and domainA.co.uk; Company B owns domainB.com. Suppose further that you set up two IdPs, one for each company:

  • For IdP A, you can define identifiers DomainA.com and DomainA.co.uk.

  • For IdP B, you can define identifier DomainB.com.

In your application, you can prompt users to enter their email addresses. By deriving the domain from the email address, you can redirect the user to the correct IdP by providing the domain in the IdPIdentifier in the call to the /authorize endpoint. For example, if a user enters bob@domain1.co.uk, the user is redirected to IdP A.

The sign-in page hosted by Amazon Cognito parses the email address automatically to derive the information. It parses the email domain from email and uses it as IdPIdentifier when calls the /authorize endpoint.

  • If you have multiple SAML IdPs and you specify an IdPIdentifier value for any one of them, you will see a box to enter an email address on the hosted page.

  • If you have multiple IdPs, and you do not specify an IdPIdentifier value for any of them, the hosted page will show a list of IdPs.

If you're building your own UI, you should parse the domain name so that it matches the IdPIdentifiers that are provided during the IdP setup. For more information about IdP setup, see Specifying Identity Providers for Your User Pool.

To create a SAML provider

  1. Sign in to the Amazon Cognito console.

  2. In the navigation pane, choose Manage your User Pools, and choose the user pool you want to edit.

  3. Choose Identity providers from the Federation tab.

  4. Choose Corporate ID via SAML.

  5. To attach your own custom metadata document, choose Select file. Or enter a metadata document endpoint URL. The metadata document must be a valid XML file.

    Note

    We recommend that you provide the endpoint URL if it is a public endpoint, rather than uploading a file, because this allows Amazon Cognito to refresh the metadata automatically. Typically metadata refresh happens every 6 hours or before the metadata expires, whichever is earlier.

  6. Enter your SAML Provider name and any Identifiers that you want. The provider name is required; the identifiers are optional.

  7. Choose Create provider.

Note

If you see InvalidParameterException while creating a SAML identity provider with an HTTPS metadata endpoint URL, for example, "Error retrieving metadata from <metadata endpoint>," make sure that the metadata endpoint has SSL correctly set up and that there is a valid SSL certificate associated with it.

To set up the SAML IdP to add Amazon Cognito User Pools as a relying party

  • The Amazon Cognito User Pools service provider URN is: urn:amazon:cognito:sp:<user_pool_id>. Amazon Cognito User Pools issues the AuthnRequest to SAML IdP to issue a SAML assertion with audience restriction to this URN. Your IdP uses the following POST binding endpoint for the IdP-to-SP response message: https://<domain_prefix>.auth.<region>.amazoncognito.com/saml2/idpresponse.

  • Make sure your SAML IdP populates 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. Use persistent SAML Name ID format.

To delete a SAML provider

  1. Sign in to the Amazon Cognito console.

  2. In the navigation pane, choose Manage your User Pools, and choose the user pool you want to edit.

  3. Choose Identity providers from the Federation tab.

  4. Choose Corporate ID via SAML to display the SAML identity providers.

  5. Select the check box next to the provider to be deleted.

  6. Choose Delete provider.

Creating and Managing a SAML Identity Provider (AWS CLI and AWS API)

Use the following commands to create and manage a SAML provider.

To create an identity provider 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 <user_pool_id> --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:

    { 
        "MetadataFile": "<SAML metadata XML>"
    }

    Note

    If the <SAML metadata XML> contains any quotations ("), they must be escaped (\").

    Example with metadata URL: aws cognito-idp create-identity-provider --user-pool-id <user_pool_id> --provider-name=SAML_provider_1 --provider-type SAML --provider-details MetadataURL=<metadata_url> --attribute-mapping email=http://schemas.xmlsoap.org/ws/2005/05/identity/claims/emailaddress

  • AWS API: CreateIdentityProvider

To upload a new metadata document for an identity provider

  • AWS CLI: aws cognito-idp update-identity-provider

    Example with metadata file: aws cognito-idp update-identity-provider --user-pool-id <user_pool_id> --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:

    { 
        "MetadataFile": "<SAML metadata XML>"
    }

    Note

    If the <SAML metadata XML> contains any quotations ("), they must be escaped (\").

    Example with metadata URL: aws cognito-idp update-identity-provider --user-pool-id <user_pool_id> --provider-name=SAML_provider_1 --provider-details MetadataURL=<metadata_url> --attribute-mapping email=http://schemas.xmlsoap.org/ws/2005/05/identity/claims/emailaddress

  • AWS API: UpdateIdentityProvider

To get information about a specific identity provider

  • AWS CLI: aws cognito-idp describe-identity-provider

    aws cognito-idp describe-identity-provider --user-pool-id <user_pool_id> --provider-name=SAML_provider_1

  • AWS API: DescribeIdentityProvider

To list information about all identity providers

  • AWS CLI: aws cognito-idp list-identity-providers

    Example: aws cognito-idp list-identity-providers --user-pool-id <user_pool_id> --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 <user_pool_id> --provider-name=SAML_provider_1

  • AWS API: DeleteIdentityProvider