Manage User Authentication with Box Platform using Amazon Cognito

When building an app with Box Platform, one of the things you’ll need to do is to create and manage App Users. App Users are users of your app that can access features of Box Platform via your app’s interface. Authenticating and managing these users, however, can be complicated if you aren’t familiar with user authentication.

Luckily, there are several providers that let you easily add user authentication to your web and mobile apps, including Amazon Cognito. Cognito lets you easily add user sign-up and sign-in to your apps and offers features like email verification, multi-factor authentication, social identity authentication, and synchronization across devices to enable users to have a seamless experience across platforms.

Today, we’re excited to share a step-by-step tutorial to allow you to authenticate and manage Box App Users with Amazon Cognito using just a few lines of code. By following along the tutorial below, you’ll be able to setup user authentication for your Box app in minutes.

The Use Case

What we’re building today is a login page for App Users to log into Box via your app. Cognito will then handle the authentication and user pool management.

The overall architecture of authentication is simple. We’ll create a new App User in Box the first time a user logs into Cognito. Once that’s done, we’ll update the App User with the new user ID we just generated so we can keep track of it programatically. After that, your client application can call an API Gateway URL to perform a token exchange with Cognito user tokens and Box App User tokens. Box tokens expire roughly every hour, so you’ll need to generate a new token to keep making API calls for as long as your user is logged in to Cognito.

Getting Set Up

Before writing any code, you’ll need to set up a few things.

To build the integration, you’ll need:

1. An AWS account
2. A Box Developer account

Step 1: Create a Box application

First, you’ll need to create a Box application. You can also modify the configuration of your existing application. Your application will need to be authorized into your Box account and have the appropriate scopes and advanced features enabled.

You can see the exact steps here.

Step 2: Create Cognito user pool

Next, you’ll need to create a user pool in Amazon Cognito.

1. Log into the AWS Management Console and go to the Cognito console.
2. Click “Manage your User Pools”
3. Click “Create user pool”
4. Fill pool name as box-cognito-integration. Press the “Step through settings”
5. Click “Add a custom attribute”
6. Choose the String type. Give the attribute name as “box_appuser_id”. Press “Next step”.
7. Configure next steps based on the application needs.
8. Finally press “Create pool”.

Step 3: Register your app to access the Cognito user pool

1. Log into the AWS Management Console and go to the Cognito console.
2. Click “Manage Your User Pools”. Press the user pools you have created. Here the name of the pool is “box-cognito-integration”.
3. Click the “App”. Then, click “Add an app”.
4. Give the app name and fill other configuration details based on the need.
5. Click “Create app”. The app is now created.
6. Click “Save changes”.

Step 4: Create a user as the Cognito Admin

1. Log into the AWS Management Console and go to the Cognito console.
2. Click “Manage you User Pools”. Press the user pools you have created. Here the name of the pool is “box-cognito-integration”.
3. Click “Users and groups”.
4. Click “Create user”. Fill out the details and click “Create user” button in the pop-up.
5. The user created successfully. The status of the user is “Enabled”.

Step 5: Create an API in Amazon API Gateway

1. Log into the AWS Management Console and go to the API Gateway console.
2. Press “Create API”.
3. Click “New API”.
4. Give API name as box-node-cognito-token-exchange and fill description.
5. Press “Create API”.

Step 6: Create an AWS Identity and Access Management (IAM) role

1. Go to IAM
2. Press “Create New Role”
3. Give Role Name box-node-cognito-token-exchange-sample-role. Click "Next Step"
4. Select “AWS Lambda”.
5. Select Policies

• AWSLambdaFullAccess
• CloudWatchLogsFullAccess
• AmazonCognitoPowerUser

6. Review and press “Create Role”.

Build the Integration

Next, you’ll create two Lambda functions.

Step 7: Create a Lambda function that creates the App User in Box

Next, you’ll need to create a Lambda function that creates an App User in Box when a user logs in to your app. In this tutorial, we’ll use the Box Node SDK for the integration.

1. Log into the AWS Management Console and go to the Lambda Management Console
2. Press “Create a Lambda function”

• Choose the “Blank Function” blueprint

3. Create the deployment package for the Lambda function

• Run npm install to install the Box Node SDK and other dependencies.
• Run npm run zip to create box-node-cognito-create-appuser-lambda-sample.zip

4. Configure the lambda function

• Name = “box-node-cognito-create-appuser-lambda-sample”
• Description = “Creates a Box app user for the given AWS cognito user”
• Runtime = “Node.js”
• Code entry type = “Upload a .ZIP file”
• Function package = Browse and select box-node-cognito-create-appuser-lambda-sample.zip
• Environment variables:

