Project

General

Profile

Wiki » Microsoft Entra ID »

Entra ID OAuth2 Provisioning Ansible Role

This role automates the creation and management of Microsoft Entra ID (Azure AD) OAuth2 application credentials for sites protected by SSO in the reverse-proxy environment.
It discovers which sites require OAuth2, provisions or updates the necessary identity resources in Entra ID, generates client secrets, and injects those secrets back into the site definitions so that the oauth2_proxy_setup downstream role can complete OAuth2 Proxy and Nginx SSO configuration.

This role acts as the identity provisioning layer in the SSO pipeline.

1. Role Purpose and Responsibilities

This role manages all Azure-side identity operations required for OAuth2-enabled sites, including:

  • Identifying which reverse-proxy sites use OAuth2
  • Creating or validating the Entra ID application for each site
  • Generating client secrets with a controlled expiry
  • Logging into Azure using a service principal
  • Returning a complete site definition list that includes generated secrets
  • Preparing the data needed by the oauth2_proxy_setup role to finalize SSO configuration

It abstracts away the complexities of Azure application registration and ensures consistent, repeatable identity provisioning.

2. High-Level Workflow

Below is the end-to-end flow of the role, from site discovery to generating usable OAuth2 credentials for downstream roles.

                     +--------------------------------+
                     |  rproxy_setup_sites (input)    |
                     |  list of reverse-proxy sites   |
                     +-----------------+--------------+
                                       |
                                       v
                    +------------------+------------------+
                    | Filter sites requiring OAuth2       |
                    | use_oauth2: true                    |
                    +------------------+------------------+
                                       |
                                       v
                 +---------------------+----------------------+
                 | Create/validate Entra ID app for each site |
                 |   - Uses azure.azcollection                |
                 +---------------------+----------------------+
                                       |
                                       v
                 +---------------------+----------------------+
                 | Login to Azure using service principal     |
                 |   - Stores token under ~/.azure            |
                 +---------------------+----------------------+
                                       |
                                       v
                 +---------------------+----------------------+
                 | Generate client secrets for each site      |
                 |   - Uses Azure CLI                         |
                 +---------------------+----------------------+
                                       |
                                       v
         +------------------------------+-------------------------------+
         | Append generated secrets into site definitions               |
         | Produces: entra_id_oauth2_updated_sites                      |
         +------------------------------+-------------------------------+
                                       |
                                       v
           +---------------------------+-----------------------------+
           | Downstream role: oauth2_proxy_setup                      |
           | Uses updated site list to configure OAuth2 Proxy + Nginx |
           +---------------------------------------------------------+

3. Required Variables (Per-Site)

Each site that needs OAuth2 must define the following fields inside the master variable:
rproxy_setup_sites.

These values describe how the site integrates with Entra ID via OAuth2 Proxy.

Example Entry

rproxy_setup_sites:
  - server_name: code.refol.us
    port: 8000
    proxy_pass: "http://{{ global_ip_addresses[groups['code_server'][0]] }}"
    allow_list:
      - 192.168.0.0/24
      - 192.168.2.0/24
      - 24.105.250.200
      - 70.107.117.124
    restricted: false
    enable: true

    # OAuth2 integration
    use_oauth2: true
    oauth2_provider: "entra-id"
    oauth2_scope: "openid profile email"
    oauth2_cookie_secret: "base64-random-32-bytes"
    oauth2_client_id: "uuid-for-site"          # pre-generated via uuidgen
    oauth2_callback_url: "https://code.refol.us/oauth2/callback"
    oauth2_client_secret: ""                   # generated by this role
    oauth2_email_domains: "*"

Required Values

Field Purpose
use_oauth2 Marks the site as requiring OAuth2 SSO
oauth2_client_id Pre-created application ID (e.g., generated via uuidgen)
oauth2_callback_url Must match Entra ID's redirect URI
oauth2_scope Requested scopes (usually openid profile email)
oauth2_email_domains Allowed login domains
oauth2_cookie_secret Base64-encoded 32-byte random string for cookie encryption
oauth2_client_secret Left blank → filled in by this role

Only sites with use_oauth2: true are processed.

4. Prerequisites

This role interacts directly with Azure, and therefore requires:

4.1 Azure Service Principal (Required)

The role requires a dedicated service principal with permissions to:

  • Create and manage Azure AD applications
  • Generate client secrets

The Create a Service Principal in Microsoft Entra ID page details on creating a service principal.

4.2 Global Role Variables

The following Global Role variables are referenced. These are located in the global role vault.

global_azure_sp_client_id: "<service_principal_client_id>"
global_azure_sp_secret: "<service_principal_secret>"
global_azure_tenant: "<tenant_id>"

4.3 Azure Ansible Collection

Used to create or update Entra ID applications:

ansible-galaxy collection install azure.azcollection

The role automatically installs the supporting Python requirements into the virtual environment.

4.4 Azure CLI (azure-cli)

Used for secret generation and service principal login. Azure CLI is installed using the azure_cli_setup role. The az command is used to interface with Azure to perform authentication and generating secrets.

az login --service-principal \
  --username <client_id> \
  --password <client_secret> \
  --tenant <tenant_id>

This writes a token cache under ~/.azure.

Note

Although azure_rm_adapplication can be used to perform authentication and
generating secrets it did not perform as expected. Therefore the az command
is used instead.

4.4 Python 3 Virtual Environment

The role installs all Azure modules into a dedicated venv defined by:

python3_venv_folder
python3_version

This ensures dependency isolation.

5. Output of the Role

5.1 entra_id_oauth2_updated_sites

This is the final updated version of rproxy_setup_sites, containing newly generated client secrets for each OAuth2-enabled site.

Each entry now includes all information required for SSO:

  • Client ID
  • Client secret
  • Scopes
  • Cookie secret
  • Callback URL

This list is the primary output of the role.

6. Downstream Integration (OAuth2 Proxy Setup)

The output variable entra_id_oauth2_updated_sites is consumed by the
oauth2_proxy_setup role, which uses it to:

  • Render OAuth2 Proxy configuration (*.cfg)
  • Insert client secrets and provider configuration
  • Configure Nginx integration with OAuth2 Proxy
  • Finalize the SSO flow for each protected site

➡️ This role provisions identity; the next role activates it.
Together, they form a fully automated, consistent, and secure OAuth2 SSO deployment pipeline across the homelab reverse proxy cluster.