Custom auth flow

You are currently viewing the AWS SDK for Mobile documentation which is a collection of low-level libraries. Use the Amplify libraries for all new app development. Learn more

You can view the Mobile SDK API reference here.

Amazon Cognito User Pools supports customizing the authentication flow to enable custom challenge types. These challenge types may include CAPTCHAs or dynamic challenge questions. To define your challenges you need to implement three Lambda triggers.

For more information about working with Lambda Triggers for custom authentication challenges visit Amazon Cognito Developer Documentation.

Custom Authentication in Amplify

To enable a custom authentication flow update your awsconfiguration.json file and set authenticationFlowType to CUSTOM_AUTH.

1{
2  "CognitoUserPool": {
3    "Default": {
4      "PoolId": "XX-XXXX-X_abcd1234",
5      "AppClientId": "XXXXXXXX",
6      "Region": "XX-XXXX-X"
7    }
8  },
9  "Auth": {
10    "Default": {
11      "authenticationFlowType": "CUSTOM_AUTH"
12    }
13  }
14}

In your app code call signIn with a dummy password. Custom challenges need to be answered using the confirmSignIn method:

1AWSMobileClient.default().signIn(
2  username: username,
3  password: "dummyPassword"
4) { (signInResult, error) in
5    if let signInResult = signInResult {
6        if (signInResult.signInState == .customChallenge) {
7            // Retrieve challenge details
8        }
9    }
10}

Get the challenge details from the user and then call confirmSignIn

1AWSMobileClient.default().confirmSignIn(
2  challengeResponse: "<Challenge Response>",
3  completionHandler: { (signInResult, error) in
4    if let error = error  {
5        print("\(error.localizedDescription)")
6    } else if let signInResult = signInResult {
7        switch (signInResult.signInState) {
8        case .signedIn:
9            print("User is signed in.")
10        default:
11            print("\(signInResult.signInState.rawValue)")
12        }
13    }
14  }
15)

Lambda Trigger Setup

The Amplify CLI can be used to generate triggers required by a custom authentication flow. See the CLI Documentation for details. The CLI will create a custom auth flow skeleton that you can manually edit.

More information on available triggers can be found in the Cognito documentation.

AWSMobileClient assumes the custom auth flow starts with username and password. If you want a passwordless authentication flow, modify your Define Auth Challenge Lambda trigger to bypass the initial username/password verification and proceed to the custom challenge:

1exports.handler = (event, context) => {
2  if (
3    event.request.session.length === 1 &&
4    event.request.session[0].challengeName === 'SRP_A'
5  ) {
6    event.response.issueTokens = false;
7    event.response.failAuthentication = false;
8    event.response.challengeName = 'CUSTOM_CHALLENGE';
9  } else if (
10    event.request.session.length === 2 &&
11    event.request.session[1].challengeName === 'CUSTOM_CHALLENGE' &&
12    event.request.session[1].challengeResult === true
13  ) {
14    event.response.issueTokens = true;
15    event.response.failAuthentication = false;
16  } else {
17    event.response.issueTokens = false;
18    event.response.failAuthentication = true;
19  }
20  context.done(null, event);
21};