Onboarding: Microsoft Entra ID
================================

Your Airflow instance can be secured either through the platform's shared
Keycloak realm (see :doc:`../sovereign-data-platform/getting-started`), or,
if your organization prefers to manage access from its own Azure tenant,
through **Microsoft Entra ID** directly. Here's how to onboard Entra ID.

.. container:: entra-i18n
   :name: entra-i18n

   .. container::
      :name: entra-i18n-label

      Customer name

   .. container::
      :name: entra-i18n-placeholder

      e.g. acme

   .. container::
      :name: entra-i18n-copy

      Copy

   .. container::
      :name: entra-i18n-copied

      Copied

   .. container::
      :name: entra-i18n-prefix

      Your Airflow URL:

   .. container::
      :name: entra-i18n-dev

      Dev

   .. container::
      :name: entra-i18n-prod

      Prod

.. raw:: html

   <div class="entra-url-builder">
     <div class="entra-url-builder__row">
       <label id="entra-org-label" for="entra-org-input" class="entra-url-builder__label"></label>
       <input id="entra-org-input" type="text" class="entra-url-builder__input" autocomplete="off" spellcheck="false">
       <div class="entra-url-builder__env" role="group" id="entra-env-group">
         <button type="button" class="entra-url-builder__env-btn" id="entra-env-dev" data-env="dev"></button>
         <button type="button" class="entra-url-builder__env-btn" id="entra-env-prod" data-env="prod"></button>
       </div>
     </div>
     <p class="entra-url-builder__output-row">
       <span id="entra-url-prefix"></span><code id="entra-url-output" class="entra-url-builder__output"></code>
       <button type="button" id="entra-url-copy" class="entra-url-builder__copy"></button>
     </p>
   </div>
   <style>
     /* Real, gettext-translatable RST content (see the .. container::
        block above) rather than strings hardcoded in this script --
        translators edit the .po catalog like any other string on this
        page, instead of a second, JS-only copy of the same text. Hidden
        here purely for layout; the content itself is real page text. */
     .entra-i18n {
       display: none;
     }
     .entra-url-builder {
       margin: 1.5rem 0;
       padding: 1rem 1.25rem;
       border: 1px solid var(--color-background-border);
       border-radius: var(--sd-radius, 8px);
       background: var(--color-background-secondary);
     }
     .entra-url-builder__row {
       display: flex;
       align-items: center;
       gap: 0.75rem;
       flex-wrap: wrap;
     }
     .entra-url-builder__label {
       font-family: var(--font-stack--monospace);
       font-size: 0.85rem;
       font-weight: 600;
       color: var(--color-foreground-primary);
     }
     .entra-url-builder__input {
       flex: 1 1 12rem;
       min-width: 10rem;
       padding: 0.4rem 0.6rem;
       border-radius: 6px;
       border: 1px solid var(--color-background-border);
       background: var(--color-background-primary);
       color: var(--color-foreground-primary);
       font-family: var(--font-stack);
       font-size: 0.9rem;
     }
     .entra-url-builder__input:focus {
       outline: 2px solid var(--color-brand-content);
       outline-offset: 1px;
     }
     .entra-url-builder__env {
       display: inline-flex;
       border: 1px solid var(--color-background-border);
       border-radius: 6px;
       overflow: hidden;
     }
     .entra-url-builder__env-btn {
       border: none;
       background: var(--color-background-primary);
       color: var(--color-foreground-primary);
       padding: 0.4rem 0.75rem;
       font-size: 0.82rem;
       font-family: var(--font-stack--monospace);
       cursor: pointer;
     }
     .entra-url-builder__env-btn + .entra-url-builder__env-btn {
       border-left: 1px solid var(--color-background-border);
     }
     .entra-url-builder__env-btn:hover {
       color: var(--color-brand-content);
     }
     .entra-url-builder__env-btn[aria-pressed="true"] {
       background: var(--color-brand-content);
       color: var(--color-background-primary);
     }
     .entra-url-builder__output-row {
       margin: 0.75rem 0 0;
       display: flex;
       align-items: center;
       gap: 0.6rem;
       flex-wrap: wrap;
     }
     .entra-url-builder__output {
       font-family: var(--font-stack--monospace);
       font-size: 0.88rem;
       color: var(--color-brand-content);
       word-break: break-all;
     }
     #entra-url-prefix::after {
       content: " ";
     }
     .entra-url-builder__copy {
       border: 1px solid var(--color-background-border);
       background: var(--color-background-primary);
       color: var(--color-foreground-primary);
       border-radius: 6px;
       padding: 0.25rem 0.6rem;
       font-size: 0.78rem;
       cursor: pointer;
       font-family: var(--font-stack);
     }
     .entra-url-builder__copy:hover {
       border-color: var(--color-brand-content);
     }
   </style>
   <script>
     (function () {
       // This block sits right after the intro paragraph, above the
       // numbered steps further down the page -- run at parse time (the
       // default for an inline, non-deferred <script>), it would execute
       // before the browser's streaming HTML parser has even reached
       // those steps, so `document.querySelectorAll("code.literal")`
       // below would find zero of them (the widget's own elements still
       // work, since those are defined above this script). Deferring to
       // DOMContentLoaded guarantees the whole page, steps included, is
       // in the DOM first.
       function init() {
       // Pulls its label/button text from the hidden, real, translated
       // RST content added above (ids "entra-i18n-*") instead of
       // deciding the language itself -- whatever the .po catalog says
       // for this page is what shows up here too, same as any other
       // text on the page.
       function i18n(id) {
         var el = document.getElementById(id);
         return el ? el.textContent.trim() : "";
       }
       var strings = {
         label: i18n("entra-i18n-label"),
         placeholder: i18n("entra-i18n-placeholder"),
         copy: i18n("entra-i18n-copy"),
         copied: i18n("entra-i18n-copied"),
         prefix: i18n("entra-i18n-prefix"),
         dev: i18n("entra-i18n-dev"),
         prod: i18n("entra-i18n-prod")
       };

       var input = document.getElementById("entra-org-input");
       var output = document.getElementById("entra-url-output");
       var label = document.getElementById("entra-org-label");
       var prefix = document.getElementById("entra-url-prefix");
       var copyBtn = document.getElementById("entra-url-copy");
       var devBtn = document.getElementById("entra-env-dev");
       var prodBtn = document.getElementById("entra-env-prod");
       if (!input || !output || !label || !prefix || !copyBtn || !devBtn || !prodBtn) {
         return;
       }

       label.textContent = strings.label;
       input.placeholder = strings.placeholder;
       prefix.textContent = strings.prefix;
       copyBtn.textContent = strings.copy;
       devBtn.textContent = strings.dev;
       prodBtn.textContent = strings.prod;

       var env = "prod";

       function setEnv(next) {
         env = next === "dev" ? "dev" : "prod";
         devBtn.setAttribute("aria-pressed", String(env === "dev"));
         prodBtn.setAttribute("aria-pressed", String(env === "prod"));
         try {
           localStorage.setItem("entra-onboarding-env", env);
         } catch (e) {}
         render();
       }

       devBtn.addEventListener("click", function () {
         setEnv("dev");
       });
       prodBtn.addEventListener("click", function () {
         setEnv("prod");
       });

       function slugify(value) {
         return value
           .toLowerCase()
           .normalize("NFKD")
           .replace(/[\u0300-\u036f]/g, "")
           .replace(/[^a-z0-9]+/g, "-")
           .replace(/^-+|-+$/g, "");
       }

       // The numbered steps below reference the Airflow URL twice, as a
       // literal (``https://<your-organization>...``) -- found here by
       // pattern-matching the rendered placeholder rather than by id,
       // so translated pages (whose literal text reads
       // "<uw-organisatie>" instead) are picked up the same way, with no
       // separate localization of this script needed. Each match's
       // original text is captured once, up front, so clearing the
       // input field can restore the exact original placeholder.
       var urlPattern = /^https:\/\/<([^>]+)>\.(?:dev\.)?airflow\.datafoundation\.eu$/;
       var urlNodes = [];
       Array.prototype.forEach.call(document.querySelectorAll("code.literal"), function (el) {
         var match = el.textContent.match(urlPattern);
         if (match) {
           urlNodes.push({ el: el, placeholder: match[1] });
         }
       });

       function render() {
         var slug = slugify(input.value);
         var domain = env === "dev" ? "dev.airflow.datafoundation.eu" : "airflow.datafoundation.eu";
         // Reuses the same "<placeholder>" text already extracted from
         // the numbered steps below (real, translated page content)
         // instead of a second hardcoded copy of it here.
         var fallback = urlNodes.length ? urlNodes[0].placeholder : "your-organization";
         output.textContent = "https://" + (slug || fallback) + "." + domain;

         urlNodes.forEach(function (node) {
           var host = slug || "<" + node.placeholder + ">";
           node.el.textContent = "https://" + host + "." + domain;
         });
       }

       var saved = "";
       try {
         saved = localStorage.getItem("entra-onboarding-org") || "";
       } catch (e) {}
       input.value = saved;

       var savedEnv = "prod";
       try {
         savedEnv = localStorage.getItem("entra-onboarding-env") || "prod";
       } catch (e) {}
       setEnv(savedEnv);

       input.addEventListener("input", function () {
         try {
           localStorage.setItem("entra-onboarding-org", input.value);
         } catch (e) {}
         render();
       });

       copyBtn.addEventListener("click", function () {
         if (!navigator.clipboard) {
           return;
         }
         navigator.clipboard.writeText(output.textContent).then(function () {
           var original = copyBtn.textContent;
           copyBtn.textContent = strings.copied;
           setTimeout(function () {
             copyBtn.textContent = original;
           }, 1500);
         });
       });
       }

       if (document.readyState === "loading") {
         document.addEventListener("DOMContentLoaded", init);
       } else {
         init();
       }
     })();
   </script>

