Work-In-Progress (WIP)
An attempt to automate the build process of AWS Lambda@Edge function, that is used for authentication and authorization.
- Docker
Expand/Collapse
- Google Developer Console > Create a New Project
- Project Name:
app
- Organization: Leave empty
- Project Name:
- OAuth consent screen > Select External > Click CREATE
- App name:
app
- User support email:
your email address
- Authorised domains > Add domain >
example.com
- Developer contact information:
your email address
Click SAVE AND CONTINUE
- App name:
- Scopes > Click SAVE AND CONTINTUE - there's no need for a scope, we don't plan on using Google APIs (authorization), we just need the authentication mechanism (OAuth2/OIDC)
- (Optional) Test users > Click SAVE AND CONTINTUE - it's irrelevant since either way we're allowing any Google user to login to the app since it's a local app
- Summary > Click BACK TO DASHBOARD
- NOTE: There's no need to PUBLISH APP, keep it in sandbox mode
- Credentials > Click CREATE CREDENTIALS > Select OAuth Client ID > Select Application type Web application
- Name:
app-sso
- Authorised JavaScript origins ADD URI >
https://app.example.com
- Authorised redirect URIs ADD URI >
https://app.example.com/_callback
Click CREATE - Save Your Client ID and Your Client Secret in a safe place, we'll use them in the following section
- Name:
-
Set environment variables according to your application and IdP, either with
export MY_VAR=MY_VALUE
or with the.env
fileAUTHN="GOOGLE" # Identity Provider (IdP) AUTH_AUTHZ="HOSTED_DOMAIN" # Authorize by email domain AUTH_HOST_DOMAIN="example.com" # Only users with this domain will be authorized to login AUTH_REDIRECT_URI="https://app.example.com/_callback" AUTH_CLIENT_ID="myClientId" AUTH_CLIENT_SECRET="myClientSecret" AUTH_CLOUDFRONT_DIST_ID="E1TU2EGCZDDALR" AUTH_SESSION_DURATION_HOURS=12
-
Run a container that will build your customized Lambda@Edge function
# Copy `env` to `.env`, or pass environment variables with `-e MY_VAR=MY_VALUE` docker run --rm -it --env-file .env -v "${PWD}/distributions/":/usr/src/app/distributions/ -v "${PWD}/out/":/usr/src/app/out/ unfor19/cloudfront-auth # Check for a new ZIP file in PWD/out/, named after your CloudFront Distribution ID, like `E1TU2EGCZDDALR.zip`
Some explanations about the Docker volume mounts
-v "${PWD}/distributions/":/usr/src/app/distributions/
- Contains a sub-directory per CloudFront Distribution Id. Each directory contains the artifacts that will be zipped per distribution. This mount is for debugging purposes, to see what's inside the package. Also, thepem
andpub
are generated only if they don't exist, so having this mount means you'll use the samepem
andpub
keys per distribution, instead of generating new ones.-v "${PWD}/out/":/usr/src/app/out/
- Contains the final artifacts${DISTRIBUTION_ID}.ZIP
files. The ZIP file is then uploaded as the Lambda@Edge function code.
Clone or fork this repository.
- Build a Docker image
docker build -t cloudfront-auth .
- Run a Docker container
# Copy `env` to `.env`, or pass environment variables with `-e MY_VAR=MY_VALUE` docker run --rm -it --env-file .env -v "${PWD}/distributions/":/usr/src/app/distributions/ -v "${PWD}/out/":/usr/src/app/out/ cloudfront-auth
- Artifact: The final artifact after running running the container will be a ZIP file, like
E1TU2EGCZDDALR.zip
. The ZIP file is a ready-to-deploy Viewer-Request Lambda@Edge Function.
TODO: Add code snippets of how to automatically deploy this function as part of CloudFormation/Terraform.
- Build a Docker image
docker build -t cloudfront-auth:dev --target=dev .
- Run a Docker container
# Copy `env` to `.env`, or pass environment variables with `-e MY_VAR=MY_VALUE` docker run --rm -it --env-file .env -v "$PWD":/usr/src/app/ cloudfront-auth:dev
- Build app in container
# Make sure you set environment variables according to the `env` file before executing this command
yarn build:ci
- Artifact: check the directories
/usr/src/app/distributions
and/usr/src/app/out
Expand/Collapse
Google Apps (G Suite), Microsoft Azure AD, GitHub, OKTA, Auth0, Centrify authentication for CloudFront using Lambda@Edge. The original use case for cloudfront-auth
was to serve private S3 content over HTTPS without running a proxy server in EC2 to authenticate requests; but cloudfront-auth
can be used authenticate requests of any Cloudfront origin configuration.
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.
If your CloudFront distribution is pointed at a S3 bucket, configure origin access identity so S3 objects can be stored with private permissions. (Origin access identity requires the S3 ACL owner be the account owner. Use our s3-object-owner-monitor Lambda function if writing objects across multiple accounts.)
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).
- Clone or download this repo
- Navigate to your organization's profile page, then choose OAuth Apps under Developer settings.
- Select New OAuth App
- 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
- Execute
./build.sh
in the downloaded directory. NPM will run to download dependencies and a RSA key will be generated.- 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.
- Choose
- Upload the resulting
zip
file found in your distribution folder using the AWS Lambda console and jump to the configuration step
- Clone or download this repo
- Go to the Credentials tab of your Google developers console
- Create a new Project
- Create an OAuth Client ID from the Create credentials menu
- Select Web application for the Application type
- 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
- Execute
./build.sh
in the downloaded directory. NPM will run to download dependencies and a RSA key will be generated. - Choose
Google
as the authorization method and enter the values for Client ID, Client Secret, Redirect URI, Hosted Domain and Session Duration - Select the preferred authentication method
- Hosted Domain (verify email's domain matches that of the given hosted domain)
- JSON Email Lookup
- Enter your JSON Email Lookup URL (example below) that consists of a single JSON array of emails to search through
- Google Groups Lookup
- Upload the resulting
zip
file found in your distribution folder using the AWS Lambda console and jump to the configuration step
- Clone or download this repo
- In your Azure portal, go to Azure Active Directory and select App registrations
- Create a new application registration with an application type of Web app / api
- 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 yourclient_secret
- Above where you selected
Keys
, go toReply URLs
and enter your Cloudfront hostname with your preferred path value for the authorization callback. Example: https://my-cloudfront-site.example.com/_callback
- Execute
./build.sh
in the downloaded directory. NPM will run to download dependencies and a RSA key will be generated. - 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 - Select the preferred authentication method
- Azure AD Membership (default)
- JSON Username Lookup
- Enter your JSON Username Lookup URL (example below) that consists of a single JSON array of usernames to search through
- Upload the resulting
zip
file found in your distribution folder using the AWS Lambda console and jump to the configuration step
- Clone or download this repo
- Sign in to OKTA with your administrator account and navigate to the
Applications
tab. - Add Application
- Select the
Web
application type - Base URI: CloudFront distribution domain name (
https://{cf-endpoint}.cloudfront.net
) - Login Redirect URI: CloudFront distribution domain name with callback path (
https://{cf-endpoint}.cloudfront.net/_callback
) - Group Assignments: Optional
- Grant Type Allowed: Authorization Code
- Done
- Select the
- Gather the following information for Lambda configuration
- Client Id and Client Secret from the application created in our previous step (can be found at the bottom of the general tab)
- Base Url
- This is named the 'Org URL' and can be found in the top right of the Dashboard tab.
- Execute
./build.sh
in the downloaded directory. NPM will run to download dependencies and a RSA key will be generated. - Choose
OKTA
as the authorization method and enter the values for Base URL (Org URL), Client ID, Client Secret, Redirect URI, and Session Duration - Upload the resulting
zip
file found in your distribution folder using the AWS Lambda console and jump to the configuration step
- Clone or download this repo
- Go to the Dashboard of your Auth0 admin page
- Click New Application
- Select Regular Web App and click Create.
- Now select an application type and follow the steps for 'Quick Start' or use your own app.
- Go to application Settings and enter required details. In Allowed Callback URLs enter your Cloudfront hostname with your preferred path value for the authorization callback. Example:
https://my-cloudfront-site.example.com/_callback
- Execute
./build.sh
in the downloaded directory. NPM will run to download dependencies and a RSA key will be generated. - Choose
AUTH0
as the authorization method and enter the values for Base URL (Auth0 Domain), Client ID, Client Secret, Redirect URI, and Session Duration - Upload the resulting
zip
file found in your distribution folder using the AWS Lambda console and jump to the configuration step
- Clone or download this repo
- Go to the Dashboard of your Centrify admin page
- Click Web Apps from the LHS.
- Click Add Web App and select the Custom Tab.
- Add an OpenID Connect webapp and click Yes to confirm.
- Fill in naming and logo information and then switch to the Trust tab.
- Enter service provider information. In Authorized Redirect URIs enter your Cloudfront hostname with your preferred path value for the authorization callback. Example:
https://my-cloudfront-site.example.com/_callback
- Execute
./build.sh
in the downloaded directory. NPM will run to download dependencies and a RSA key will be generated. - Choose
CENTRIFY
as the authorization method and enter the values for Base URL (Centrify Resource application URL), Client ID, Client Secret, Redirect URI, and Session Duration (which is available from the Tokens tab). - Upload the resulting
zip
file found in your distribution folder using the AWS Lambda console and jump to the configuration step
- Clone or download this repo
- Sign in to OKTA with your administrator account and navigate to the
Applications
tab. - Add Application
- Select the
Native
application type - Base URI: CloudFront distribution domain name (
https://{cf-endpoint}.cloudfront.net
) - Login Redirect URI: CloudFront distribution domain name with callback path (
https://{cf-endpoint}.cloudfront.net/_callback
) - Group Assignments: Optional
- Grant Type Allowed: Authorization Code
- Done
- Select the
- Gather the following information for Lambda configuration
- Client Id from the application created in our previous step (can be found at the bottom of the general tab)
- Base Url
- This is named the 'Org URL' and can be found in the top right of the Dashboard tab.
- Execute
./build.sh
in the downloaded directory. NPM will run to download dependencies and a RSA key will be generated. - Choose
OKTA Native
as the authorization method and enter the values for Base URL (Org URL), Client ID, PKCE Code Verifier Length, Redirect URI, and Session Duration - Upload the resulting
zip
file found in your distribution folder using the AWS Lambda console and jump to the configuration step
Manual Deployment or AWS SAM Deployment
-
JSON array of email addresses
[ "[email protected]", "[email protected]" ]
Detailed instructions on testing your function can be found in the Wiki.
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.