Ecosyste.ms: Awesome
An open API service indexing awesome lists of open source software.
https://github.com/yuvalherziger/oidc-client-app-service
A sample application deployed to Azure App Service using ACR, authenticating users with Azure AD OIDC
https://github.com/yuvalherziger/oidc-client-app-service
Last synced: 9 days ago
JSON representation
A sample application deployed to Azure App Service using ACR, authenticating users with Azure AD OIDC
- Host: GitHub
- URL: https://github.com/yuvalherziger/oidc-client-app-service
- Owner: yuvalherziger
- Created: 2022-04-04T09:20:23.000Z (over 2 years ago)
- Default Branch: main
- Last Pushed: 2022-04-12T09:08:40.000Z (over 2 years ago)
- Last Synced: 2024-10-31T18:12:22.323Z (16 days ago)
- Language: HCL
- Size: 2.08 MB
- Stars: 1
- Watchers: 2
- Forks: 0
- Open Issues: 2
-
Metadata Files:
- Readme: README.md
Awesome Lists containing this project
README
# Sample App Service Container with Custom OIDC Authentication
- [Intro](#intro)
- [Why?](#why-)
- [Architecture](#architecture)
- [Installation](#installation)
- [Requirements](#requirements)
- [Step 1: Build the Image](#step-1--build-the-image)
- [Step 2: Log In with the Azure CLI](#step-2--log-in-with-the-azure-cli)
- [Step 3: Configure the Deployment](#step-3--configure-the-deployment)
- [Step 4: Deploy](#step-4--deploy)
- [Further Customizations](#further-customizations)
## Intro
This project contains a sample Node.js server app that
- is built as a docker image and pushed into an ACR container repo;
- is deployed as an Azure App Service resource using Terraform (see below) or Bicep (coming soon);
- authenticates with Azure Active Directory over OIDC, in a way that the application can consume custom token claims.
## Why?
[Azure App Service](https://docs.microsoft.com/en-us/azure/app-service/overview), similarly to other compute services in Azure, supports built-in authentication using [Azure Active Directory](https://docs.microsoft.com/en-us/azure/active-directory/authentication/overview-authentication).
However, in some cases, you would want to have the authenticating client implemented in your workload with its own OpenID Connect client, sample reasons:
- You need to consume/use custom claims from your user's tokens.
- You have an existing application with established permissions, roles, and attributes, yet you need
to map them to Azure AD user claims (e.g., Azure Application Roles should be mapped to your application's roles).
- You have a requirement to protect only subsets of your endpoints with OIDC.
## Architecture
## Installation
### Requirements
- [Terraform CLI](https://learn.hashicorp.com/tutorials/terraform/install-cli) - you'll need to install the Terraform CLI in order
to provision resources.
- [Docker](https://docs.docker.com/desktop/) - you'll need to have Docker installed in order to build the app's image
- [Azure CLI](https://docs.microsoft.com/en-us/cli/azure/install-azure-cli) - you'll need to have Azure CLI installed in order
to log into Azure from your terminal.
- A Linux/WSL/macOS terminal
### Step 1: Build the Image
In order to build the application's image, run the following command:
```bash
make build-image
```
Please note that you might be required to have a [Docker Hub](https://hub.docker.com/) user and logged in for this to run. In few scenarios you might need to run it in an elevated way:
```bash
sudo make build-image
```
You can verify the image has been built successfully by running `docker images`. You should see
a line indicating that the `sample-oidc-client-app` is present in your Docker daemon, e.g.:
```zsh
REPOSITORY TAG IMAGE ID CREATED SIZE
sample-oidc-client-app latest 93f1bd0ceefc 6 hours ago 118MB
```
### Step 2: Log In with the Azure CLI
You can authenticate with Azure using the following CLI command:
```bash
az login
```
Please note that if you have multiple Azure profiles configured, you might want
to set the current Azure subscription explicitly with its subscription ID. For example:
```bash
az account set --subscription ${SUBSCRIPTION_ID}
```
### Step 3: Configure the Deployment
Before you can deploy the resource using Terraform, you will need to configure the deployment.
First, make a copy of the template Terraform variables file:
```bash
cp deploy/terraform/terraform.tfvars.example deploy/terraform/terraform.tfvars
```
You should now have a file named `terraform.tfvars` under the `deploy/terraform` directory.
Your configuration file contains the following variables; change their values as required:
- `subscription_id` (required): Your Azure account's subscription ID.
- `tenant_id` (required): The ID of the Azure Active Directory tenant under which
you'd like to provision the App Registration in.
- `allow_multiple_orgs` (default: `false`): Whether you'd like the App to allow authentication
using **any** work/school Azure AD tenant.
- `location` (default: `"eastus"`): The Azure region in which you'd like to provision your resources.
### Step 4: Deploy
Initialize the Terraform working directory:
```bash
cd deploy/terraform
terraform init
```
Run the following command to validate the deployment:
```bash
terraform plan -out oidc.plan
```
If everything ran successfully, the Terraform CLI should present to
you a summary of the resources to be provisioned.
Lastly, deploy the application using the following command:
```bash
terraform apply "oidc.plan"
```
Please note that this step should take a while, especially the `null_resource.docker_push` resource,
which pushes your app's container image to ACR.
If all resources were provisioned successfully, you should see a Terraform output along the following lines:
```zsh
Apply complete! Resources: 10 added, 0 changed, 0 destroyed.
Outputs:
instructions = <>`, you'll find that the following resources
have been provisioned:
- **App Service Plan**
- **App Service** Assigned with an `ACRPull` role, enabling it to pull from the ACR.
- **Container Registry**: ACR is where your container image is hosted.
In your Active Directory tenant, you'll find an App Registration, configured to allow OIDC authentication
for your App Service instance.
## Further Customizations
To be added. Topics to cover:
- Documentation on adding custom ID token claims
- Adding application roles as ID token claims