Advanced workflows

Subscribing Events

You can take specific actions when users sign-in or sign-out by subscribing authentication events in your app. Please see our Hub Module Developer Guide for more information.

Identity Pool Federation

Imagine that you are creating a mobile app that accesses AWS resources, such as a game that runs on a mobile device and stores player and score information using Amazon S3 and DynamoDB.

When you write such an app, you make requests to AWS services that must be signed with an AWS access key. However, we strongly recommend that you do not embed or distribute long-term AWS credentials with apps that a user downloads to a device, even in an encrypted store. Instead, build your app so that it requests temporary AWS security credentials dynamically when needed using web identity federation. The supplied temporary credentials map to an AWS role that has only the permissions needed to perform the tasks required by the mobile app.

With web identity federation, you don't need to create custom sign-in code or manage your own user identities. Instead, users of your app can sign in using a well-known external identity provider (IdP), such as Login with Amazon, Facebook, Google, or any other OpenID Connect (OIDC)-compatible IdP. They can receive an authentication token, and then exchange that token for temporary security credentials in AWS that map to an IAM role with permissions to use the resources in your AWS account. Using an IdP helps you keep your AWS account secure, because you don't have to embed and distribute long-term security credentials with your application.

You can use federateToIdentityPool to get AWS credentials directly from Cognito Federated Identities and not use User Pool federation. If you have logged in with Auth.signIn you can not call federateToIdentityPool as Amplify will perform this federation automatically for you in the background. In general, you should only call Auth.federateToIdentityPool when using OAuth flows.

You can use the escape hatch API federateToIdentityPool with a valid token from other social providers.

func federateToIdentityPools() async throws {
    guard let authCognitoPlugin = try Amplify.Auth.getPlugin(
        for: "awsCognitoAuthPlugin") as? AWSCognitoAuthPlugin else {
        fatalError("Unable to get the Auth plugin")
    }
    do {
        let result = try await authCognitoPlugin.federateToIdentityPool(
            withProviderToken: "YOUR_TOKEN", for: .facebook)
        print("Federation successful with result: \(result)")
    } catch {
        print("Failed to federate to identity pools with error: \(error)")
    }
}

Retrieve Session

After federated login, you can retrieve session using the Auth.fetchAuthSession API.

Token Refresh

By default, Amplify will NOT automatically refresh the tokens from the federated providers. You will need to handle the token refresh logic and provide the new token to the federateToIdentityPool API.

Clear Session

You can clear the federated session using the clearFederationToIdentityPool API.

func clearFederationToIdentityPools() async throws {
    guard let authCognitoPlugin = try Amplify.Auth.getPlugin(
        for: "awsCognitoAuthPlugin") as? AWSCognitoAuthPlugin else {
        fatalError("Unable to get the Auth plugin")
    }
    do {
        try await authCognitoPlugin.clearFederationToIdentityPool()
        print("Federation cleared successfully")
    } catch {
        print("Clear federation failed with error: \(error)")
    }
}

Provide Custom Identity Id

You can provide a custom identity id to the federateToIdentityPool API. This is useful when you want to use the same identity id across multiple devices.

func federateToIdentityPoolsUsingCustomIdentityId() async throws {
    guard let authCognitoPlugin = try Amplify.Auth.getPlugin(
        for: "awsCognitoAuthPlugin") as? AWSCognitoAuthPlugin else {
        fatalError("Unable to get the Auth plugin")
    }
    do {
        let identityId = "YOUR_CUSTOM_IDENTITY_ID"
        let result = try await authCognitoPlugin.federateToIdentityPool(
            withProviderToken: "YOUR_TOKEN",
            for: .facebook,
            options: .init(developerProvidedIdentityID: identityId))
        print("Federation successful with result: \(result)")
    } catch {
        print("Failed to federate to identity pools with error: \(error)")
    }
}

Keychain Sharing

Migrating to a Shared Keychain

To use a shared keychain:

1. In Xcode, go to Project Settings → Your Target → Signing & Capabilities
2. Select +Capability
3. Add Keychain Sharing capability
4. Add a keychain group
5. Repeat for all apps for which you want to share auth state, adding the same keychain group for all of them

To move to the shared keychain using this new keychain access group, specify the accessGroup parameter when instantiating the AWSCognitoAuthPlugin. If a user is currently signed in, they will be signed out when first using the access group:

let accessGroup = AccessGroup(name: "\(teamID)com.example.sharedItems")
let secureStoragePreferences = AWSCognitoSecureStoragePreferences(
  accessGroup: accessGroup)
try Amplify.add(
  plugin: AWSCognitoAuthPlugin(
    secureStoragePreferences: secureStoragePreferences))
try Amplify.configure()

If you would prefer the user session to be migrated (which will allow the user to continue to be signed in), then specify the migrateKeychainItemsOfUserSession boolean in the AccessGroup to be true like so:

let accessGroup = AccessGroup(
  name: "\(teamID)com.example.sharedItems",
  migrateKeychainItemsOfUserSession: true)
let secureStoragePreferences = AWSCognitoSecureStoragePreferences(
  accessGroup: accessGroup)
try Amplify.add(
  plugin: AWSCognitoAuthPlugin(
    secureStoragePreferences: secureStoragePreferences))
try Amplify.configure()

Sign in a user with any sign-in method within one app that uses this access group. After reloading another app that uses this access group, the user will be signed in. Likewise, signing out of one app will sign out the other app after reloading it.

Migrating to another Shared Keychain

To move to a different access group, update the name parameter of the AccessGroup to be the new access group. Set migrateKeychainItemsOfUserSession to true to migrate an existing user session under the previously used access group.

Migrating from a Shared Keychain

If you'd like to stop sharing state between this app and other apps, you can set the access group to be AccessGroup.none or AccessGroup.none(migrateKeychainItemsOfUserSession: true) if you'd like the session to be migrated.

Retrieving Team ID

First, ensure your Info.plist has the AppIdentifierPrefix key:

<?xml version="1.0" encoding="UTF-8"?>
<!DOCTYPE plist PUBLIC "-//Apple//DTD PLIST 1.0//EN" "http://www.apple.com/DTDs/PropertyList-1.0.dtd">
<plist version="1.0">
<dict>
    <key>AppIdentifierPrefix</key>
    <string>$(AppIdentifierPrefix)</string>
</dict>
</plist>

Then, you can retrieve the team ID from your Info.plist:

guard let teamID = Bundle.main.infoDictionary?["AppIdentifierPrefix"] as? String else {
    fatalError("AppIdentifierPrefix key not found in Info.plist")
}