Azure Active Directory and Key Vault Configuration
==================================================

This section provides a step-by-step guide to configure Azure Active Directory (Entra ID)
for the Influxion API and client application, and to grant Influxion access to Azure Key Vault
using a managed identity.

Register the Influxion API application
---------------------------------------

1. In the Azure portal, navigate to **Entra ID** → **App registrations** → **New registration**.
2. Enter a name (e.g., **Influxion API**).
3. Select supported account types (single-tenant or multi-tenant) as appropriate.
4. Click **Register**.

Define API permissions (scopes)
--------------------------------

1. In the **Influxion API** registration, go to **Expose an API**.
2. Under **Application ID URI**, click **Set**, and accept the default (e.g., ``api://<client-id>``) or customize.
3. Click **Add a scope** and configure:

   - **Scope name**: ``access_as_user``
   - **Who can consent**: Admins and users
   - **Admin consent display name**: Allow the app to call Influxion API
   - **Admin consent description**: Allows the app to call the Influxion API on the user’s behalf.

4. Click **Add scope**.
5. Note the full scope value: ``api://<client-id>/access_as_user``. Later on we will use
   ``api://<client-id>/.default`` as the default scope for token validation. We will also use the
   Application (client) ID of this one for the ``INFLUXION_AZURE_API_CLIENT_ID`` environment variable during
   deployment.

Register the Influxion client application
-----------------------------------------

1. In **App registrations**, click **New registration** and name it (e.g., **Influxion Client**).
2. After registering, select **API permissions** → **Add a permission**.
3. Choose **My APIs**, select **Influxion API**, and choose the ``access_as_user`` scope.
4. (Optional) Under **Certificates & secrets**, configure a client secret or certificate.
5. Note the **Application (client) ID** and the **Client secret** for environment variables.

Configure environment variables
-------------------------------

Add the following variables to your environment or `.env` file (see :doc:`environment`):

.. list-table::
   :header-rows: 1
   :widths: 20 80

   * - Environment Variable
     - Description
   * - ``INFLUXION_AZURE_TENANT_ID``
     - Azure tenant (directory) ID where the applications are registered.
   * - ``INFLUXION_AZURE_API_CLIENT_ID``
     - Client ID of the Influxion API application. Needed for token audience validation.
   * - ``INFLUXION_AZURE_AUDIENCE``
     - Application (client) ID URI of the Influxion API (e.g., ``api://<client-id>``).
   * - ``INFLUXION_AZURE_DEFAULT_SCOPE``
     - Default OAuth2 scope for validating inbound tokens (e.g., ``api://<client-id>/.default``).
   * - ``INFLUXION_VAULT_URL``
     - Azure Key Vault URL for signing certificates.
   * - ``INFLUXION_AZURE_CLIENT_ID``
     - Client ID of the managed identity or service principal (omit if using system-assigned identity).
   * - ``INFLUXION_AZURE_CLIENT_SECRET``
     - Client secret (only if not using managed identity).

Enable managed identity and grant Key Vault access
--------------------------------------------------

To allow Influxion to retrieve certificates from Key Vault without exposing secrets:

1. Deploy Influxion to your hosting environment (e.g., App Service, Function App, VM).
2. Enable the **System-assigned managed identity** for that resource.
3. In **Azure Key Vault**, assign an access policy (or RBAC role) to the managed identity with **Get** permission on secrets.
4. Do **not** grant Key Vault permissions to the Influxion Client application.

Authentication flow
-------------------

1. The Influxion Client requests an access token from Azure AD using the audience and scope.
2. The client calls the Influxion API with the token in the ``Authorization`` header.
3. Influxion validates the token based on the configured audience and default scope.
4. If signing is requested, Influxion retrieves the certificate from Key Vault using its managed identity.