Programming the Amazon Rekognition Face Liveness APIs

To use the Amazon Rekognition Face Liveness API, you must create a backend that carries out the following steps:

1. Call CreateFaceLivenessSession to initiate a Face Liveness session. When the CreateFaceLivenessSession operation is completed, the UI prompts the user to submit a video selfie. The AWS Amplify’s FaceLivenessDetector component then calls StartFaceLivenessSession to perform Liveness detection.

2. Call GetFaceLivenessSessionResults to return the detection results associated with a Face Liveness session.

3. Proceed to configure your React application to use the FaceLivenessDetector component by following the steps at the Amplify Liveness guide.

Before using Face Liveness, make sure that you have created an AWS Account, set up the AWS CLI and AWS SDKs, and set up AWS Amplify. You should also ensure the IAM policy for your backend API has permissions that cover the following: GetFaceLivenessSessionResults, and CreateFaceLivenessSession. See the Prerequisites section for more information.

Step 1: CreateFaceLivenessSession

CreateFaceLivenessSession API operation creates a Face Liveness session and returns a unique SessionId.

As part of the input for this operation, it is also possible to specify an Amazon S3 bucket location. This allows the storage of a reference image and audit images generated during the Face Liveness session. The Amazon S3 bucket must be located in the caller's AWS account and in the same region as the Face Liveness endpoint. Additionally, the S3 object keys are generated by the Face Liveness system.

It is also possible to provide an AuditImagesLimit, which is a number between 0 and 4. By default, it is set to 0. The number of images returned is best effort and based on the duration of the selfie-video.

Request Example

{
    "ClientRequestToken": "my_default_session",
    "Settings": {
        "OutputConfig": {
            "S3Bucket": "s3bucket",
            "S3KeyPrefix": "s3prefix"
        },
        "AuditImagesLimit": 1
    }
}
            

Response Example

{
    {"SessionId": "0f959dbb-37cc-45d8-a08d-dc42cce85fa8"}
}

Step 2: StartFaceLivenessSession

When the CreateFaceLivenessSession API operation finishes, the AWS Amplify component performs the StartFaceLivenessSession API operation. The user is prompted to capture a video selfie. For a successful check, the user must position their face within the onscreen oval while maintaining good lighting. For more information, see Recommendations for Usage of Face Liveness.

This API operation requires the video captured during the Face Liveness session, the sessionId obtained from the CreateFaceLivenessSession API operation, and an onAnalysisComplete callback. The callback can be used to signal the backend to call the GetFaceLivenessSessionResults API operation, which returns a confidence score, reference, and audit images.

Note that this step is performed by the AWS Amplify FaceLivenessDetector component on the client application. You do not need to do additional setup to call StartFaceLivenessSession.

Step 3: GetFaceLivenessSessionResults

The GetFaceLivenessSessionResults API operation retrieves the results of a specific Face Liveness session. It requires the sessionId as input and returns the corresponding Face Liveness confidence score. It also provides a reference image that includes a face bounding box, and audit images that also contain face bounding boxes. The Face Liveness confidence score ranges from 0–100.

Request Example

{"SessionId": "0f959dbb-37cc-45d8-a08d-dc42cce85fa8"}
            

Response Example

{
    "SessionId": "0f959dbb-37cc-45d8-a08d-dc42cce85fa8",
    "Confidence": 98.9735,
    "ReferenceImage": {
        "S3Object": { 
            "Bucket": "s3-bucket-name",
            "Name": "file-name",
        },
        "BoundingBox": { 
           "Height": 0.4943420886993408, 
            "Left": 0.8435328006744385, 
            "Top": 0.8435328006744385, 
            "Width": 0.9521094560623169}
    },
    "AuditImages": [{
        "S3Object": { 
            "Bucket": "s3-bucket-name",
            "Name": "audit-image-name",
        },
        "BoundingBox": { 
           "Width": 0.6399999856948853,
           "Height": 0.47999998927116394,
           "Left": 0.1644444465637207,
           "Top": 0.17666666209697723}
    }],
    "Status": "SUCCEEDED"
}
            

Step 4: Respond to results

After the Face Liveness session, compare the check's confidence score against the specified threshold. If the score is higher than the threshold, the user can go to the next screen or task. If the check fails, the user will be notified and prompted to try again.