Understanding the Basics of Apache mod_auth_openidc with Microsoft Entra ID

Modern enterprise applications require secure authentication systems that are scalable, centralized, and easy to manage. Traditionally, many applications directly integrate authentication libraries such as Microsoft Authentication Library (MSAL) or Microsoft Security Library (MSL) into their application code.

While this approach works, it creates several challenges:

• Authentication logic gets duplicated across applications
• Backend code becomes complex
• Session handling increases maintenance overhead
• Security policies become inconsistent
• Applications become tightly coupled with authentication mechanisms

A more scalable and enterprise-grade solution is to move authentication away from application code and into the infrastructure layer using Apache HTTP Server with mod_auth_openidc.

This article explains the fundamentals of Apache mod_auth_openidc, OpenID Connect (OIDC), Microsoft Entra ID integration, reverse proxy architecture, claims, scopes, authentication flow, and enterprise security design in detail. The implementation discussed here is based on a practical enterprise-style architecture.

What is Apache mod_auth_openidc?

mod_auth_openidc is an Apache HTTP Server module that enables:

• OpenID Connect authentication
• OAuth 2.0 integration
• JWT token validation
• Single Sign-On (SSO)
• Session management
• Identity federation

Instead of applications handling authentication themselves, Apache performs authentication before requests reach the backend application.

Official Repository:https://github.com/OpenIDC/mod_auth_openidc

Why Centralized Authentication Matters

In traditional authentication architectures, every application independently performs:

• User login
• Token validation
• Session creation
• Logout handling
• Refresh token management
• Identity verification

Browser → Application → Microsoft Entra ID

This creates duplicated security logic across applications.

With Apache reverse proxy architecture:

Browser → Apache Reverse Proxy → Backend Application

Understanding OpenID Connect (OIDC)

OpenID Connect is an identity layer built on top of OAuth 2.0.

OAuth 2.0 mainly handles authorization.

OIDC adds:

• User authentication
• Identity verification
• User profile information

Microsoft Entra ID acts as the Identity Provider (IdP).

Apache acts as the Relying Party (RP).

Core OpenID Connect Terminology

Architecture Overview

The following architecture demonstrates how Apache mod_auth_openidc works with Microsoft Entra ID and Azure Web Apps.

Authentication Flow Explained in Detail

The complete OpenID Connect flow works as follows:

Step 1 — User Requests Protected Website

A user attempts to access the Apache reverse proxy endpoint.

Example:

https://YOUR_VM_IP

Apache detects that the user is not authenticated.

Step 2 — Apache Redirects User to Microsoft Login

Apache automatically redirects the user to Microsoft Entra ID login page.

At this stage:

• No request reaches the backend application
• Authentication happens entirely through Microsoft

Step 3 — User Authenticates

The user enters Microsoft credentials.

Microsoft Entra ID verifies:

• Username
• Password
• MFA policies
• Conditional Access policies

Step 4 — Microsoft Returns Authorization Code

After successful login, Microsoft redirects the browser back to Apache using the configured Redirect URI.

Example:

https://YOUR_VM_IP/redirect_uri

Apache receives:

• Authorization code
• Authentication response

Step 5 — Apache Exchanges Code for Tokens

Apache communicates securely with Microsoft Entra ID and exchanges the authorization code for:

• ID Token
• Access Token

Step 6 — Apache Validates Tokens

Apache validates:

• Signature
• Issuer
• Audience
• Expiration
• Claims

If validation succeeds, Apache creates an authenticated session.

Step 7 — Request is Forwarded to Backend Application

Only authenticated requests are forwarded to the Azure Web App.

The backend application never directly handles login or token validation

Understanding Claims in OIDC

Claims are user attributes stored inside tokens.

Example token:

{
  "sub": "123456789",
  "email": "user@example.com",
  "preferred_username": "user@example.com"
}

Common claim include

The sub claim is especially important because it uniquely identifies users and remains stable across sessions.

sub@iss = yourname@google

Understanding OIDC Scopes

Scopes define what information Apache requests from Microsoft Entra ID.

Example:

OIDCScope "openid profile email"

The openid scope is mandatory.

Without it, authentication fails because the request becomes standard OAuth instead of OpenID Connect.

Apache Reverse Proxy Configuration

Main Apache configuration file:

/etc/apache2/sites-available/default-ssl.conf

Example of Configuration

<VirtualHost *:443>

SSLEngine on

OIDCProviderMetadataURL https://login.microsoftonline.com/TENANT_ID/v2.0/.well-known/openid-configuration

OIDCClientID YOUR_CLIENT_ID

OIDCClientSecret YOUR_SECRET

OIDCRedirectURI https://YOUR_VM_IP/redirect_uri

OIDCCryptoPassphrase randomSecret123

OIDCRemoteUserClaim sub

OIDCPassClaimsAs environment

OIDCScope "openid profile email"

SSLProxyEngine On

ProxyPass / https://YOUR_WEBAPP.azurewebsites.net/

ProxyPassReverse / https://YOUR_WEBAPP.azurewebsites.net/

<Location />
    AuthType openid-connect
    Require valid-user
</Location>

</VirtualHost>

Understanding Important Apache Directives

OIDCProviderMetadataURL

Apache automatically downloads:

• Authorization endpoint
• Token endpoint
• Public signing keys
• Issuer metadata

This enables Apache to communicate with Microsoft Entra ID securely.

OIDCClientID

Uniquely identifies Apache inside Microsoft Entra ID.

Think of it as the application identity.

OIDCClientSecret

Acts as the password for Apache during token exchange.

This must remain confidential.

OIDCRedirectURI

Defines where Microsoft redirects users after authentication.

OIDCRedirectURI https://YOUR_VM_IP/redirect_uri

OIDCCryptoPassphrase

Used internally by Apache to:

• Encrypt sessions
• Protect cookies
• Secure token storage

OIDCRemoteUserClaim

Defines which claim becomes the authenticated username.

Example:

OIDCRemoteUserClaim sub

Why HTTPS is Required

OIDC authentication requires HTTPS because:

• Tokens are sensitive
• Sessions must be encrypted
• Cookies must be secure
• Browsers enforce secure policies

Apache typically listens on:

Restricting Direct Access to Backend Applications

A critical enterprise security practice is blocking direct access to the Azure Web App.

Only Apache VM IP should access the backend.

Example Azure Access Restriction:

All other traffic should be denied.

Authentication vs Authorization

Authentication

Authentication answers:

Who is the user?

Example :

Require valid-user

Authorization

Authorization answers:

What can the user access?

Example: Restricting Users

Require claim preferred_username:user@example.com

Example restricting Azure AD groups:

Require claim groups:GROUP_ID

Use GitHub Repository

https://github.com/Amancs1541/ODIC-Authentication.git