AWS Lambda

Have a lambda living in AWS and an API Gateway for it? Excellent. Here's how to use Internal's Auth Provider and AWS Cognito to call that lambda.

The Setup

This writeup makes a fair few assumptions, chief amongst these are the following:

  1. You have created a Lambda function in AWS
  2. You have created an API Gateway for said Lambda function
  3. You have created and integrated a Cognito authorization instance for the API Gateway
  4. You are comfortable with the AWS console
  5. You are an admin of your Internal instance

If your situation meets the above criteria, keep reading.

Creating Your App Client for Internal in Cognito

In this section, we will be creating an app client in Cognito that will act as an authentication bridge between Internal and your API Gateway for your Lambda function.

  1. Navigate to Amazon Cognito > User pools > {your user pool name}
  2. Scroll to the bottom of the page, and click the "Create app client" button
  1. Give the app a name
  2. Have the app generate the client secret
  1. In the "Authentication Flows" section, be sure to select "ALLOW_CUSTOM_AUTH" and "ALLOW_USER_SRP_AUTH" from the dropdown
  1. The token expiry and revocation are inconsequential to working with Internal, but should be carefully considered before implementation
  2. In the "Hosted UI Settings" you'll need to add Internal's callback URI: https://secure.internal.io/api/authorization-flow/oauth2/callback
  3. In the "OAuth 2.0 Grant Types" section, remove the "Implicit Grant" grant type
  1. Click "Create app client" button at the bottom of the form

Creating a Custom Authorization Flow in Internal

Now that we've got a Lambda, an API Gateway, and an authorization application for the gateway, we can set Internal up to authorize through Cognito, which will send a request to the API Gateway, which will call "invoke" on our Lambda function.

  1. In Internal, navigate to "Company Settings" at the bottom of the left navigation panel
  1. In the resulting view, select the "Authorization Providers" Tab and click "Add Authorization Provider"
  1. In the proceeding view, give the new authorization provider a name and select "Custom" from the dropdown selector
  1. You will then be sent to a larger, pop-out view from the right of the entire Authorization Provider configuration panel. In that panel, click "Add Another Step"
  1. In the next view, select "OAuth 2.0" from the dropdown next to "Step 0"
  1. Double check that the callback URI listed in the top of configuration panel matches the callback URI in your API Gateway configuration in AWS
  2. Fill in the Auth and Token URLs in the resulting form. They follow this pattern: https://mydomain.auth.us-east-1.amazoncognito.com/oauth2/token and https://mydomain.auth.us-east-1.amazoncognito.com/oauth2/authorize Note: You need to ensure that the domain and locality of the AWS instance match that listed in your Cognito instance.
  1. Add Client ID and Client Secret to the form in Internal. Those can be found in Cognito under User Pools > {Your Pool Name} > {Your App Name}
  1. Then, add the following scopes to the Scopes field: "email openid profile" Note: These are space delimited and require no quotes in the input field
  2. It'll look like this when you're done:

  1. Next, we'll import the access token into the auth headers of the "credential" section of the form. Click "Add a Header" and then enter a key / value pair of "Authorization" and "Bearer $(step0.IdToken)"
  1. Click "Save" in the upper-righthand corner of the form

Calling the Function from Internal

Now that we have a functioning connection between Internal and Cognito, we can use Internal's Functions to invoke the API Gateway for our Lambda. There are many ways to do so, but the simplest would be to create a function which uses the new Auth provider and add that function to a Space. This will prompt the user to log into Cognito. On successful log-in, the API Gateway will be invoked, and the lambda will be called in AWS Lambda.

  1. In a Space, click the "Data Source" icon in the upper left (the thing that looks like two discs on top of each other)
  2. In the resulting page, click the "Auth" tab and select our new Authorization Provider from the dropdown selector
  1. Users, when attempting to navigate to a Space which uses that function, will see this:
  1. Logging in will trigger the Lambda via the API Gateway via Cognito authorization