BOX_ENTERPRISE_ID = <YOUR_BOX_ENTERPRISE_ID>
BOX_CLIENT_ID = <YOUR_APP_CLIENT_ID>
BOX_CLIENT_SECRET = <YOUR_APP_CLIENT_SECRET>
COGNITO_USER_POOL_ID = <YOUR_COGNITO_USER_POOL_ID>
COGNITO_USER_ATTRIBUTE_BOX_APPUSER_ID_KEY = custom:box_appuser_id
BOX_PUBLIC_KEY_ID = <YOUR_APP_PUBLIC_KEY_ID>
BOX_PRIVATE_KEY_PASSPHRASE = <YOUR_APP_PRIVATE_KEY_PASSPHRASE>

• Handler = “index.handler”. This sets the entry point to be the handler() function of the index.js file
• Role = “Create new role from template”
• Role Name = “box-node-cognito-create-appuser-sample-role”
• Policy Templates = Leave blank
• Leave all of the advanced settings with default values
• Press “Next”

5. Press “Create function”

Step 8: Set Cognito “Post Authentication” trigger

1. Log into the AWS Management Console and go to the Cognito console.
2. Press “Manage you User Pools”. Press the user pools you have created. Here the name of the pool is “box-cognito-integration”.
3. Press “Triggers”.
4. In the “Post authentication” section, select the Lambda function “box-node-cognito-create-appuser-lambda-sample”.
5. Press “Save changes”.

Step 9: Create a Lambda function that generates a Box App User token for the given Cognito JWT access token

1. Log into the AWS Management Console and go to the Lambda Management Console
2. Press “Create a Lambda function”

• Choose the “Blank Function” blueprint

3. Configure a trigger for the Lambda function by clicking in the gray outlined area

• Choose API Gateway created in Step 1.
• Leave the API name and Deployment stage with default values
• Choose “Open” for Security. This enables the Box webhook to call the API externally
• Press Next

4. Create the deployment package for the Lambda function

• Run npm install to install the Box Node SDK and other depdencies.
• Run npm run zip to create box-node-cognito-token-exchange-lambda-sample.zip

5. Configure the Lambda function

• Name = “box-node-cognito-token-exchange-lambda-sample”
• Description = “Generate the Box app user token”
• Runtime = “Node.js”
• Code entry type = “Upload a .ZIP file”
• Function package = Browse and select box-node-cognito-token-exchange-lambda-sample.zip
• Environment variables:

BOX_ENTERPRISE_ID = <YOUR_BOX_ENTERPRISE_ID>
BOX_CLIENT_ID = <YOUR_APP_CLIENT_ID>
BOX_CLIENT_SECRET = <YOUR_APP_CLIENT_SECRET>
COGNITO_USER_POOL_ID = <YOUR_COGNITO_USER_POOL_ID>
COGNITO_USER_ATTRIBUTE_BOX_APPUSER_ID_KEY = custom:box_appuser_id
BOX_PUBLIC_KEY_ID = <YOUR_APP_PUBLIC_KEY_ID>
BOX_PRIVATE_KEY_PASSPHRASE = <YOUR_APP_PRIVATE_KEY_PASSPHRASE>

• Handler = “index.handler”. This sets the entry point to be the handler() function of the index.js file
• Role = “Create new role from template”
• Role Name = “box-node-cognito-token-exchange-sample-role”
• Policy Templates = Leave blank
• Leave all of the advanced settings with default values.
• Press “Next”

6. Press “Create function”

Step 10: Develop an app client

The app client should handle the login to Cognito. Also it should support the newPasswordRequired operation to generate a new password for the first time login based on the configuration.

Step 11: Log in as user

1. Login as the user that is created in the previous step. Change password if it asks for it.
2. It triggers the “Create App User Lambda Function”. That creates the user in Box.
3. Verify in Box that the user is created successfully in the enterprise.

Step 12: Token exchange

1. Once a token is generated from Cognito, the app client should call the API gateway end point that is used as a trigger for the “Token Exchange Lambda function”.
2. The Box token is sent as a successful response. The request body looks as below.

{
   "token":"<cognito_token>"
}

And that’s it! You can now authenticate and manage App Users using Amazon Cognito and AWS Lambda.

You can see the complete Github repo with working code available here. You can also view a client application implementation in Angular 2 here.

If you have any questions or suggestions, feel free to reach out to us on Twitter or post in our Developer Forum.