SAML identity providers (identity pools)
Amazon Cognito supports authentication with identity providers (IdPs) through Security Assertion Markup Language 2.0 (SAML 2.0). You can use an IdP that supports SAML with Amazon Cognito to provide a simple onboarding flow for your users. Your SAML-supporting IdP specifies the IAM roles that your users can assume. This way, different users can receive different sets of permissions.
Configuring your identity pool for a SAML IdP
The following steps describe how to configure your identity pool to use a SAML-based IdP.
Note
Before you configure your identity pool to support a SAML provider, first configure
the SAML IdP in the IAM console
Configuring your SAML IdP
After you create the SAML provider, configure your SAML IdP to add relying party trust
between your IdP and AWS. With many IdPs, you can specify a URL that the IdP can use to
read relying party information and certificates from an XML document. For AWS, you can use
https://signin.aws.amazon.com/static/saml-metadata.xml
Customizing your user role with SAML
When you use SAML with Amazon Cognito Identity, you can customize the role for the end user. Amazon Cognito only
supports the enhanced flow with the SAML-based
IdP. You don't need to specify an authenticated or unauthenticated role for the identity
pool to use a SAML-based IdP. The https://aws.amazon.com/SAML/Attributes/Role
claim attribute specifies one or more pairs of comma -delimited role and provider ARN. These
are the roles that the user can assume. You can configure the SAML IdP to populate the role
attributes based on the user attribute information available from the IdP. If you receive
multiple roles in the SAML assertion, populate the optional customRoleArn
parameter when you call getCredentialsForIdentity
. The user assumes this
customRoleArn
if the role matches one in the claim in the SAML
assertion.
Authenticating users with a SAML IdP
To federate with the SAML-based IdP, determine the URL where the user initiates the
login. AWS federation uses IdP-initiated login. In AD FS 2.0, the URL takes the form of
https://
.<fqdn>
/adfs/ls/IdpInitiatedSignOn.aspx?loginToRp=urn:amazon:webservices
To add support for your SAML IdP in Amazon Cognito, first authenticate users with your SAML identity provider from your iOS or Android application. The code that you use to integrate and authenticate with the SAML IdP is specific to SAML providers. After you authenticate your user, you can use Amazon Cognito APIs to provide the resulting SAML assertion to Amazon Cognito Identity .
You can't repeat, or replay, a SAML assertion in the
Logins
map of your identity pool API request. A replayed SAML assertion has
an assertion ID that duplicates the ID of an earlier API request. API operations that can
accept a SAML assertion in the Logins
map include GetId, GetCredentialsForIdentity, GetOpenIdToken,
and GetOpenIDTokenForDeveloperIdentity. You can replay a SAML assertion ID one time
per API request in an identity pool authentication flow. For example, you can supply the
same SAML assertion in a GetId
request and a subsequent
GetCredentialsForIdentity
request, but not in a second GetId
request.
Android
If you use the Android SDK, you can populate the logins map with the SAML assertion as follows.
Map logins = new HashMap(); logins.put("arn:aws:iam::aws account id:saml-provider/name", "base64 encoded assertion response"); // Now this should be set to CognitoCachingCredentialsProvider object. CognitoCachingCredentialsProvider credentialsProvider = new CognitoCachingCredentialsProvider(context, identity pool id, region); credentialsProvider.setLogins(logins); // If SAML assertion contains multiple roles, resolve the role by setting the custom role credentialsProvider.setCustomRoleArn("arn:aws:iam::aws account id:role/customRoleName"); // This should trigger a call to the Amazon Cognito service to get the credentials. credentialsProvider.getCredentials();
iOS
If you are using the iOS SDK, you can provide the SAML assertion in
AWSIdentityProviderManager
as follows.
- (AWSTask<NSDictionary<NSString*,NSString*> *> *) logins { //this is hardcoded for simplicity, normally you would asynchronously go to your SAML provider //get the assertion and return the logins map using a AWSTaskCompletionSource return [AWSTask taskWithResult:@{@"arn:aws:iam::aws account id:saml-provider/name":@"base64 encoded assertion response"}]; } // If SAML assertion contains multiple roles, resolve the role by setting the custom role. // Implementing this is optional if there is only one role. - (NSString *)customRoleArn { return @"arn:aws:iam::accountId:role/customRoleName"; }