Introduction to the Deployment Setup
To create a unified deployment process, this guide focuses on packaging a Next.js token exchange broker for both local testing and real cluster environments. Using tools like Docker Compose and Kubernetes Helm, the same application can be deployed seamlessly across diverse environments. The broker leverages OIDC sign-in capabilities with support for single or multiple providers, ensuring flexibility in authentication configurations.
The underlying principle involves running the same container image across all environments while substituting environment-specific values. This eliminates inconsistencies and simplifies the testing and deployment workflow. Key configurations include environment variables such as NEXTAUTH_SECRET, NEXTAUTH_URL, and provider-specific credentials.
Configuring Environment Variables
The application relies heavily on environment variables to function correctly in different environments. For example, NEXTAUTH_SECRET holds a random 32-byte secret for authentication, while NEXTAUTH_URL specifies the base URL for the app. Additional variables like ENTRAID_TENANT_ID and REDIS_URL manage integration with external services such as Microsoft Graph APIs and Redis for caching.
One critical aspect is ensuring that the OIDC provider configurations are valid JSON objects. Double quotes should surround keys and strings, and trailing commas must be avoided. Debugging JSON validity is often the first step if issues arise during provider rendering on the login page.
OIDC Provider Setup
To support multiple OIDC providers, a structured array of JSON objects is used. Each object should include keys such as id, baseUrl, clientId, and clientSecret. For instance, a provider named PingFederate could have an entry specifying its authentication URL and related credentials.
Adding additional providers is straightforward-simply append new JSON objects to the array. This modularity enables seamless integration with other identity providers, such as Auth0 or corporate credentials via PingFederate. Properly configuring these entries ensures a smooth sign-in experience for users.
Building and Pushing Docker Images
The process begins with building a Docker image of the application using the docker build command. The resulting image is tagged appropriately and pushed to a container registry. For example, the tag darkedges/entraid-token-exchange might be used for this application.
Once pushed, the image serves as the foundation for both Docker Compose and Kubernetes Helm deployments. This approach ensures consistency in application behavior across local and cluster environments, reducing the potential for deployment-specific issues.
Deploying with Kubernetes Helm
To deploy the application in a Kubernetes cluster, secrets for the container registry are first created using the kubectl create secret docker-registry command. This step ensures that the Kubernetes cluster can pull the necessary images securely.
Next, the application is deployed using Helm. Commands like helm upgrade --install and kubectl get pods are used to manage the deployment process and verify the status of running pods. Additionally, a custom namespace such as broker can be created to isolate the application components.
Managing Application Components
The architecture of the application is divided into several components, each with its specific environment variables. For instance, the backend token exchange app requires ENTRAID_CLIENT_ID, ENTRAID_CLIENT_SECRET, and ENTRAID_SCOPE. Similarly, the web login app relies on OIDC_PROVIDER configurations for authentication.
Optional configurations, such as those for CIAM (Customer Identity and Access Management) apps, can also be incorporated. These typically require their own set of environment variables, including ENTRAID_CIAM_CLIENT_ID and ENTRAID_CIAM_SCOPE. Properly managing these components ensures that the application functions as intended across various use cases.