Google Apps (G Suite), Microsoft Azure AD, GitHub, and OKTA authentication for CloudFront using Lambda@Edge. The primary use case for cloudfront-auth is to serve private S3 content over HTTPS without running a proxy server to authenticate requests.

Description

Upon successful authentication, a cookie (named TOKEN) with the value of a signed JWT is set and the user redirected back to the originally requested path. Upon each request, Lambda@Edge checks the JWT for validity (signature, expiration date, audience and matching hosted domain) and will redirect the user to configured provider's login when their session has timed out.

Usage

If your CloudFront distribution is pointed at a S3 bucket, configure origin access identity so S3 objects can be stored with private permissions.

Enable SSL/HTTPS on your CloudFront distribution; AWS Certificate Manager can be used to provision a no-cost certificate.

Session duration is defined as the number of hours that the JWT is valid for. After session expiration, cloudfront-auth will redirect the user to the configured provider to re-authenticate. RSA keys are used to sign and validate the JWT. If the files id_rsa and id_rsa.pub do not exist they will be automatically generated by the build. To disable all issued JWTs upload a new ZIP using the Lambda Console after deleting the id_rsa and id_rsa.pub files (a new key will be automatically generated).

Login using Github

1. Clone or download this repo
2. Navigate to your organization's profile page, then choose OAuth Apps under Developer settings.
   1. Select New OAuth App
   2. For Authorization callback URL enter your Cloudfront hostname with your preferred path value for the authorization callback. Example: https://my-cloudfront-site.example.com/_callback
3. Execute ./build.sh in the downloaded directory. NPM will run to download dependencies and a RSA key will be generated.
   1. Choose Github as the authorization method and enter the values for Client ID, Client Secret, Redirect URI, Session Duration and Organization
      • cloudfront-auth will check that users are a member of the entered Organization.
4. Upload the resulting zip file found in your distribution folder using the AWS Lambda console and jump to the configuration step

Login using Google

1. Clone or download this repo
2. Go to the Credentials tab of your Google developers console
   1. Create a new Project
   2. Create an OAuth Client ID from the Create credentials menu
   3. Select Web application for the Application type
   4. Under Authorized redirect URIs, enter your Cloudfront hostname with your preferred path value for the authorization callback. Example: https://my-cloudfront-site.example.com/_callback
3. Execute ./build.sh in the downloaded directory. NPM will run to download dependencies and a RSA key will be generated.
4. Choose Google as the authorization method and enter the values for Client ID, Client Secret, Redirect URI, Hosted Domain and Session Duration
5. Select the preferred authentication method
   1. Hosted Domain (verify email's domain matches that of the given hosted domain)
   2. JSON Email Lookup
      1. Enter your JSON Email Lookup URL (example below) that consists of a single JSON array of emails to search through
   3. Google Groups Lookup
      1. Use Google Groups to authorize users
6. Upload the resulting zip file found in your distribution folder using the AWS Lambda console and jump to the configuration step

Login using Microsoft Azure

1. Clone or download this repo
2. In your Azure portal, go to Azure Active Directory and select App registrations
   1. Create a new application registration with an application type of Web app / api
   2. Once created, go to your application Settings -> Keys and make a new key with your desired duration. Click save and copy the value. This will be your client_secret
   3. Above where you selected Keys, go to Reply URLs and enter your Cloudfront hostname with your preferred path value for the authorization callback. Example: https://my-cloudfront-site.example.com/_callback
3. Execute ./build.sh in the downloaded directory. NPM will run to download dependencies and a RSA key will be generated.
4. Choose Microsoft as the authorization method and enter the values for Tenant, Client ID (Application ID), Client Secret (previously created key), Redirect URI and Session Duration
5. Select the preferred authentication method
   1. Azure AD Membership (default)
   2. JSON Username Lookup
      1. Enter your JSON Username Lookup URL (example below) that consists of a single JSON array of usernames to search through
6. Upload the resulting zip file found in your distribution folder using the AWS Lambda console and jump to the configuration step

Login using OKTA

1. Clone or download this repo
2. Go to the Applications tab of your OKTA admin page
   1. Add Application
   2. Select Web as the platform
   3. For Login redirect URIs, enter your Cloudfront hostname with your preferred path value for the authorization callback. Example: https://my-cloudfront-site.example.com/_callback
   4. Make sure Authorization Code is checked for Grant type allowed
3. Execute ./build.sh in the downloaded directory. NPM will run to download dependencies and a RSA key will be generated.
4. Choose OKTA as the authorization method and enter the values for Base URL, Client ID, Client Secret, Redirect URI, and Session Duration
5. Upload the resulting zip file found in your distribution folder using the AWS Lambda console and jump to the configuration step

Configure Lambda and CloudFront

1. Upload cloudfront-auth.zip to Lambda using the AWS Console:

   1. Choose Create function
   2. Choose Blueprints
      • Search and select cloudfront-http-redirect
      • Enter Name (e.g. My_Site_Cloudfront_Auth)
      • Select Create new role from Templates as the Role
      • Enter Role Name (e.g. Lambda_At_Edge_Cloudfront)
      • Add the role policy template Basic Edge Lambda Permissions
      • Click Create function
   3. Choose Upload a .ZIP file under the Function code header and Code entry type field
      • Click Upload and choose your generated cloudfront-auth.zip file
      • Set Timeout under Basic Settings to be 5 seconds
      • Click Save
   4. Choose Publish new version under the Actions button
      • Enter a version description (e.g. v1)
   5. Copy the ARN value (required to be your published versioned) from the top-right: arn:aws:lambda:us-east-1:9999999999:function:my-site-cloudfront-auth:1

2. Configure CloudFront to use the Lambda function upon viewer request:

   1. Choose the Behaviors tab for your CloudFront distribution, mark the checkbox for the origin, choose Edit
   2. Under Lambda Function Associations
      • Select Viewer Request for the Event Type
      • Enter the Lambda ARN value (e.g. arn:aws:lambda:us-east-1:9999999999:function:my-site-cloudfront-auth:1)
      • Save
   3. It may take Cloudfront up to 20 minutes to fully configure the distribution. You may receive strange errors while the distribution is still updating.
   4. When fully deployed, your browser will be redirected to your authentication provider as necessary! Enjoy!

Authorization Method Examples

• Use Google Groups to authorize users

• JSON array of email addresses

  [ "[email protected]", "[email protected]" ]
  

Testing

Detailed instructions on testing your function can be found in the Wiki.

Build Requirements

• npm ^5.6.0
• node ^7.10.0
• openssl

Contributing

All contributions are welcome. Please create an issue in order open up communication with the community.

When implementing a new flow or using an already implemented flow, be sure to follow the same style used in build.js. The config.json file should have an object for each request made. For example, openid.index.js converts config.AUTH_REQUEST and config.TOKEN_REQUEST to querystrings for simplified requests (after adding dynamic variables such as state or nonce). For implementations that are not generic (most), endpoints are hardcoded in to the config (or discovery documents).

Be considerate of our limitations. The zipped function can be no more than 1MB in size and execution cannot take longer than 5 seconds, so we must pay close attention to the size of our dependencies and complexity of operations.