Face Liveness

Use the Amplify Gen 1 CLI to automatically configure and manage your Cognito Identity and User Pool for you.

FaceLivenessDetector uses Amplify Auth by default to authorize users to perform the Face Liveness check. If you are using Amplify for the first time, follow the instructions for installing the Amplify CLI.

Set up a new Amplify project

$ amplify init
? Enter a name for the project reactliveness
? Enter a name for the environment dev
? Choose your default editor: Visual Studio Code
? Choose the type of app that you're building javascript
Please tell us about your project
? What javascript framework are you using react
? Source Directory Path:  src
? Distribution Directory Path: build
? Build Command:  npm run-script build
? Start Command: npm run-script start

Add the auth category

$ amplify add auth
 Do you want to use the default authentication and security configuration? Manual configuration
 
 Select the authentication/authorization services that you want to use: User Sign-Up, Sign-In, connected with AWS IAM controls (Enables per-user Storage features for images or other content, Analytics, and more)
 
 Provide a friendly name for your resource that will be used to label this category in the project: <default>
 
 Enter a name for your identity pool. <default>
 
 Allow unauthenticated logins? (Provides scoped down permissions that you can control via AWS IAM) Yes
 
 <Choose defaults for the rest of the questions>   

Push to create the resources

$ amplify push
✔ Successfully pulled backend environment dev from the cloud.

Current Environment: dev

| Category | Resource name    | Operation | Provider plugin   |
| -------- | ---------------- | --------- | ----------------- |
| Auth     | reactlive••••••• | Create    | awscloudformation | 

If you have an existing Amplify backend, run amplify pull to sync your aws-exports.js with your cloud backend.

Once complete you should now have an aws-exports.js file in your src directory with your latest Amplify backend configuration.

Update IAM Role Permissions

Now that you have Amplify Auth setup, follow the steps below to create an inline policy to enable authenticated app users to access Rekognition.

1. Go to AWS IAM console → Roles

2. Select the newly created unauthRole for your project (amplify-<project_name>-<env_name>-<id>-unauthRole if using the Amplify CLI). Note that unauthRole should be used if you are not logging in, but if you are using an authenticator with your application, you will need to use authRole.

3. Choose Add Permissions, then select Create Inline Policy, then choose JSON and paste the following:

{
    "Version": "2012-10-17",
    "Statement": [
        {
            "Effect": "Allow",
            "Action": "rekognition:StartFaceLivenessSession",
            "Resource": "*"
        }
    ]
}

4. Choose Review Policy

5. Name the policy

6. Choose Create Policy

To use Amplify UI FaceLivenessDetector, you must also set up a backend to create the Face Liveness session and retrieve the session results. Follow the Amazon Rekognition Face Liveness developer guide to set up your backend.

If you previously had unmanaged resources that you want to manage with Amplify Gen 1 you can use the CLI to import your Cognito resources.

FaceLivenessDetector uses Amplify Auth by default to authorize users to perform the Face Liveness check. Follow the instructions for Amplify CLI (Import) to manage your Cognito resources with Amplify.

Once complete you should now have an aws-exports.js file in your src directory with your latest Amplify backend configuration.

Update IAM Role Permissions

Now that you have Amplify Auth setup, follow the steps below to create an inline policy to enable authenticated app users to access Rekognition.

1. Go to AWS IAM console → Roles

2. Select the newly created unauthRole for your project (amplify-<project_name>-<env_name>-<id>-unauthRole if using the Amplify CLI). Note that unauthRole should be used if you are not logging in, but if you are using an authenticator with your application, you will need to use authRole.

3. Choose Add Permissions, then select Create Inline Policy, then choose JSON and paste the following:

{
    "Version": "2012-10-17",
    "Statement": [
        {
            "Effect": "Allow",
            "Action": "rekognition:StartFaceLivenessSession",
            "Resource": "*"
        }
    ]
}

4. Choose Review Policy

5. Name the policy

6. Choose Create Policy

To use Amplify UI FaceLivenessDetector, you must also set up a backend to create the Face Liveness session and retrieve the session results. Follow the Amazon Rekognition Face Liveness developer guide to set up your backend.

Use this option if you already have a Cognito identity/user pools that you do not want to import to Amplify, or want to manage Cognito resources yourself or with a 3rd party resource management tool.

If you already have Cognito set up or do not want to use the Amplify Gen 1 CLI to generate Cognito resources, you can follow the documentation in the existing resources tab or check out the code snippet below.

If you are manually setting up an identity pool in the Cognito console you can follow this guide. When setting up the identity pool ensure that access to unauthenticated identities is enabled.

When initially configuring Amplify you can pass in the cognito region and an identity pool instead of using the Amplify generated aws-exports file.

import React from 'react';
import { ThemeProvider } from '@aws-amplify/ui-react';
import { Amplify } from 'aws-amplify';
import '@aws-amplify/ui-react/styles.css';
import awsexports from './aws-exports';

