From c4681cdc95e9b195eee456085bf3b49175eea493 Mon Sep 17 00:00:00 2001 From: Siva Nadesan Date: Mon, 31 Mar 2025 18:29:32 -0700 Subject: [PATCH] changes to update the README for dbt docs --- dbt-docs/README.md | 104 +++++++++++------- .../cloudfront-microsoft-sso/README.md | 13 +++ .../sample/index.html | 84 ++++++++++++++ .../cloudfront-microsoft-sso/lambda.tf | 6 +- 4 files changed, 165 insertions(+), 42 deletions(-) create mode 100644 dbt-docs/terraform/cloudfront-microsoft-sso/sample/index.html diff --git a/dbt-docs/README.md b/dbt-docs/README.md index 44bc7c6..e26fe58 100644 --- a/dbt-docs/README.md +++ b/dbt-docs/README.md @@ -1,48 +1,71 @@ -- [Overview](#overview) -- [How to Generate and Serve dbt Docs Locally](#how-to-generate-and-serve-dbt-docs-locally) -- [Hosting Options](#hosting-options) - - [Github Pages](#github-pages) - - [Netlify](#netlify) - - [S3 and CloudFront](#s3-and-cloudfront) - - [S3, CloudFront, and Cognito](#s3-cloudfront-and-cognito) -- [Deployment Steps](#deployment-steps) -- [Reference](#reference) +# dbt Docs Hosting Solutions -# Overview -This repository contains demo code showcasing how to host dbt(data build tool) docs. +- [dbt Docs Hosting Solutions](#dbt-docs-hosting-solutions) + - [Overview](#overview) + - [How to Generate and Serve dbt Docs Locally](#how-to-generate-and-serve-dbt-docs-locally) + - [Hosting Options](#hosting-options) + - [Github Pages](#github-pages) + - [Netlify](#netlify) + - [S3 and CloudFront](#s3-and-cloudfront) + - [S3, CloudFront, and Microsoft Entra ID SSO](#s3-cloudfront-and-microsoft-entra-id-sso) + - [S3, CloudFront, and Cognito](#s3-cloudfront-and-cognito) + - [Deployment Steps](#deployment-steps) + - [Reference](#reference) -# How to Generate and Serve dbt Docs Locally +## Overview +This repository contains demo code showcasing various options for hosting dbt (data build tool) documentation. + +## How to Generate and Serve dbt Docs Locally To generate and serve dbt docs locally, follow these simple steps: -1. **Generate the Document:** Open your terminal or command prompt and run the following command to generate the dbt document: +1. **Generate the Documentation:** Open your terminal or command prompt and run the following command to generate the dbt documentation: - `dbt docs generate`, This command will create the necessary documentation files based on your dbt project. + ``` + dbt docs generate + ``` + + This command will create the necessary documentation files based on your dbt project. -2. **Serve the Document:** After generating the documentation, use the following command to serve it locally: +2. **Serve the Documentation:** After generating the documentation, use the following command to serve it locally: + + ``` + dbt docs serve + ``` + + By default, the documentation will be served on port 8080. To specify a custom port, use: - `dbt docs serve`. By default, the documentation will be served on port 8080. However, if you want to specify a custom port, you can use the following command `dbt docs serve --port 3000`. This will serve the documentation on port 3000 (you can replace "3000" with any port of your choice). + ``` + dbt docs serve --port 3000 + ``` + + This will serve the documentation on port 3000 (replace "3000" with any port of your choice). -3. **View the dbt Document:** Open your web browser and navigate to [http://localhost:8080/](http://localhost:8080/) (or the custom port you specified) to access and view your dbt document. +3. **View the Documentation:** Open your web browser and navigate to [http://localhost:8080/](http://localhost:8080/) (or your custom port) to access and view your dbt documentation. -That's it ! Now you have your dbt documentation generated and served locally for easy access and review. +That's it! Now you have your dbt documentation generated and served locally for easy access and review. -# Hosting Options -Here are some user-friendly hosting options for static websites like dbt docs: +## Hosting Options +Here are several user-friendly hosting options for static websites like dbt docs: -## Github Pages +### Github Pages The simplest and most straightforward option. It comes with no extra cost, but there's a limitation: sites hosted on Github Pages will be public in the free tier. For private access and authentication setup, an enterprise tier is required. -## Netlify -A powerful serverless platform with an intuitive git-based workflow. Netlify allows to host static websites with ease. This is simple as well but preferenced below github pages only because it sits outside github eco system. +### Netlify +A powerful serverless platform with an intuitive git-based workflow. Netlify allows you to host static websites with ease. This is simple as well but ranked below Github Pages only because it sits outside the GitHub ecosystem. -## S3 and CloudFront +### S3 and CloudFront A cost-effective option that offers the ability to add basic authentication for restricted access. S3 (Simple Storage Service) provides reliable storage for your static content, and CloudFront serves as a content delivery network for faster and more efficient distribution. -## S3, CloudFront, and Cognito -The most robust option that provides the ability to let users sign up for access. In addition to S3 and CloudFront, Amazon Cognito is used to manage user identities and authentication. This setup allows you to control who can access your dbt docs by creating user pools and defining user sign-up and sign-in processes. +### S3, CloudFront, and Microsoft Entra ID SSO +A robust enterprise solution that leverages your existing Microsoft identity system. This option allows you to authenticate users with their Microsoft Entra ID (formerly Azure AD) credentials, making it ideal for organizations already using Microsoft services. The implementation uses Lambda@Edge for authentication at the edge, providing a seamless and secure user experience without requiring server-side components. + +See the [cloudfront-microsoft-sso](./terraform/cloudfront-microsoft-sso/README.md) module for implementation details. + +### S3, CloudFront, and Cognito +Another comprehensive option that provides the ability to let users sign up for access. In addition to S3 and CloudFront, Amazon Cognito is used to manage user identities and authentication. This setup allows you to control who can access your dbt docs by creating user pools and defining user sign-up and sign-in processes. -# Deployment Steps +## Deployment Steps To deploy your dbt docs website, follow these steps: 1. **Configure AWS Credentials:** @@ -53,27 +76,27 @@ To deploy your dbt docs website, follow these steps: ``` 2. **Initialize Terraform:** - Initialize Terraform in the project directory using the following command: + Initialize Terraform in the project directory using the following command: - ``` - terraform init - ``` + ``` + terraform init + ``` 3. **Format Terraform Configuration:** - Ensure that your Terraform configuration files are properly formatted for consistency: + Ensure that your Terraform configuration files are properly formatted for consistency: - ``` - terraform fmt -recursive - ``` + ``` + terraform fmt -recursive + ``` 4. **Deploy the Infrastructure:** - Apply the Terraform configuration to deploy your infrastructure: + Apply the Terraform configuration to deploy your infrastructure: - ``` - terraform apply - ``` + ``` + terraform apply + ``` -# Reference +## Reference Here are some useful references and resources related to hosting dbt docs and implementing authentication: - [AWS Static Website Hosting with Cognito and S3](https://howtoember.wordpress.com/2020/06/11/aws-static-website-hosting-with-cognito-and-s3/) @@ -82,3 +105,4 @@ Here are some useful references and resources related to hosting dbt docs and im - [Cognito Auth Example (sashee GitHub)](https://github.com/sashee/cognito-auth-example) - [Terraform AWS Lambda@Edge Cognito Authentication (disney GitHub)](https://github.com/disney/terraform-aws-lambda-at-edge-cognito-authentication) - [Validate User Email Domain AWS Cognito](https://andreybleme.com/2020-01-18/validate-user-email-domain-aws-cognito/) +- [Microsoft Entra ID Documentation](https://docs.microsoft.com/en-us/azure/active-directory/) diff --git a/dbt-docs/terraform/cloudfront-microsoft-sso/README.md b/dbt-docs/terraform/cloudfront-microsoft-sso/README.md index 8124c48..0152ec8 100644 --- a/dbt-docs/terraform/cloudfront-microsoft-sso/README.md +++ b/dbt-docs/terraform/cloudfront-microsoft-sso/README.md @@ -1,3 +1,16 @@ +- [Microsoft Entra ID SSO for CloudFront](#microsoft-entra-id-sso-for-cloudfront) + - [Architecture](#architecture) + - [How It Works](#how-it-works) + - [Quick Start](#quick-start) + - [1. Register Microsoft Entra ID Application](#1-register-microsoft-entra-id-application) + - [2. Store Credentials](#2-store-credentials) + - [3. Deploy Module](#3-deploy-module) + - [4. Configure CloudFront](#4-configure-cloudfront) + - [Module Inputs](#module-inputs) + - [Module Outputs](#module-outputs) + - [Troubleshooting](#troubleshooting) + - [Security Features](#security-features) + # Microsoft Entra ID SSO for CloudFront A Terraform module to implement Microsoft Entra ID (Azure AD) authentication for CloudFront static websites using Lambda@Edge. diff --git a/dbt-docs/terraform/cloudfront-microsoft-sso/sample/index.html b/dbt-docs/terraform/cloudfront-microsoft-sso/sample/index.html new file mode 100644 index 0000000..44aa415 --- /dev/null +++ b/dbt-docs/terraform/cloudfront-microsoft-sso/sample/index.html @@ -0,0 +1,84 @@ + + + + + + Microsoft Entra ID SSO Test Page + + + +

Microsoft Entra ID SSO Test Page

+ +
+

Authentication Successful!

+

If you can see this page, your SSO authentication is working correctly.

+
+ +
+

Session Information

+

Your session is secured by Microsoft Entra ID (formerly Azure AD).

+

The authentication is handled via Lambda@Edge functions that validate your session token.

+
+ +
+

How It Works

+

This page is protected by:

+ +
+ +
+

Testing Notes

+

To verify that authentication is working correctly:

+
    +
  1. Try accessing this page in a private/incognito window
    2. +
  2. You should be redirected to the Microsoft login page
    3. +
  3. After login, you should be redirected back here
    4. +
  4. Clear browser cookies to test the flow again
    5. +
+
+ + + + diff --git a/dbt-docs/terraform/modules/cloudfront-microsoft-sso/lambda.tf b/dbt-docs/terraform/modules/cloudfront-microsoft-sso/lambda.tf index 69bf0d6..c59101b 100644 --- a/dbt-docs/terraform/modules/cloudfront-microsoft-sso/lambda.tf +++ b/dbt-docs/terraform/modules/cloudfront-microsoft-sso/lambda.tf @@ -27,7 +27,8 @@ resource "null_resource" "prepare_authenticator" { } provisioner "local-exec" { - interpreter = ["/bin/bash", "-c"] + # Don't specify interpreter, let Terraform use the default shell + # interpreter = ["/bin/bash", "-c"] command = "rm -rf ${local.temp_authenticator_dir} && mkdir -p ${local.temp_authenticator_dir} && cp -r ${local.sso_authenticator_dir}/* ${local.temp_authenticator_dir}/ && sed -i 's/const SECRET_NAME = \"SECRET-NAME-PLACEHOLDER\";/const SECRET_NAME = \"${local.secret_name}\";/g' ${local.temp_authenticator_dir}/authenticator.js" } } @@ -40,7 +41,8 @@ resource "null_resource" "prepare_callback" { } provisioner "local-exec" { - interpreter = ["/bin/bash", "-c"] + # Don't specify interpreter, let Terraform use the default shell + # interpreter = ["/bin/bash", "-c"] command = "rm -rf ${local.temp_callback_dir} && mkdir -p ${local.temp_callback_dir} && cp -r ${local.sso_callback_dir}/* ${local.temp_callback_dir}/ && sed -i 's/const SECRET_NAME = \"SECRET-NAME-PLACEHOLDER\";/const SECRET_NAME = \"${local.secret_name}\";/g' ${local.temp_callback_dir}/callback-handler.js" } }