Prerequisites
--------------

Onboarding must be done by an administrator holding the Azure role
**Cloud Application Administrator** in your organization's tenant.

Onboarding instructions
--------------------------

1. Open your Airflow URL — ``https://<your-organization>.airflow.datafoundation.eu``.
   This shows the sign-in screen:

   .. image:: /_static/img/entra-id-onboarding/01-sign-in-screen.png
      :alt: Airflow sign-in screen with a "Sign In with azure" button
      :width: 700px

2. Click **Sign In with azure**. Choose the account with the
   **Cloud Application Administrator** role.

3. Select the checkbox **Consent on behalf of your organization**, then
   click **Accept** to grant the permissions request:

   .. image:: /_static/img/entra-id-onboarding/02-consent-on-behalf-of-organization.png
      :alt: Microsoft permissions-requested dialog with "Consent on behalf of your organization" checked
      :width: 700px

4. After this first login, Airflow shows **403 Forbidden**. That's
   expected, since the account doesn't have any role assigned within
   Airflow yet:

   .. image:: /_static/img/entra-id-onboarding/03-403-forbidden.png
      :alt: Airflow welcome page showing a 403 Forbidden error in the History panel
      :width: 700px

5. Open `portal.azure.com <https://portal.azure.com>`_ using the same
   **Cloud Application Administrator** account. Open **Microsoft Entra ID**,
   then **Enterprise Applications**:

   .. image:: /_static/img/entra-id-onboarding/04-entra-id-enterprise-applications.png
      :alt: Microsoft Entra ID Overview page with Enterprise applications highlighted in the sidebar
      :width: 700px

