Core Linux - OpenID Connect (OIDC) Authentication in Azure

OpenID Connect (OIDC) is an authentication protocol that enables secure user authentication and authorization. This guide will walk you through the steps to set up OIDC authentication for your application using Azure Active Directory (Azure AD) as the identity provider.

Prerequisites

• An Azure account with sufficient privileges for managing an Azure AD application.

• An existing application you want to enable OIDC authentication for.

Steps 

Step 1: Create an Azure AD Application

1. Log in to the Azure portal: https://portal.azure.com/

2. Go to "Azure Active Directory."

3. Choose "App registrations" from the left menu.

4. Click "+ New registration."

5. Fill in the details:

   1. Name: Name of your application.

   2. Supported account types: Choose the appropriate types.

   3. Redirect URI (Single Page Application): Use the application host followed by "/app" (e.g., https://yourappdomain.com/app).

6. Click "Register" to create the app.

7. Ensure under API Permissions for the App that User.Read is present (Microsoft Graph - Delegated).

Step 2: Configure OIDC Settings

1. In the application settings, navigate to the "Authentication" section.

2. Confirm that the callback URL is listed in "Redirect URIs."

3. Click "Save" to confirm the changes.

Step 3: Retrieve Application Configuration Details

1.  Note down these details from the app settings:

   1. Application (client) ID: Unique identifier for your app.

   2. Directory (tenant) ID: Azure AD instance identifier.

   3. Issuer URL: OIDC issuer URL format: https://login.microsoftonline.com/{tenant_id}/v2.0.

Step 4: Set Up API Container Environment Variables

The package folder comes with a file called docker-compose-oidc.yml - we will want to copy that file into a new file called docker-compose-custom.yml and then edit this newly created file. If you already have a docker-compose-custom.yml file with some custom configuration elements, we will simply be editing that file instead.

cp docker-compose-oidc.yml docker-compose-custom.yml

Next, we will edit the api section of the docker-compose-custom.yml file to include the correct values for the following environment variables, replacing the right-hand side of each line with the actual values:

api:
  image: testmodeller_api
  ...
  environment:
    ...
    OIDC_EMAIL_CLAIM: unique_name
    AUTH_METHOD: Oidc

• OIDC_EMAIL_CLAIM: Claim with the user's email (e.g., unique_name, default for Azure).

• AUTH_METHOD: Set to Oidc for OIDC-based authentication.

Step 5: Configure OIDC for the Web Container

Next, we will edit the web section of the docker-compose-custom.yml file to include the correct values for the following environment variables, replacing the right-hand side of each line with the actual values:

web:
  image: testmodeller_web
  ...
  environment:
    ...
    # replace {tenantId} with the actual tenant GUID and {applicationId} with the actual application GUID
    OIDC_AUTHORITY: "https://login.microsoftonline.com/{tenantId}/v2.0"
    OIDC_WELL_KNOWN_URI: "https://login.microsoftonline.com/{tenantId}/v2.0/.well-known/openid-configuration"
    OIDC_REDIRECT_URI: "${HOST_PROTOCOL}${HOST_ADDRESS}:${HOST_PORT}/app"
    OIDC_CLIENT_ID: "{applicationId}"
    OIDC_SCOPE: "{applicationId}/.default"

• OIDC_AUTHORITY: The tenant ID for Azure AD.

• OIDC_WELL_KNOWN_URI: The URL for OIDC configuration.

• OIDC_REDIRECT_URI: The redirect URL after authentication.

• OIDC_CLIENT_ID: The application ID from Azure AD.

• OIDC_SCOPE: The scope for OIDC authentication

Step 6: Launch and Test

1. Start both the API and web containers using .\run.sh 

2. Access your web app through a browser.

3. Initiate authentication with Azure AD.

4. After successful authentication, you'll be redirected back to your app.

Conclusion

By following these steps and configuring the required environment variables, you've integrated OIDC authentication into your API and web containers using Azure AD. This ensures secure user authentication and authorization for your app.