Microsoft Entra ID (Azure AD)

This page describes basically how to configure Microsoft Entra ID - previously known as Azure Active Directory - and mod_auth_openidc.

However, some details depend on your application served by your Apache2.

---

TL;DR

Authenticating against your Microsoft Entra ID / Azure AD is fairly straight-forward, but requires that you know a few things.

Most of your URLs and other things you'll need can be found by hitting a JSON endpoint that's specific to your Azure AD Directory (tenant): https://login.microsoftonline.com/[TENANT_GUID]/v2.0/.well-known/openid-configuration

Note that using older URLs like sts.windows.net and without the v2.0 is not recommended because they lack features or interoperability

We'll go over how to get the information you need here.

1. Your tenant_id can be found in your Azure Portal AD Settings Page. It will be referred to as the Directory ID
2. Your app_id. This you get when you create a new App in the Azure Portal. We will need this in module configuration as OIDCClientID
3. Your app's client_secret. You'll get this when you go through setting up the rest of the newly registered App you just created. It will be referred to as the OIDCClientSecret in our module configuration.
4. The some_custom_passphrase should be something you generate that's lengthy and specific to your server. Generally, this is some 32-character long thing, like: ZasT5bgtwzA4RKcGPz68wvWVtBj8dzwV or some such.
5. Add upn to your Token configuration. We will need it for OIDCRemoteUserClaim in module configuration.

Configure Entra ID / Azure

Create new Application

Login to https://aad.portal.azure.com (or https://portal.azure.com)

App registrations

• New application registration

• Choose any name that fits for your
• Choose the account type for your environment
• Reply URI
  • Web
  • The URI must match the OIDCRedirectUri you configure in mod_auth_openidc later

Hit button "Register"

Overview

• Application ID will be used as OIDCClientID in module configuration
• Directory (tenant) ID will be needed for your module configuration

Manage > Certificates & secrets

• New Client Secret

• Enter a description
• Choose a expiration duration

Hit button "Add"

*** Copy that value (key) *** You will never see it again !!! This will be used as OIDCClientSecret in module configuration later

Manage > Token configuration

• Add optional claim

• Token Type: ID
• Select upn

Click button "Add"

• Confirm Turn on the Microsoft Graph profile permission (required for claims to appear in token).

Click button "Add"

Apache Configuration

You use the above pieces of information to create your OpenIDC configuration in your Apache config file (generally within a VirtualHost directive) like so:

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

OIDCRedirectURI https://[APACHE_FQDN]/secure/redirect_uri
# This must match the Redirect URI of Azure configuration above

OIDCClientID [app_id]
OIDCClientSecret [app_password]
OIDCCryptoPassphrase [some_custom_passphrase]

OIDCScope "openid profile" // add offline_access for a refresh token
OIDCRemoteUserClaim upn

Then use your config in Location or Directory directives as follows:

<Location /secure>
    SSLRequireSSL
    SSLOptions +StdEnvVars

    AuthType openid-connect
    require valid-user

    Options Includes FollowSymLinks
    AllowOverride AuthConfig Limit
    Order allow,deny
    Allow from all
</Location>

Authorization

This is even more depending on your application, Azure environment, ... Thus it is hard to describe a generic valid approach...

Group Authorization

If you added groups to the claim, you can use these to control access by modifying a Location section to suit:

    <Location />
       AuthType openid-connect
       Require claim groups:mygroup
    </Location>

The group name is the sAmAccountName. Of course this can be adjusted in the claim as needed.

Customizing Claims

You may be able to customize claims returned by Entra ID / Azure https://docs.microsoft.com/en-us/azure/active-directory/develop/active-directory-claims-mapping to add additional information.

Example: Adding groups to claims in Entra ID / Azure

1. Open app registration created earlier
2. Go to Manager > Token configuration
3. • Add groups claims
4. Select the groups you want to add and select format (Group Id, sAMAccountName, ...).
5. Click on "Add" button