Amplify.configure({
   ...awsexports,
  "aws_cognito_region": "us-east-2", // (required) - Region where Amazon Cognito project was created
  "aws_cognito_identity_pool_id": "us-east-2:xxx-xxx-xxx-xxx-xxx", // (required) - the pool region should match the cognito region
});

export default function App() {
  return (
    <ThemeProvider>
    </ThemeProvider>
  );
}

Update IAM Role Permissions

Now that you have Amplify Auth setup, follow the steps below to create an inline policy to enable authenticated app users to access Rekognition.

1. Go to AWS IAM console → Roles

2. Select the newly created unauthRole for your project (amplify-<project_name>-<env_name>-<id>-unauthRole if using the Amplify CLI). Note that unauthRole should be used if you are not logging in, but if you are using an authenticator with your application, you will need to use authRole.

3. Choose Add Permissions, then select Create Inline Policy, then choose JSON and paste the following:

{
    "Version": "2012-10-17",
    "Statement": [
        {
            "Effect": "Allow",
            "Action": "rekognition:StartFaceLivenessSession",
            "Resource": "*"
        }
    ]
}

4. Choose Review Policy

5. Name the policy

6. Choose Create Policy

To use Amplify UI FaceLivenessDetector, you must also set up a backend to create the Face Liveness session and retrieve the session results. Follow the Amazon Rekognition Face Liveness developer guide to set up your backend.

Use this option if you want more control over the process of obtaining AWS credentials.

By default, FaceLivenessDetector uses Amplify Auth to authorize users to perform the Face Liveness check. You can use your own credentials provider to retrieve credentials from Amazon Cognito or assume a role with Amazon STS, for example:

import { FaceLivenessDetectorCore, AwsCredentialProvider } from '@aws-amplify/ui-react-liveness';
 
const credentialProvider: AwsCredentialProvider = async () => {
  // Fetch the credentials
}

return (
  <FaceLivenessDetectorCore
    sessionId={'<sessionId>'}
    region={'<region>'}
    onAnalysisComplete={() => {}}
    onError={onError}
    config={{ credentialProvider }}
  />
);

Note: The provided Credentials Provider's fetchAWSCredentials function is called once at the start of the liveness flow, with no token refresh.

Update IAM Role Permissions

Now that you have Amplify Auth setup, follow the steps below to create an inline policy to enable authenticated app users to access Rekognition.

1. Go to AWS IAM console → Roles

2. Select the newly created unauthRole for your project (amplify-<project_name>-<env_name>-<id>-unauthRole if using the Amplify CLI). Note that unauthRole should be used if you are not logging in, but if you are using an authenticator with your application, you will need to use authRole.

3. Choose Add Permissions, then select Create Inline Policy, then choose JSON and paste the following:

{
    "Version": "2012-10-17",
    "Statement": [
        {
            "Effect": "Allow",
            "Action": "rekognition:StartFaceLivenessSession",
            "Resource": "*"
        }
    ]
}

4. Choose Review Policy

5. Name the policy

6. Choose Create Policy

To use Amplify UI FaceLivenessDetector, you must also set up a backend to create the Face Liveness session and retrieve the session results. Follow the Amazon Rekognition Face Liveness developer guide to set up your backend.

import React from 'react';
import { FaceLivenessDetector } from '@aws-amplify/ui-react-liveness';
import { Loader, ThemeProvider } from '@aws-amplify/ui-react';

export function LivenessQuickStartReact() {
  const [loading, setLoading] = React.useState<boolean>(true);
  const [createLivenessApiData, setCreateLivenessApiData] = React.useState<{
    sessionId: string;
  } | null>(null);

  React.useEffect(() => {
    const fetchCreateLiveness: () => Promise<void> = async () => {
      /*
       * This should be replaced with a real call to your own backend API
       */
      await new Promise((r) => setTimeout(r, 2000));
      const mockResponse = { sessionId: 'mockSessionId' };
      const data = mockResponse;

      setCreateLivenessApiData(data);
      setLoading(false);
    };

    fetchCreateLiveness();
  }, []);

  const handleAnalysisComplete: () => Promise<void> = async () => {
    /*
     * This should be replaced with a real call to your own backend API
     */
    const response = await fetch(
      `/api/get?sessionId=${createLivenessApiData.sessionId}`
    );
    const data = await response.json();

    /*
     * Note: The isLive flag is not returned from the GetFaceLivenessSession API
     * This should be returned from your backend based on the score that you
     * get in response. Based on the return value of your API you can determine what to render next.
     * Any next steps from an authorization perspective should happen in your backend and you should not rely
     * on this value for any auth related decisions.
     */
    if (data.isLive) {
      console.log('User is live');
    } else {
      console.log('User is not live');
    }
  };

  return (
    <ThemeProvider>
      {loading ? (
        <Loader />
      ) : (
        <FaceLivenessDetector
          sessionId={createLivenessApiData.sessionId}
          region="us-east-1"
          onAnalysisComplete={handleAnalysisComplete}
          onError={(error) => {
            console.error(error);
          }}
        />
      )}
    </ThemeProvider>
  );
}