Under the hood

Authentication is a process to validate who you are (abbreviated as AuthN). The system which does this validation is referred to as an Identity Provider or IdP. This can be your own self-hosted IdP or a cloud service. Oftentimes, this IdP is a social provider such as Facebook, Google, Amazon, or Sign in with Apple.

Authorization is the process of validating what you can access (abbreviated as AuthZ). This is sometimes done by looking at tokens with custom logic, predefined rules, or signed requests with policies.

Authentication with AWS

In the Amplify ecosystem, the most common Authentication method is either using Amazon Cognito User Pools independently or with a social provider to validate the identity of the user (known as Federation).

Amazon Cognito User Pools is a directory service to handle user registration, authentication, and account recovery. Amazon Cognito Federated Identities or Identity Pools on the other hand, is a way to authorize your users to use AWS services.

Amplify interfaces with User Pools to store your user information, including federation with other OpenID providers like Facebook & Google, and it leverages Federated Identities to manage user access to AWS Resources, for example allowing a user to upload a file (to an S3 bucket). The Amplify CLI automates the access control policies for these AWS resources as well as provides fine grained access controls via GraphQL for protecting data in your APIs.

Authorization is often done in one of two ways:

1. Clients pass the tokens to the backend that perform custom logic to allow or deny actions
2. Clients sign the requests and the backend validates the signature, allowing or denying actions depending on predefined policy. The predefined rules are known as IAM policies and automatically configured by the Amplify CLI.

The first mode is a common authorization method for REST or GraphQL APIs, while the second mode is necessary for interfacing with AWS services such as S3, Pinpoint, and others.

Sign-up and sign-in

For many apps, user sign-up and sign-in is all that is needed. Once authenticated the app can talk to an API to access and mutate data. In this case, you can simply create a User Pool by running amplify add auth using the Amplify CLI and selecting the default setup. In your application you can use Amplify.Auth.signUp and Amplify.Auth.signIn (or an Amplify UI component) to complete this process and retrieve tokens. The Amplify client will refresh the tokens calling Amplify.Auth.fetchAuthSession if they are no longer valid and Amplify will handle the rest - retrieving, sending, and refreshing tokens as needed.

Social Provider Federation

Many apps also support login with social providers such as Facebook, Google Sign-In, Login With Amazon, or Sign in with Apple. The preferred way to do this is via an OAuth redirect which lets users login using their social media account and a corresponding user is created in User Pools. With this design you do not need to include an SDK for the social provider in your app. Set this up by running amplify add auth and selecting the social provider option. Upon completion you can use Amplify.Auth.signInWithWebUI() in your application to show a pre-built "Hosted UI". Or pass in a social provider name (e.g. Amplify.Auth.signInWithSocialWebUI(AuthProvider.facebook()) to interface directly with that provider's web UI.

Accessing AWS services

Some apps need to use AWS services which require signing requests. Examples of this would be storing images or videos on S3, or sending analytics to Pinpoint or Kinesis. Amplify automatically signs requests with short term credentials from a Cognito Identity Pool which automatically expire, rotate, and refresh by the Amplify client libraries.

Credential handling

Amplify Swift library securely handles credentials and user identity information. You do not need to store, refresh, or delete credentials yourself. Instead, Amplify Swift library handles these operations using platform capabilities such as ASWebAuthenticationSession for web-based OAuth flows, and Keychain Services for storing and retrieving sensitive information. Only the host app (or defined app group) can access values that Amplify Swift library stores, and Amplify Swift library also clears credentials if it detects a configuration change such as a new Cognito UserPool or Cognito Identity Pool.

You can retrieve stored credentials by invoking fetchAuthSession API, which is the same API that other Amplify Swift library categories use to retrieve credentials for making calls to backend services like AWS AppSync, Amazon Pinpoint, and Amazon Simple Storage Service (Amazon S3). That API validates stored credentials and returns them if valid. If the credentials are not valid, Amplify Swift library will use the stored refresh token to refresh the credentials and return them. If the refresh token is not valid, Amplify Swift library will return a session expired error.