6. Search for **airflow**, click the Airflow application, then click
   **Manage** → **Users and groups**:

   .. image:: /_static/img/entra-id-onboarding/05-users-and-groups.png
      :alt: Enterprise applications search results showing the airflow application
      :width: 700px

7. Your account has the role **Default Access** (see "Role assigned").
   Select the checkbox for the user, then click **Edit assignment**:

   .. image:: /_static/img/entra-id-onboarding/06-edit-assignment.png
      :alt: Users and groups page for the airflow enterprise application, with Edit assignment highlighted
      :width: 700px

   .. image:: /_static/img/entra-id-onboarding/07-edit-assignment-panel.png
      :alt: Edit Assignment panel with "Select a role" showing None Selected
      :width: 500px

8. Select the **Airflow Admin** role for your **Cloud Application
   Administrator** account:

   .. image:: /_static/img/entra-id-onboarding/08-select-airflow-admin-role.png
      :alt: Select a role panel listing the Airflow Admin and Airflow Users app roles
      :width: 700px

   .. note::
      A user can hold multiple roles. **Airflow Users** is a subset of
      **Airflow Admin**.

9. To force role synchronization, log out of the Airflow application after
   the role assignment:

   .. image:: /_static/img/entra-id-onboarding/09-logout-airflow.png
      :alt: Airflow user menu with Logout highlighted
      :width: 500px

10. Wait a few minutes, then log back into Airflow at
    ``https://<your-organization>.airflow.datafoundation.eu``. Role
    synchronization can take up to 15 minutes; once it completes and you've
    re-logged in, the 403 Forbidden error is gone:

    .. image:: /_static/img/entra-id-onboarding/10-successful-login.png
       :alt: Airflow Dags page loading successfully with no errors
       :width: 700px

11. Assign the **Airflow User** role to the rest of the Airflow developers
    in your organization the same way, directly in the Azure portal
    (preferably via a user group). See :doc:`permissions` for what each
    role can do and how to manage assignments afterwards.