From d344a70de4a3c00ccf4f8a2a75611aac3aa9943d Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Fabrice=20Flore-Th=C3=A9bault?= Date: Fri, 13 Jun 2025 17:38:59 +0200 Subject: [PATCH 01/27] RHIDP-7833 Follow more logical user flow for authenticating with Azure MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit Signed-off-by: Fabrice Flore-Thébault Update modules/authentication/proc-enabling-user-authentication-with-microsoft-azure.adoc --- ...y-authenticating-with-microsoft-azure.adoc | 13 - .../assembly-enabling-authentication.adoc | 2 +- ...-authentication-and-user-provisioning.adoc | 2 +- ...g-authentication-with-microsoft-azure.adoc | 172 ------- ...r-authentication-with-microsoft-azure.adoc | 480 ++++++++++++++++++ ...crosoft-azure-to-the-software-catalog.adoc | 268 ---------- .../snip-technology-preview.adoc | 0 7 files changed, 482 insertions(+), 455 deletions(-) delete mode 100644 assemblies/assembly-authenticating-with-microsoft-azure.adoc delete mode 100644 modules/authentication/proc-enabling-authentication-with-microsoft-azure.adoc create mode 100644 modules/authentication/proc-enabling-user-authentication-with-microsoft-azure.adoc delete mode 100644 modules/authentication/proc-provisioning-users-from-microsoft-azure-to-the-software-catalog.adoc rename {artifacts => modules}/snip-technology-preview.adoc (100%) diff --git a/assemblies/assembly-authenticating-with-microsoft-azure.adoc b/assemblies/assembly-authenticating-with-microsoft-azure.adoc deleted file mode 100644 index d575ae393e..0000000000 --- a/assemblies/assembly-authenticating-with-microsoft-azure.adoc +++ /dev/null @@ -1,13 +0,0 @@ -[id="assembly-authenticating-with-microsoft-azure"] -= Authentication with Microsoft Azure - -To authenticate users with Microsoft Azure: - -. xref:enabling-authentication-with-microsoft-azure[Enable authentication with Microsoft Azure]. -. xref:provisioning-users-from-microsoft-azure-to-the-software-catalog[Provision users from Microsoft Azure to the software catalog]. - -include::modules/authentication/proc-enabling-authentication-with-microsoft-azure.adoc[leveloffset=+1] - - -include::modules/authentication/proc-provisioning-users-from-microsoft-azure-to-the-software-catalog.adoc[leveloffset=+1] - diff --git a/assemblies/assembly-enabling-authentication.adoc b/assemblies/assembly-enabling-authentication.adoc index b1b4f77f86..5791888b45 100644 --- a/assemblies/assembly-enabling-authentication.adoc +++ b/assemblies/assembly-enabling-authentication.adoc @@ -16,5 +16,5 @@ include::assembly-authenticating-with-rhbk.adoc[leveloffset=+1] include::assembly-authenticating-with-github.adoc[leveloffset=+1] -include::assembly-authenticating-with-microsoft-azure.adoc[leveloffset=+1] +include::modules/authentication/proc-enabling-user-authentication-with-microsoft-azure.adoc[leveloffset=+1] diff --git a/modules/authentication/con-understanding-authentication-and-user-provisioning.adoc b/modules/authentication/con-understanding-authentication-and-user-provisioning.adoc index e8dc60f009..81c6a1ff5f 100644 --- a/modules/authentication/con-understanding-authentication-and-user-provisioning.adoc +++ b/modules/authentication/con-understanding-authentication-and-user-provisioning.adoc @@ -9,7 +9,7 @@ Catalog provider plugins handle this task asynchronously. These plugins query the Identity Provider (IdP) for relevant user and group information, and create or update corresponding entities in the {product-short} catalog. Scheduled provisioning ensures that the catalog accurately reflects the users and groups in your organization. -When a user attempts to access {product-short}, {product-short} redirects them to a configured authentication provider, such as xref:assembly-authenticating-with-rhbk[{rhbk-brand-name} ({rhbk})], xref:authenticating-with-github[GitHub], or xref:assembly-authenticating-with-microsoft-azure[{azure-brand-name}]. +When a user attempts to access {product-short}, {product-short} redirects them to a configured authentication provider, such as xref:assembly-authenticating-with-rhbk[{rhbk-brand-name} ({rhbk})], xref:authenticating-with-github[GitHub], or xref:enabling-user-authentication-with-microsoft-azure[{azure-brand-name}]. This external IdP is responsible for authenticating the user. On successful authentication, the {product-short} authentication plugin, configured in your `{my-app-config-file}` file, processes the response from the IdP, resolves the identity in the {product-short} software catalog, and establishes a user session within {product-short}. diff --git a/modules/authentication/proc-enabling-authentication-with-microsoft-azure.adoc b/modules/authentication/proc-enabling-authentication-with-microsoft-azure.adoc deleted file mode 100644 index 5eb5b8c634..0000000000 --- a/modules/authentication/proc-enabling-authentication-with-microsoft-azure.adoc +++ /dev/null @@ -1,172 +0,0 @@ -[id="enabling-authentication-with-microsoft-azure"] -= Enabling authentication with Microsoft Azure - -{product} includes a Microsoft Azure authentication provider that can authenticate users by using OAuth. - -.Prerequisites -. You have the permission to register an application in Microsoft Azure. -* You link:{configuring-book-url}[added a custom {product-short} application configuration], and have sufficient permissions to modify it. - -.Procedure -. To allow {product-short} to authenticate with Microsoft Azure, link:https://learn.microsoft.com/en-us/entra/identity-platform/scenario-web-app-sign-user-app-registration?tabs=aspnetcore#register-an-app-by-using-the-azure-portal[create an OAuth application in Microsoft Azure]. - -.. In the Azure portal go to link:https://portal.azure.com/#view/Microsoft_AAD_RegisteredApps/ApplicationsListBlade[*App registrations*], create a **New registration** with the configuration: -+ -**Name**:: The application name in Azure, such as ____. - -.. On the *Home > App registrations > ____ > Manage > Authentication* page, *Add a platform*, with the following configuration: - -*Redirect URI*:: Enter the backend authentication URI set in {product-short}: `pass:c,a,q[{my-product-url}/api/auth/microsoft/handler/frame]` -*Front-channel logout URL*:: Leave blank. -*Implicit grant and hybrid flows*:: Leave all checkboxes cleared. - -.. On the *Home > App registrations > ____ > Manage > API permissions* page, *Add a Permission*, then add the following *Delegated permission* for the *Microsoft Graph API*: -+ -* `email` -* `offline_access` -* `openid` -* `profile` -* `User.Read.All` -* `GroupMember.Read.All` -* Optional custom scopes for the Microsoft Graph API that you define both in this section and in the `{my-app-config-file}` {product-short} configuration file. -[NOTE] -==== -Your company might require you to grant admin consent for these permissions. -Even if your company does not require admin consent, you might do so as it means users do not need to individually consent the first time they access backstage. -To grant administrator consent, a directory administrator must go to the link:https://learn.microsoft.com/en-us/azure/active-directory/manage-apps/user-admin-consent-overview[admin consent] page and click *Grant admin consent for COMPANY NAME*. -==== - - -.. On the *Home > App registrations > ____ > Manage > Certificates & Secrets* page, in the *Client secrets* tab, create a *New client secret*. - -.. Save for the next step: -- **Directory (tenant) ID** -- **Application (client) ID** -- **Application (client) secret** - -. To add your Microsoft Azure credentials to {product-short}, add the following key/value pairs to link:{configuring-dynamic-plugins-book-url}#provisioning-your-custom-configuration[your {product-short} secrets]: -+ -`AUTH_AZURE_TENANT_ID`:: Enter your saved *Directory (tenant) ID*. -`AUTH_AZURE_CLIENT_ID`:: Enter your saved *Application (client) ID*. -`AUTH_AZURE_CLIENT_SECRET`:: Enter your saved *Application (client) secret*. - -. Set up the Microsoft Azure authentication provider in your `{my-app-config-file}` file: -+ -.`{my-app-config-file}` file fragment -[source,yaml,subs="+quotes,+attributes"] ----- -auth: - environment: production # <1> - providers: - microsoft: - production: - clientId: ${AUTH_AZURE_CLIENT_ID} # <2> - clientSecret: ${AUTH_AZURE_CLIENT_SECRET} - tenantId: ${AUTH_AZURE_TENANT_ID} -signInPage: microsoft # <3> ----- -<1> Mark the environment as production and disable the **Guest** login option in the {product-short} login page. -<2> Apply the Microsoft Azure credentials configured in your {product-short} secrets. -<3> Set the Microsoft Azure provider as your {product-short} sign-in provider. - -.. Optional: Consider adding following optional fields: - -`domainHint`:: -Optional for single-tenant applications. -You can reduce login friction for users with accounts in multiple tenants by automatically filtering out accounts from other tenants. -If you want to use this parameter for a single-tenant application, uncomment and enter the tenant ID. -If your application registration is multi-tenant, leave this parameter blank. -For more information, see link:https://learn.microsoft.com/en-us/azure/active-directory/manage-apps/home-realm-discovery-policy[Home Realm Discovery]. -+ -.`{my-app-config-file}` file fragment with optional `domainHint` field -[source,yaml,subs="+quotes,+attributes"] ----- -auth: - environment: production - providers: - microsoft: - production: - domainHint: ${AUTH_AZURE_TENANT_ID} ----- - -`additionalScopes`:: -Optional for additional scopes. -To add scopes for the application registration, uncomment and enter the list of scopes that you want to add. -The default and mandatory value lists: `'openid', 'offline_access', 'profile', 'email', 'User.Read'`. -+ -.`{my-app-config-file}` file fragment with optional `additionalScopes` field -[source,yaml,subs="+quotes,+attributes"] ----- -auth: - environment: production - providers: - microsoft: - production: - additionalScopes: - - Mail.Send ----- - -`sessionDuration`:: -Lifespan of the user session. -Enter a duration in `ms` library format (such as '24h', '2 days'), ISO duration, or "human duration" as used in code. -+ -.`app-config-rhdh.yaml` fragment with optional `sessionDuration` field -[source,yaml,subs="+quotes"] ----- -auth: - providers: - microsoft: - production: - sessionDuration: { hours: 24 } ----- - -`signIn` :: - -`resolvers`::: -After successful authentication, the user signing in must be resolved to an existing user in the {product-short} catalog. To best match users securely for your use case, consider configuring a specific resolver. Enter the resolver list to override the default resolver: `emailLocalPartMatchingUserEntityName`. -+ -The authentication provider tries each sign-in resolver in order until it succeeds, and fails if none succeed. -+ -WARNING: In production mode, only configure one resolver to ensure users are securely matched. - -`resolver`:::: -Enter the sign-in resolver name. -Available resolvers: - -* `userIdMatchingUserEntityAnnotation` -* `emailLocalPartMatchingUserEntityName` -* `emailMatchingUserEntityProfileEmail` - -`dangerouslyAllowSignInWithoutUserInCatalog: true`:::: -Configure the sign-in resolver to bypass the user provisioning requirement in the {product-short} software catalog. -+ -WARNING: Use `dangerouslyAllowSignInWithoutUserInCatalog` to explore {product-short} features, but do not use it in production. -+ -.`app-config-rhdh.yaml` fragment with optional field to allow signing in users absent from the software catalog -[source,yaml] ----- -auth: - environment: production - providers: - microsoft: - production: - clientId: ${AUTH_AZURE_CLIENT_ID} - clientSecret: ${AUTH_AZURE_CLIENT_SECRET} - tenantId: ${AUTH_AZURE_TENANT_ID} - signIn: - resolvers: - - resolver: usernameMatchingUserEntityName - dangerouslyAllowSignInWithoutUserInCatalog: true -signInPage: microsoft ----- - -[NOTE] -==== -This step is optional for environments with outgoing access restrictions, such as firewall rules. - If your environment has such restrictions, ensure that your {product-very-short} backend can access the following hosts: - -* `login.microsoftonline.com`: For obtaining and exchanging authorization codes and access tokens. - -* `graph.microsoft.com`: For retrieving user profile information (as referenced in the source code). -If this host is unreachable, you might see an _Authentication failed, failed to fetch user profile_ error when attempting to log in. -==== diff --git a/modules/authentication/proc-enabling-user-authentication-with-microsoft-azure.adoc b/modules/authentication/proc-enabling-user-authentication-with-microsoft-azure.adoc new file mode 100644 index 0000000000..2fe8a866ba --- /dev/null +++ b/modules/authentication/proc-enabling-user-authentication-with-microsoft-azure.adoc @@ -0,0 +1,480 @@ +[id="enabling-user-authentication-with-microsoft-azure"] += Enabling user authentication with {azure-brand-name} + +To authenticate users with {azure-brand-name}, configure the {azure-short} authentication provider in {product} and provision the users and groups from {azure-short} to the {product-short} software catalog. + +.Prerequisites +* You have the permission to register an application in {azure-short}. +Alternatively, you can ask your {azure-short} administrator to prepare the required {azure-short} application. + +* You link:{configuring-book-url}[added a custom {product-short} application configuration], and have sufficient permissions to modify it. + +* Your {product-short} backend can access the following hosts: + +`login.microsoftonline.com`:: +For obtaining and exchanging authorization codes and access tokens. + +`graph.microsoft.com`:: +For retrieving user profile information (as referenced in the source code), and avoiding an _Authentication failed, failed to fetch user profile_ error when attempting to log in. + +.Procedure +:my-product-app-name-in-azure: +. To allow {product-short} to authenticate with {azure-brand-name}, link:https://learn.microsoft.com/en-us/entra/identity-platform/scenario-web-app-sign-user-app-registration?tabs=aspnetcore#register-an-app-by-using-the-azure-portal[create an OAuth application in {azure-short}]. + +.. In the {azure-short} portal go to link:https://portal.azure.com/#view/Microsoft_AAD_RegisteredApps/ApplicationsListBlade[*App registrations*], create a **New registration** with the configuration: + +Name:: +Enter a name to identify your application in Azure, such as __{my-product-app-name-in-azure}__. + +.. On the *Home > App registrations > __{my-product-app-name-in-azure}__ > Manage > Authentication* page, *Add a platform*, with the following configuration: + +Redirect URI:: +Enter the backend authentication URI set in {product-short}: `pass:c,a,q[{my-product-url}/api/auth/microsoft/handler/frame]` + +Front-channel logout URL:: +Leave blank. + +Implicit grant and hybrid flows:: +Leave all checkboxes cleared. + +.. On the *Home > App registrations > __My {my-product-app-name-in-azure}__ > Manage > API permissions* page, *Add a Permission*, then add the following *Delegated permission* for the *Microsoft Graph API*: + +* `email` +* `offline_access` +* `openid` +* `profile` +* `User.Read.All` +* `GroupMember.Read.All` +* Optional custom scopes for the Microsoft Graph API that you define both in this section and in the `{my-app-config-file}` {product-short} configuration file. ++ +[NOTE] +==== +Your company might require you to grant admin consent for these permissions. +Even if your company does not require admin consent, you might do so as it means users do not need to individually consent the first time they access backstage. +To grant administrator consent, a directory administrator must go to the link:https://learn.microsoft.com/en-us/azure/active-directory/manage-apps/user-admin-consent-overview[admin consent] page and click *Grant admin consent for COMPANY NAME*. +==== + +.. On the *Home > App registrations > __{my-product-app-name-in-azure}__ > Manage > Certificates & Secrets* page, in the *Client secrets* tab, create a *New client secret*. + +.. Save the following values for the next step: +- **Directory (tenant) ID** +- **Application (client) ID** +- **Application (client) secret** + +. To add your {azure-short} credentials to {product-short}, add the following key/value pairs to link:{configuring-dynamic-plugins-book-url}#provisioning-your-custom-configuration[your {product-short} secrets]: + +`AUTH_AZURE_TENANT_ID`:: +Enter your saved *Directory (tenant) ID*. + +`AUTH_AZURE_CLIENT_ID`:: +Enter your saved *Application (client) ID*. + +`AUTH_AZURE_CLIENT_SECRET`:: +Enter your saved *Application (client) secret*. + +. Enable the Microsoft Graph organization provisioning plugin (`backstage-plugin-catalog-backend-module-msgraph-dynamic`). +This plugin ingests {azure-short} users and groups to the {product-short} software catalog. ++ +.`dynamic-plugins.yaml` file fragment +[source,yaml] +---- +plugins: + - package: './dynamic-plugins/dist/backstage-plugin-catalog-backend-module-msgraph-dynamic' + disabled: false +---- ++ +include::../snip-technology-preview.adoc[] + +. To provision {azure-short} users and groups to the {product-short} software catalog, add the `catalog.providers.microsoftGraphOrg` section to your custom {product-short} `{my-app-config-file}` configuration file: ++ +-- +[id=microsoftGraphOrgProviderId] +.`{my-app-config-file}` fragment with mandatory `microsoftGraphOrg` fields +[source,yaml] +---- +catalog: + providers: + microsoftGraphOrg: + providerId: + target: https://graph.microsoft.com/v1.0 + tenantId: ${AUTH_AZURE_TENANT_ID} + clientId: ${AUTH_AZURE_CLIENT_ID} + clientSecret: ${AUTH_AZURE_CLIENT_SECRET} + schedule: + frequency: + hours: 1 + timeout: + minutes: 50 + initialDelay: + minutes: 50 +---- + +`target`:: +Enter `\https://graph.microsoft.com/v1.0` to define the MSGraph API endpoint the provider is connecting to. +You might change this parameter to use a different version, such as the link:https://learn.microsoft.com/en-us/graph/api/overview?view=graph-rest-beta#call-the-beta-endpoint[beta endpoint]. + +`tenandId`:: +Enter the configured secret variable name: `${AUTHENTICATION_AZURE_TENANT_ID}`. + +`clientId`:: +Enter the configured secret variable name: `${AUTHENTICATION_AZURE_CLIENT_ID}`. + +`clientSecret`:: +Enter the configured secret variable name: `${AUTHENTICATION_AZURE_CLIENT_SECRET}`. + +`schedule`:: + +`frequency`::: +Enter the schedule frequency in the cron, ISO duration, or human duration format. ++ +In a large organization, user provisioning might take a long time, therefore avoid using a low value. + +`timeout`::: +Enter the schedule timeout in the ISO duration or human duration format. ++ +In a large organization, user provisioning might take a long time, therefore avoid using a low value. + +`initialDelay`::: +Enter the schedule initial delay in the ISO duration or human duration format. + +Optional: Consider adding the following optional `microsoftGraphOrg.providerId` fields: + +[id=authority] +`authority`:: +Enter your link:https://learn.microsoft.com/en-us/graph/deployments#app-registration-and-token-service-root-endpoints[{azure-short} authority URL], +when different from the default: `\https://login.microsoftonline.com`. ++ +.`{my-app-config-file}` fragment with optional `queryMode` field +[source,yaml] +---- +catalog: + providers: + microsoftGraphOrg: + providerId: + authority: https://login.microsoftonline.com/ +---- + +[id=queryMode] +`queryMode: basic | advanced`:: +Enter `advanced` when the default `basic` query mode is not sufficient for your queries to the Microsoft Graph API. +See link:https://docs.microsoft.com/en-us/graph/aad-advanced-queries[{azure-brand-name} advanced queries]. ++ +.`{my-app-config-file}` fragment with optional `queryMode` field +[source,yaml] +---- +catalog: + providers: + microsoftGraphOrg: + providerId: + queryMode: advanced +---- + +[id=userExpand] +`user.expand`:: +To include the expanded resource or collection referenced by a single relationship (navigation property) in your results. +Only one relationship can be expanded in a single request. +See https://docs.microsoft.com/en-us/graph/query-parameters#expand-parameter[Microsoft Graph query expand parameter]. +This parameter can be combined with xref:userGroupMemberFilter[`userGroupMember.filter`] or xref:userFilter[`user.filter`]. ++ +.`{my-app-config-file}` fragment with optional `user.expand` field +[source,yaml] +---- +catalog: + providers: + microsoftGraphOrg: + providerId: + user: + expand: manager +---- + +[id=userFilter] +`user.filter`:: +To filter users. +See link:https://docs.microsoft.com/en-us/graph/api/resources/user?view=graph-rest-1.0#properties[Microsoft Graph API] and link:https://docs.microsoft.com/en-us/graph/query-parameters#filter-parameter[Microsoft Graph API query filter parameters syntax]. +This parameter and xref:userGroupMemberFilter[`userGroupMember.filter`] are mutually exclusive, only one can be specified. ++ +.`{my-app-config-file}` fragment with optional `user.filter` field +[source,yaml] +---- +catalog: + providers: + microsoftGraphOrg: + providerId: + user: + filter: accountEnabled eq true and userType eq 'member' +---- + +[id=userLoadPhotos] +`user.loadPhotos: true | false`:: +{product-short} loads photos by default. +Enter `false` to avoid loading user photos. ++ +.`{my-app-config-file}` fragment with optional `user.loadPhotos` field +[source,yaml] +---- +catalog: + providers: + microsoftGraphOrg: + providerId: + user: + loadPhotos: true +---- + +[id=userSelect] +`user.select`:: +Enter the link:https://docs.microsoft.com/en-us/graph/api/resources/schemaextension?view=graph-rest-1.0[Microsoft Graph resource type] list to retrieve. ++ +.`{my-app-config-file}` fragment with optional `user.select` field +[source,yaml] +---- +catalog: + providers: + microsoftGraphOrg: + providerId: + user: + select: ['id', 'displayName', 'description'] +---- + +[id="userGroupMemberFilter"] +`userGroupMember.filter`::: +To use group membership to get users. +To filter groups and fetch their members. +This parameter and xref:userFilter[`user.filter`] are mutually exclusive, only one can be specified. ++ +.`{my-app-config-file}` fragment with optional `userGroupMember.filter` field +[source,yaml] +---- +catalog: + providers: + microsoftGraphOrg: + providerId: + userGroupMember: + filter: "displayName eq 'Backstage Users'" +---- + +[id="userGroupMemberSearch"] +`userGroupMember.search`:: +To use group membership to get users. +To search for groups and fetch their members. +This parameter and xref:userFilter[`user.filter`] are mutually exclusive, only one can be specified. ++ +.`{my-app-config-file}` fragment with optional `userGroupMember.search` field +[source,yaml] +---- +catalog: + providers: + microsoftGraphOrg: + providerId: + userGroupMember: + search: '"description:One" AND ("displayName:Video" OR "displayName:Drive")' +---- + +[id=groupExpand] +`group.expand`:: +Optional parameter to include the expanded resource or collection referenced by a single relationship (navigation property) in your results. +Only one relationship can be expanded in a single request. +See https://docs.microsoft.com/en-us/graph/query-parameters#expand-parameter +This parameter can be combined with xref:userGroupMemberFilter[`userGroupMember.filter`] instead of xref:userFilter[`user.filter`]. ++ +.`{my-app-config-file}` fragment with optional `group.expand` field +[source,yaml] +---- +catalog: + providers: + microsoftGraphOrg: + providerId: + group: + expand: member +---- + +[id=groupFilter] +`group.filter`:: +To filter groups. +See link:https://docs.microsoft.com/en-us/graph/api/resources/group?view=graph-rest-1.0#properties[Microsoft Graph API query group syntax]. ++ +.`{my-app-config-file}` fragment with optional `group.filter` field +[source,yaml] +---- +catalog: + providers: + microsoftGraphOrg: + providerId: + group: + filter: securityEnabled eq false and mailEnabled eq true and groupTypes/any(c:c+eq+'Unified') +---- + +[id=groupSearch] +`group.search`:: +To search for groups. +See link:https://docs.microsoft.com/en-us/graph/search-query-parameter[Microsoft Graph API query search parameter]. ++ +.`{my-app-config-file}` fragment with optional `group.search` field +[source,yaml] +---- +catalog: + providers: + microsoftGraphOrg: + providerId: + group: + search: '"description:One" AND ("displayName:Video" OR "displayName:Drive")' +---- + +[id=groupSelect] +`group.select`:: +Enter the link:https://docs.microsoft.com/en-us/graph/api/resources/schemaextension?view=graph-rest-1.0[Microsoft Graph resource type] list to retrieve. ++ +.`{my-app-config-file}` fragment with optional `group.select` field +[source,yaml] +---- +catalog: + providers: + microsoftGraphOrg: + providerId: + group: + select: ['id', 'displayName', 'description'] +---- +-- + +. To set up the {azure-short} authentication provider, add the `auth.providers.microsoft` section to your `{my-app-config-file}` file content: ++ +-- +.`{my-app-config-file}` file fragment with mandatory fields to enable authentication with {azure-short} +[source,yaml,subs="+quotes,+attributes"] +---- +auth: + environment: production + providers: + microsoft: + production: + clientId: ${AUTH_AZURE_CLIENT_ID} + clientSecret: ${AUTH_AZURE_CLIENT_SECRET} + tenantId: ${AUTH_AZURE_TENANT_ID} +signInPage: microsoft +---- + +`environment`:: +Enter `production` to disable the **Guest** login option in the {product-short} login page. + +`clientId`:: +Enter the configured secret variable name: `${AUTH_AZURE_CLIENT_ID}`. + +`clientSecret`:: +Enter the configured secret variable name: +`${AUTH_AZURE_CLIENT_SECRET}`. + +`tenantId`:: +Enter the configured secret variable name: `${AUTH_AZURE_TENANT_ID}`. + +`signInPage`:: +Enter `microsoft` to set the {azure-short} provider as your {product-short} sign-in provider. + +Optional: Consider adding following optional fields: + +`domainHint`:: +Optional for single-tenant applications. +You can reduce login friction for users with accounts in multiple tenants by automatically filtering out accounts from other tenants. +If you want to use this parameter for a single-tenant application, uncomment and enter the tenant ID. +If your application registration is multi-tenant, leave this parameter blank. +For more information, see link:https://learn.microsoft.com/en-us/azure/active-directory/manage-apps/home-realm-discovery-policy[Home Realm Discovery]. ++ +.`{my-app-config-file}` file fragment with optional `domainHint` field +[source,yaml,subs="+quotes,+attributes"] +---- +auth: + environment: production + providers: + microsoft: + production: + domainHint: ${AUTH_AZURE_TENANT_ID} +---- + +`additionalScopes`:: +Optional for additional scopes. +To add scopes for the application registration, uncomment and enter the list of scopes that you want to add. +The default and mandatory value lists: `'openid', 'offline_access', 'profile', 'email', 'User.Read'`. ++ +.`{my-app-config-file}` file fragment with optional `additionalScopes` field +[source,yaml,subs="+quotes,+attributes"] +---- +auth: + environment: production + providers: + microsoft: + production: + additionalScopes: + - Mail.Send +---- + +`sessionDuration`:: +Lifespan of the user session. +Enter a duration in `ms` library (such as '24h', '2 days'), ISO duration, or "human duration" format. ++ +.`app-config-rhdh.yaml` fragment with optional `sessionDuration` field +[source,yaml,subs="+quotes"] +---- +auth: + providers: + microsoft: + production: + sessionDuration: + hours: 24 +---- + +`signIn`:: + +`resolvers`::: +After successful authentication, {product-short} resolves the user signing in to an existing user in the {product-short} catalog. +To best match users securely for your use case, consider configuring a specific resolver. ++ +Enter the resolver list to override the default resolver: `emailLocalPartMatchingUserEntityName`. ++ +The authentication provider tries each sign-in resolver in order until it succeeds, and fails if none succeed. ++ +WARNING: In production mode, only configure one resolver to ensure users are securely matched. ++ +.`app-config-rhdh.yaml` fragment with optional field to allow signing in users absent from the software catalog +[source,yaml] +---- +auth: + environment: production + providers: + microsoft: + production: + clientId: ${AUTH_AZURE_CLIENT_ID} + clientSecret: ${AUTH_AZURE_CLIENT_SECRET} + tenantId: ${AUTH_AZURE_TENANT_ID} + signIn: + resolvers: + - resolver: usernameMatchingUserEntityName + dangerouslyAllowSignInWithoutUserInCatalog: true +signInPage: microsoft +---- + +`resolver`:::: +Enter the sign-in resolver name. +Available resolvers: + +* `userIdMatchingUserEntityAnnotation` +* `emailLocalPartMatchingUserEntityName` +* `emailMatchingUserEntityProfileEmail` + +`dangerouslyAllowSignInWithoutUserInCatalog: true`:::: +Configure the sign-in resolver to bypass the user provisioning requirement in the {product-short} software catalog. ++ +WARNING: Use `dangerouslyAllowSignInWithoutUserInCatalog` to explore {product-short} features, but do not use it in production. +-- + +.Verification +. To verify user and group provisioning, check the console logs. ++ +.Successful synchronization example: +[source,json] +---- +backend:start: {"class":"MicrosoftGraphOrgEntityProvider$1","level":"info","message":"Read 1 msgraph users and 1 msgraph groups in 2.2 seconds. Committing...","plugin":"catalog","service":"backstage","taskId":"MicrosoftGraphOrgEntityProvider:default:refresh","taskInstanceId":"88a67ce1-c466-41a4-9760-825e16b946be","timestamp":"2024-06-26 12:23:42"} +backend:start: {"class":"MicrosoftGraphOrgEntityProvider$1","level":"info","message":"Committed 1 msgraph users and 1 msgraph groups in 0.0 seconds.","plugin":"catalog","service":"backstage","taskId":"MicrosoftGraphOrgEntityProvider:default:refresh","taskInstanceId":"88a67ce1-c466-41a4-9760-825e16b946be","timestamp":"2024-06-26 12:23:42"} +---- + +. To verify {azure-short} user authentication: +.. Go to the {product-short} login page. +.. Your {product-short} sign-in page displays *Sign in using {azure-short}* and the Guest user sign-in is disabled. +.. Log in with an {azure-short} account. diff --git a/modules/authentication/proc-provisioning-users-from-microsoft-azure-to-the-software-catalog.adoc b/modules/authentication/proc-provisioning-users-from-microsoft-azure-to-the-software-catalog.adoc deleted file mode 100644 index d01869ce1d..0000000000 --- a/modules/authentication/proc-provisioning-users-from-microsoft-azure-to-the-software-catalog.adoc +++ /dev/null @@ -1,268 +0,0 @@ -:_mod-docs-content-type: PROCEDURE -[id="provisioning-users-from-microsoft-azure-to-the-software-catalog"] -= Provisioning users from Microsoft Azure to the software catalog - -To authenticate users with Microsoft Azure, after xref:enabling-authentication-with-microsoft-azure[Enabling authentication with Microsoft Azure], provision users from Microsoft Azure to the {product-short} software catalog. - -.Prerequisites -* You have xref:enabling-authentication-with-microsoft-azure[enabled authentication with Microsoft Azure]. - -.Procedure -. link:{installing-and-viewing-plugins-book-url}[Enable the `backstage-plugin-catalog-backend-module-msgraph-dynamic` plugin]. -+ -.`dynamic-plugins.yaml` file fragment -[code,yaml] ----- -plugins: - - package: './dynamic-plugins/dist/backstage-plugin-catalog-backend-module-msgraph-dynamic' - disabled: false ----- - -. To enable {azure-brand-name} member discovery, edit `{my-app-config-file}`, your custom {product-short} configuration file:: -+ -[id=microsoftGraphOrgProviderId] -.`{my-app-config-file}` fragment with mandatory `microsoftGraphOrg` fields -[source,yaml] ----- -catalog: - providers: - microsoftGraphOrg: - providerId: - target: https://graph.microsoft.com/v1.0 - tenantId: ${AUTH_AZURE_TENANT_ID} - clientId: ${AUTH_AZURE_CLIENT_ID} - clientSecret: ${AUTH_AZURE_CLIENT_SECRET} - schedule: - frequency: { hours: 1 } - timeout: { minutes: 50 } - initialDelay: { minutes: 50 } ----- - -`target: https://graph.microsoft.com/v1.0`:: -Defines the MSGraph API endpoint the provider is connecting to. -You might change this parameter to use a different version, such as the link:https://learn.microsoft.com/en-us/graph/api/overview?view=graph-rest-beta#call-the-beta-endpoint[beta endpoint]. - -`tenandId`, `clientId` and `clientSecret`:: -Use the {product-short} application information you created in Microsoft Azure and configured in OpenShift as secrets. - -`schedule`:: - -`frequency`::: -Enter the schedule frequency as cron, ISO duration, or human duration as used in code. - -`timeout`::: -Enter the schedule timeout as ISO duration or human duration as used in code. - -`initialDelay`::: -Enter the schedule initial delay as ISO duration or human duration as used in code. -+ -TIP: In a large organization, this plugin can take a long time. Therefore, avoid setting a low frequency or timeout when importing a large number of users and groups for the first time. - -Optional: Consider adding the following optional `microsoftGraphOrg.providerId` fields: - -[id=authority] -`authority: https://login.microsoftonline.com`:: -Defines the authority used. -Change the value to use a different link:https://learn.microsoft.com/en-us/graph/deployments#app-registration-and-token-service-root-endpoints[authority], such as Azure US government. -Default value: `https://login.microsoftonline.com`. -+ -.`{my-app-config-file}` fragment with optional `queryMode` field -[source,yaml] ----- -catalog: - providers: - microsoftGraphOrg: - providerId: - authority: https://login.microsoftonline.com/ ----- -[id=queryMode] -`queryMode: basic | advanced`:: By default, the Microsoft Graph API only provides the `basic` feature set for querying. -Certain features require `advanced` querying capabilities. -See link:https://docs.microsoft.com/en-us/graph/aad-advanced-queries[Microsoft Azure Advanced queries]. -+ -.`{my-app-config-file}` fragment with optional `queryMode` field -[source,yaml] ----- -catalog: - providers: - microsoftGraphOrg: - providerId: - queryMode: advanced ----- - -[id=userExpand] -`user.expand`:: -To include the expanded resource or collection referenced by a single relationship (navigation property) in your results. -Only one relationship can be expanded in a single request. -See https://docs.microsoft.com/en-us/graph/query-parameters#expand-parameter[Microsoft Graph query expand parameter]. -This parameter can be combined with xref:userGroupMemberFilter[] or xref:userFilter[]. -+ -.`{my-app-config-file}` fragment with optional `user.expand` field -[source,yaml] ----- -catalog: - providers: - microsoftGraphOrg: - providerId: - user: - expand: manager ----- - -[id=userFilter] -`user.filter`:: -To filter users. -See link:https://docs.microsoft.com/en-us/graph/api/resources/user?view=graph-rest-1.0#properties[Microsoft Graph API] and link:https://docs.microsoft.com/en-us/graph/query-parameters#filter-parameter[Microsoft Graph API query filter parameters syntax]. -This parameter and xref:userGroupMemberFilter[] are mutually exclusive, only one can be specified. -+ -.`{my-app-config-file}` fragment with optional `user.filter` field -[source,yaml] ----- -catalog: - providers: - microsoftGraphOrg: - providerId: - user: - filter: accountEnabled eq true and userType eq 'member' ----- - -[id=userLoadPhotos] -`user.loadPhotos: true | false`:: -Load photos by default. -Set to `false` to not load user photos. -+ -.`{my-app-config-file}` fragment with optional `user.loadPhotos` field -[source,yaml] ----- -catalog: - providers: - microsoftGraphOrg: - providerId: - user: - loadPhotos: true ----- - -[id=userSelect] -`user.select`:: -Define the link:https://docs.microsoft.com/en-us/graph/api/resources/schemaextension?view=graph-rest-1.0[Microsoft Graph resource types] to retrieve. -+ -.`{my-app-config-file}` fragment with optional `user.select` field -[source,yaml] ----- -catalog: - providers: - microsoftGraphOrg: - providerId: - user: - select: ['id', 'displayName', 'description'] ----- - -[id="userGroupMemberFilter"] -`userGroupMember.filter`::: -To use group membership to get users. -To filter groups and fetch their members. -This parameter and xref:userFilter[] are mutually exclusive, only one can be specified. -+ -.`{my-app-config-file}` fragment with optional `userGroupMember.filter` field -[source,yaml] ----- -catalog: - providers: - microsoftGraphOrg: - providerId: - userGroupMember: - filter: "displayName eq 'Backstage Users'" ----- - -[id="userGroupMemberSearch"] -`userGroupMember.search`:: -To use group membership to get users. -To search for groups and fetch their members. -This parameter and xref:userFilter[] are mutually exclusive, only one can be specified. -+ -.`{my-app-config-file}` fragment with optional `userGroupMember.search` field -[source,yaml] ----- -catalog: - providers: - microsoftGraphOrg: - providerId: - userGroupMember: - search: '"description:One" AND ("displayName:Video" OR "displayName:Drive")' ----- - -[id=groupExpand] -`group.expand`:: -Optional parameter to include the expanded resource or collection referenced by a single relationship (navigation property) in your results. -Only one relationship can be expanded in a single request. -See https://docs.microsoft.com/en-us/graph/query-parameters#expand-parameter -This parameter can be combined with xref:userGroupMemberFilter[] instead of xref:userFilter[]. -+ -.`{my-app-config-file}` fragment with optional `group.expand` field -[source,yaml] ----- -catalog: - providers: - microsoftGraphOrg: - providerId: - group: - expand: member ----- - -[id=groupFilter] -`group.filter`:: -To filter groups. -See link:https://docs.microsoft.com/en-us/graph/api/resources/group?view=graph-rest-1.0#properties[Microsoft Graph API query group syntax]. -+ -.`{my-app-config-file}` fragment with optional `group.filter` field -[source,yaml] ----- -catalog: - providers: - microsoftGraphOrg: - providerId: - group: - filter: securityEnabled eq false and mailEnabled eq true and groupTypes/any(c:c+eq+'Unified') ----- - -[id=groupSearch] -`group.search`:: -To search for groups. -See link:https://docs.microsoft.com/en-us/graph/search-query-parameter[Microsoft Graph API query search parameter]. -+ -.`{my-app-config-file}` fragment with optional `group.search` field -[source,yaml] ----- -catalog: - providers: - microsoftGraphOrg: - providerId: - group: - search: '"description:One" AND ("displayName:Video" OR "displayName:Drive")' ----- - -[id=groupSelect] -`group.select`:: -To define the link:https://docs.microsoft.com/en-us/graph/api/resources/schemaextension?view=graph-rest-1.0[Microsoft Graph resource types] to retrieve. -+ -.`{my-app-config-file}` fragment with optional `group.select` field -[source,yaml] ----- -catalog: - providers: - microsoftGraphOrg: - providerId: - group: - select: ['id', 'displayName', 'description'] ----- - -.Verification -. Check the console logs to verify that the synchronization is completed. -+ -.Successful synchronization example: -[source,json] ----- -backend:start: {"class":"MicrosoftGraphOrgEntityProvider$1","level":"info","message":"Read 1 msgraph users and 1 msgraph groups in 2.2 seconds. Committing...","plugin":"catalog","service":"backstage","taskId":"MicrosoftGraphOrgEntityProvider:default:refresh","taskInstanceId":"88a67ce1-c466-41a4-9760-825e16b946be","timestamp":"2024-06-26 12:23:42"} -backend:start: {"class":"MicrosoftGraphOrgEntityProvider$1","level":"info","message":"Committed 1 msgraph users and 1 msgraph groups in 0.0 seconds.","plugin":"catalog","service":"backstage","taskId":"MicrosoftGraphOrgEntityProvider:default:refresh","taskInstanceId":"88a67ce1-c466-41a4-9760-825e16b946be","timestamp":"2024-06-26 12:23:42"} ----- - -. Log in with a Microsoft Azure account. diff --git a/artifacts/snip-technology-preview.adoc b/modules/snip-technology-preview.adoc similarity index 100% rename from artifacts/snip-technology-preview.adoc rename to modules/snip-technology-preview.adoc From f2b51848e0690c6a2dfc82de69c91ca31d9ba6ca Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Fabrice=20Flore-Th=C3=A9bault?= Date: Wed, 18 Jun 2025 09:06:01 +0200 Subject: [PATCH 02/27] Apply suggestions from code review Co-authored-by: Jessica He --- ...enabling-user-authentication-with-microsoft-azure.adoc | 8 ++++---- 1 file changed, 4 insertions(+), 4 deletions(-) diff --git a/modules/authentication/proc-enabling-user-authentication-with-microsoft-azure.adoc b/modules/authentication/proc-enabling-user-authentication-with-microsoft-azure.adoc index 411278c31b..8f4d5a7ba4 100644 --- a/modules/authentication/proc-enabling-user-authentication-with-microsoft-azure.adoc +++ b/modules/authentication/proc-enabling-user-authentication-with-microsoft-azure.adoc @@ -12,14 +12,14 @@ Alternatively, you can ask your {azure-short} administrator to prepare the requi * Your {product-short} backend can access the following hosts: `login.microsoftonline.com`:: -For obtaining and exchanging authorization codes and access tokens. +This is the {azure-brand-name} authorization server, which enables the authentication flow. `graph.microsoft.com`:: -For retrieving user profile information (as referenced in the source code), and avoiding an _Authentication failed, failed to fetch user profile_ error when attempting to log in. +For retrieving organization data, including user and group data, to be ingested into the {product-short} catalog. .Procedure :my-product-app-name-in-azure: -. To allow {product-short} to authenticate with {azure-brand-name}, link:https://learn.microsoft.com/en-us/entra/identity-platform/scenario-web-app-sign-user-app-registration?tabs=aspnetcore#register-an-app-by-using-the-azure-portal[create an OAuth application in {azure-short}]. +. To allow {product-short} to authenticate with {azure-short}, link:https://learn.microsoft.com/en-us/entra/identity-platform/scenario-web-app-sign-user-app-registration?tabs=aspnetcore#register-an-app-by-using-the-azure-portal[Register an app by using the {azure-short} portal]. .. In the {azure-short} portal go to link:https://portal.azure.com/#view/Microsoft_AAD_RegisteredApps/ApplicationsListBlade[*App registrations*], create a **New registration** with the configuration: @@ -426,7 +426,7 @@ auth: After successful authentication, {product-short} resolves the user signing in to an existing user in the {product-short} catalog. To best match users securely for your use case, consider configuring a specific resolver. + -Enter the resolver list to override the default resolver: `emailLocalPartMatchingUserEntityName`. +Enter the resolver list to override the default resolver: `userIdMatchingUserEntityAnnotation`. + The authentication provider tries each sign-in resolver in order until it succeeds, and fails if none succeed. + From b01c39966bbc26e40a773a5412d4847fd9d4c6e9 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Fabrice=20Flore-Th=C3=A9bault?= Date: Wed, 18 Jun 2025 09:17:03 +0200 Subject: [PATCH 03/27] Update modules/authentication/proc-enabling-user-authentication-with-microsoft-azure.adoc --- ...c-enabling-user-authentication-with-microsoft-azure.adoc | 6 +++++- 1 file changed, 5 insertions(+), 1 deletion(-) diff --git a/modules/authentication/proc-enabling-user-authentication-with-microsoft-azure.adoc b/modules/authentication/proc-enabling-user-authentication-with-microsoft-azure.adoc index 8f4d5a7ba4..96372393c1 100644 --- a/modules/authentication/proc-enabling-user-authentication-with-microsoft-azure.adoc +++ b/modules/authentication/proc-enabling-user-authentication-with-microsoft-azure.adoc @@ -21,7 +21,11 @@ For retrieving organization data, including user and group data, to be ingested :my-product-app-name-in-azure: . To allow {product-short} to authenticate with {azure-short}, link:https://learn.microsoft.com/en-us/entra/identity-platform/scenario-web-app-sign-user-app-registration?tabs=aspnetcore#register-an-app-by-using-the-azure-portal[Register an app by using the {azure-short} portal]. -.. In the {azure-short} portal go to link:https://portal.azure.com/#view/Microsoft_AAD_RegisteredApps/ApplicationsListBlade[*App registrations*], create a **New registration** with the configuration: +.. Sign in to the [Microsoft Entra admin center](https://entra.microsoft.com/). + +.. If you have access to multiple tenants, use the *Settings* icon in the top menu to switch to the tenant in which you want to register the application from the *Directories + subscriptions* menu. + +.. Browse to *Entra ID > App registrations*, create a **New registration** with the configuration: Name:: Enter a name to identify your application in Azure, such as __{my-product-app-name-in-azure}__. From 7831dec2f0d646e51b30a42da34a7b6b47b027c9 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Fabrice=20Flore-Th=C3=A9bault?= Date: Wed, 18 Jun 2025 09:19:09 +0200 Subject: [PATCH 04/27] Update modules/authentication/proc-enabling-user-authentication-with-microsoft-azure.adoc --- .../proc-enabling-user-authentication-with-microsoft-azure.adoc | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/modules/authentication/proc-enabling-user-authentication-with-microsoft-azure.adoc b/modules/authentication/proc-enabling-user-authentication-with-microsoft-azure.adoc index 96372393c1..854116f565 100644 --- a/modules/authentication/proc-enabling-user-authentication-with-microsoft-azure.adoc +++ b/modules/authentication/proc-enabling-user-authentication-with-microsoft-azure.adoc @@ -28,7 +28,7 @@ For retrieving organization data, including user and group data, to be ingested .. Browse to *Entra ID > App registrations*, create a **New registration** with the configuration: Name:: -Enter a name to identify your application in Azure, such as __{my-product-app-name-in-azure}__. +Enter a name to identify your application in {azure-short}, such as __{my-product-app-name-in-azure}__. .. On the *Home > App registrations > __{my-product-app-name-in-azure}__ > Manage > Authentication* page, *Add a platform*, with the following configuration: From fa3eb7faf580e5a82a2a59eb84c493a82f33d5af Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Fabrice=20Flore-Th=C3=A9bault?= Date: Wed, 18 Jun 2025 09:33:39 +0200 Subject: [PATCH 05/27] Update modules/authentication/proc-enabling-user-authentication-with-microsoft-azure.adoc --- .../proc-enabling-user-authentication-with-microsoft-azure.adoc | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/modules/authentication/proc-enabling-user-authentication-with-microsoft-azure.adoc b/modules/authentication/proc-enabling-user-authentication-with-microsoft-azure.adoc index 854116f565..03a913e05d 100644 --- a/modules/authentication/proc-enabling-user-authentication-with-microsoft-azure.adoc +++ b/modules/authentication/proc-enabling-user-authentication-with-microsoft-azure.adoc @@ -21,7 +21,7 @@ For retrieving organization data, including user and group data, to be ingested :my-product-app-name-in-azure: . To allow {product-short} to authenticate with {azure-short}, link:https://learn.microsoft.com/en-us/entra/identity-platform/scenario-web-app-sign-user-app-registration?tabs=aspnetcore#register-an-app-by-using-the-azure-portal[Register an app by using the {azure-short} portal]. -.. Sign in to the [Microsoft Entra admin center](https://entra.microsoft.com/). +.. Sign in to the link:https://entra.microsoft.com/[Microsoft Entra admin center]. .. If you have access to multiple tenants, use the *Settings* icon in the top menu to switch to the tenant in which you want to register the application from the *Directories + subscriptions* menu. From 8bca6657f72f31968847425c893959f5745e579d Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Fabrice=20Flore-Th=C3=A9bault?= Date: Wed, 18 Jun 2025 17:17:27 +0200 Subject: [PATCH 06/27] Update modules/authentication/proc-enabling-user-authentication-with-microsoft-azure.adoc --- .../proc-enabling-user-authentication-with-microsoft-azure.adoc | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/modules/authentication/proc-enabling-user-authentication-with-microsoft-azure.adoc b/modules/authentication/proc-enabling-user-authentication-with-microsoft-azure.adoc index 03a913e05d..7ddf204161 100644 --- a/modules/authentication/proc-enabling-user-authentication-with-microsoft-azure.adoc +++ b/modules/authentication/proc-enabling-user-authentication-with-microsoft-azure.adoc @@ -25,7 +25,7 @@ For retrieving organization data, including user and group data, to be ingested .. If you have access to multiple tenants, use the *Settings* icon in the top menu to switch to the tenant in which you want to register the application from the *Directories + subscriptions* menu. -.. Browse to *Entra ID > App registrations*, create a **New registration** with the configuration: +.. Browse to *Applications > App registrations*, and create a **New registration** with the configuration: Name:: Enter a name to identify your application in {azure-short}, such as __{my-product-app-name-in-azure}__. From 85b00bfe7758c171d48181eb502eadfe532f5385 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Fabrice=20Flore-Th=C3=A9bault?= Date: Wed, 18 Jun 2025 17:19:46 +0200 Subject: [PATCH 07/27] Update modules/authentication/proc-enabling-user-authentication-with-microsoft-azure.adoc --- ...proc-enabling-user-authentication-with-microsoft-azure.adoc | 3 ++- 1 file changed, 2 insertions(+), 1 deletion(-) diff --git a/modules/authentication/proc-enabling-user-authentication-with-microsoft-azure.adoc b/modules/authentication/proc-enabling-user-authentication-with-microsoft-azure.adoc index 7ddf204161..1eb4b4da85 100644 --- a/modules/authentication/proc-enabling-user-authentication-with-microsoft-azure.adoc +++ b/modules/authentication/proc-enabling-user-authentication-with-microsoft-azure.adoc @@ -30,7 +30,8 @@ For retrieving organization data, including user and group data, to be ingested Name:: Enter a name to identify your application in {azure-short}, such as __{my-product-app-name-in-azure}__. -.. On the *Home > App registrations > __{my-product-app-name-in-azure}__ > Manage > Authentication* page, *Add a platform*, with the following configuration: +Supported account types:: +Select *Accounts in this organizational directory only*. Redirect URI:: Enter the backend authentication URI set in {product-short}: `pass:c,a,q[{my-product-url}/api/auth/microsoft/handler/frame]` From 4d95e0284859f654d99c0073f0e053cba737c67b Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Fabrice=20Flore-Th=C3=A9bault?= Date: Wed, 18 Jun 2025 17:21:38 +0200 Subject: [PATCH 08/27] Update modules/authentication/proc-enabling-user-authentication-with-microsoft-azure.adoc --- ...oc-enabling-user-authentication-with-microsoft-azure.adoc | 5 +++++ 1 file changed, 5 insertions(+) diff --git a/modules/authentication/proc-enabling-user-authentication-with-microsoft-azure.adoc b/modules/authentication/proc-enabling-user-authentication-with-microsoft-azure.adoc index 1eb4b4da85..8bdc824965 100644 --- a/modules/authentication/proc-enabling-user-authentication-with-microsoft-azure.adoc +++ b/modules/authentication/proc-enabling-user-authentication-with-microsoft-azure.adoc @@ -34,6 +34,11 @@ Supported account types:: Select *Accounts in this organizational directory only*. Redirect URI:: + +Select a platform::: +Select *Web*. + +URL::: Enter the backend authentication URI set in {product-short}: `pass:c,a,q[{my-product-url}/api/auth/microsoft/handler/frame]` Front-channel logout URL:: From 5d5acf5129e8011a2d6f434c3a1a45ee9bebfce6 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Fabrice=20Flore-Th=C3=A9bault?= Date: Wed, 18 Jun 2025 17:22:48 +0200 Subject: [PATCH 09/27] Update modules/authentication/proc-enabling-user-authentication-with-microsoft-azure.adoc --- ...c-enabling-user-authentication-with-microsoft-azure.adoc | 6 ------ 1 file changed, 6 deletions(-) diff --git a/modules/authentication/proc-enabling-user-authentication-with-microsoft-azure.adoc b/modules/authentication/proc-enabling-user-authentication-with-microsoft-azure.adoc index 8bdc824965..e1dac51d19 100644 --- a/modules/authentication/proc-enabling-user-authentication-with-microsoft-azure.adoc +++ b/modules/authentication/proc-enabling-user-authentication-with-microsoft-azure.adoc @@ -41,12 +41,6 @@ Select *Web*. URL::: Enter the backend authentication URI set in {product-short}: `pass:c,a,q[{my-product-url}/api/auth/microsoft/handler/frame]` -Front-channel logout URL:: -Leave blank. - -Implicit grant and hybrid flows:: -Leave all checkboxes cleared. - .. On the *Home > App registrations > __My {my-product-app-name-in-azure}__ > Manage > API permissions* page, *Add a Permission*, then add the following *Delegated permission* for the *Microsoft Graph API*: * `email` From 3c1a2179912217cd444743ea745e030a40b49429 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Fabrice=20Flore-Th=C3=A9bault?= Date: Wed, 18 Jun 2025 17:27:29 +0200 Subject: [PATCH 10/27] Update modules/authentication/proc-enabling-user-authentication-with-microsoft-azure.adoc --- .../proc-enabling-user-authentication-with-microsoft-azure.adoc | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/modules/authentication/proc-enabling-user-authentication-with-microsoft-azure.adoc b/modules/authentication/proc-enabling-user-authentication-with-microsoft-azure.adoc index e1dac51d19..b3fa588715 100644 --- a/modules/authentication/proc-enabling-user-authentication-with-microsoft-azure.adoc +++ b/modules/authentication/proc-enabling-user-authentication-with-microsoft-azure.adoc @@ -41,7 +41,7 @@ Select *Web*. URL::: Enter the backend authentication URI set in {product-short}: `pass:c,a,q[{my-product-url}/api/auth/microsoft/handler/frame]` -.. On the *Home > App registrations > __My {my-product-app-name-in-azure}__ > Manage > API permissions* page, *Add a Permission*, then add the following *Delegated permission* for the *Microsoft Graph API*: +.. On the *Applications > App registrations > __{my-product-app-name-in-azure}__ > Manage > API permissions* page, *Add a Permission*, select the *Microsoft Graph* API, and select the following *Application permission*: * `email` * `offline_access` From 42183b108dd809f927e9993bb2593faccf046145 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Fabrice=20Flore-Th=C3=A9bault?= Date: Fri, 20 Jun 2025 16:11:42 +0200 Subject: [PATCH 11/27] Update modules/authentication/proc-enabling-user-authentication-with-microsoft-azure.adoc --- .../proc-enabling-user-authentication-with-microsoft-azure.adoc | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/modules/authentication/proc-enabling-user-authentication-with-microsoft-azure.adoc b/modules/authentication/proc-enabling-user-authentication-with-microsoft-azure.adoc index b3fa588715..ece7e1b5b5 100644 --- a/modules/authentication/proc-enabling-user-authentication-with-microsoft-azure.adoc +++ b/modules/authentication/proc-enabling-user-authentication-with-microsoft-azure.adoc @@ -41,7 +41,7 @@ Select *Web*. URL::: Enter the backend authentication URI set in {product-short}: `pass:c,a,q[{my-product-url}/api/auth/microsoft/handler/frame]` -.. On the *Applications > App registrations > __{my-product-app-name-in-azure}__ > Manage > API permissions* page, *Add a Permission*, select the *Microsoft Graph* API, and select the following *Application permission*: +.. On the *Applications > App registrations > __{my-product-app-name-in-azure}__ > Manage > API permissions* page, click *Add a Permission*, click *Microsoft Graph*, click *Applications permissions*, and select the following permissions: * `email` * `offline_access` From 9aeed62dc3e781dac286be2fa232a850e7c0f2fc Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Fabrice=20Flore-Th=C3=A9bault?= Date: Fri, 20 Jun 2025 16:15:51 +0200 Subject: [PATCH 12/27] Update modules/authentication/proc-enabling-user-authentication-with-microsoft-azure.adoc --- .../proc-enabling-user-authentication-with-microsoft-azure.adoc | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/modules/authentication/proc-enabling-user-authentication-with-microsoft-azure.adoc b/modules/authentication/proc-enabling-user-authentication-with-microsoft-azure.adoc index ece7e1b5b5..9950b228b2 100644 --- a/modules/authentication/proc-enabling-user-authentication-with-microsoft-azure.adoc +++ b/modules/authentication/proc-enabling-user-authentication-with-microsoft-azure.adoc @@ -58,7 +58,7 @@ Even if your company does not require admin consent, you might do so as it means To grant administrator consent, a directory administrator must go to the link:https://learn.microsoft.com/en-us/azure/active-directory/manage-apps/user-admin-consent-overview[admin consent] page and click *Grant admin consent for COMPANY NAME*. ==== -.. On the *Home > App registrations > __{my-product-app-name-in-azure}__ > Manage > Certificates & Secrets* page, in the *Client secrets* tab, create a *New client secret*. +.. On the *Applications > App registrations > __{my-product-app-name-in-azure}__ > Manage > Certificates & secrets* page, in the *Client secrets* tab, create a *New client secret*. .. Save the following values for the next step: - **Directory (tenant) ID** From 7617f7bb758343c5cb0327d0a4e76f8933be896b Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Fabrice=20Flore-Th=C3=A9bault?= Date: Fri, 20 Jun 2025 16:22:19 +0200 Subject: [PATCH 13/27] Update modules/authentication/proc-enabling-user-authentication-with-microsoft-azure.adoc --- .../proc-enabling-user-authentication-with-microsoft-azure.adoc | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/modules/authentication/proc-enabling-user-authentication-with-microsoft-azure.adoc b/modules/authentication/proc-enabling-user-authentication-with-microsoft-azure.adoc index 9950b228b2..02ef9a96f1 100644 --- a/modules/authentication/proc-enabling-user-authentication-with-microsoft-azure.adoc +++ b/modules/authentication/proc-enabling-user-authentication-with-microsoft-azure.adoc @@ -63,7 +63,7 @@ To grant administrator consent, a directory administrator must go to the link:ht .. Save the following values for the next step: - **Directory (tenant) ID** - **Application (client) ID** -- **Application (client) secret** +- **Application (client) Secret ID** . To add your {azure-short} credentials to {product-short}, add the following key/value pairs to link:{configuring-dynamic-plugins-book-url}#provisioning-your-custom-configuration[your {product-short} secrets]: From 995321776edb13b30b4b6a3483ac6e6b98aa179e Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Fabrice=20Flore-Th=C3=A9bault?= Date: Mon, 23 Jun 2025 15:04:39 +0200 Subject: [PATCH 14/27] Update modules/authentication/proc-enabling-user-authentication-with-microsoft-azure.adoc --- ...r-authentication-with-microsoft-azure.adoc | 24 +++++++++++++------ 1 file changed, 17 insertions(+), 7 deletions(-) diff --git a/modules/authentication/proc-enabling-user-authentication-with-microsoft-azure.adoc b/modules/authentication/proc-enabling-user-authentication-with-microsoft-azure.adoc index 02ef9a96f1..b907fa1f0e 100644 --- a/modules/authentication/proc-enabling-user-authentication-with-microsoft-azure.adoc +++ b/modules/authentication/proc-enabling-user-authentication-with-microsoft-azure.adoc @@ -43,13 +43,23 @@ Enter the backend authentication URI set in {product-short}: `pass:c,a,q[{my-pro .. On the *Applications > App registrations > __{my-product-app-name-in-azure}__ > Manage > API permissions* page, click *Add a Permission*, click *Microsoft Graph*, click *Applications permissions*, and select the following permissions: -* `email` -* `offline_access` -* `openid` -* `profile` -* `User.Read.All` -* `GroupMember.Read.All` -* Optional custom scopes for the Microsoft Graph API that you define both in this section and in the `{my-app-config-file}` {product-short} configuration file. +Application Permissions:: + +`User.Read.All`::: + +`GroupMember.Read.All`::: + +Delegated Permissions:: + +`email`::: + +`offline_access`::: + +`openid`::: + +`profile`::: + +Optional::: Enter optional custom scopes for the Microsoft Graph API that you define both in this section and in the `{my-app-config-file}` {product-short} configuration file. + [NOTE] ==== From 52b8e8790255c166d9d834b81d0f0cc420659512 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Fabrice=20Flore-Th=C3=A9bault?= Date: Mon, 23 Jun 2025 15:09:44 +0200 Subject: [PATCH 15/27] Update modules/authentication/proc-enabling-user-authentication-with-microsoft-azure.adoc --- .../proc-enabling-user-authentication-with-microsoft-azure.adoc | 2 ++ 1 file changed, 2 insertions(+) diff --git a/modules/authentication/proc-enabling-user-authentication-with-microsoft-azure.adoc b/modules/authentication/proc-enabling-user-authentication-with-microsoft-azure.adoc index b907fa1f0e..35d083ed8b 100644 --- a/modules/authentication/proc-enabling-user-authentication-with-microsoft-azure.adoc +++ b/modules/authentication/proc-enabling-user-authentication-with-microsoft-azure.adoc @@ -44,12 +44,14 @@ Enter the backend authentication URI set in {product-short}: `pass:c,a,q[{my-pro .. On the *Applications > App registrations > __{my-product-app-name-in-azure}__ > Manage > API permissions* page, click *Add a Permission*, click *Microsoft Graph*, click *Applications permissions*, and select the following permissions: Application Permissions:: +Enter permissions that enable provisioning user and groups to the {product-short} software catalog. `User.Read.All`::: `GroupMember.Read.All`::: Delegated Permissions:: +Enter permissions that enable authenticating users. `email`::: From c079a88c79f6780f4ae3dddf90792d09b1e3e390 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Fabrice=20Flore-Th=C3=A9bault?= Date: Mon, 23 Jun 2025 15:23:00 +0200 Subject: [PATCH 16/27] Update modules/authentication/proc-enabling-user-authentication-with-microsoft-azure.adoc --- .../proc-enabling-user-authentication-with-microsoft-azure.adoc | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/modules/authentication/proc-enabling-user-authentication-with-microsoft-azure.adoc b/modules/authentication/proc-enabling-user-authentication-with-microsoft-azure.adoc index 35d083ed8b..00a1811345 100644 --- a/modules/authentication/proc-enabling-user-authentication-with-microsoft-azure.adoc +++ b/modules/authentication/proc-enabling-user-authentication-with-microsoft-azure.adoc @@ -481,7 +481,7 @@ WARNING: Use `dangerouslyAllowSignInWithoutUserInCatalog` to explore {product-sh -- .Verification -. To verify user and group provisioning, check the console logs. +. To verify user and group provisioning, check the console logs for `MicrosoftGraphOrgEntityProvider` events. + .Successful synchronization example: [source,json] From 994703399cad49ea8b70431ba880ce2ab818e37f Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Fabrice=20Flore-Th=C3=A9bault?= Date: Mon, 23 Jun 2025 15:38:44 +0200 Subject: [PATCH 17/27] Update modules/authentication/proc-enabling-user-authentication-with-microsoft-azure.adoc --- ...r-authentication-with-microsoft-azure.adoc | 23 ++++++------------- 1 file changed, 7 insertions(+), 16 deletions(-) diff --git a/modules/authentication/proc-enabling-user-authentication-with-microsoft-azure.adoc b/modules/authentication/proc-enabling-user-authentication-with-microsoft-azure.adoc index 00a1811345..cab98df021 100644 --- a/modules/authentication/proc-enabling-user-authentication-with-microsoft-azure.adoc +++ b/modules/authentication/proc-enabling-user-authentication-with-microsoft-azure.adoc @@ -44,31 +44,22 @@ Enter the backend authentication URI set in {product-short}: `pass:c,a,q[{my-pro .. On the *Applications > App registrations > __{my-product-app-name-in-azure}__ > Manage > API permissions* page, click *Add a Permission*, click *Microsoft Graph*, click *Applications permissions*, and select the following permissions: Application Permissions:: -Enter permissions that enable provisioning user and groups to the {product-short} software catalog. - `User.Read.All`::: - `GroupMember.Read.All`::: +Enter permissions that enable provisioning user and groups to the {product-short} software catalog. ++ +Optional: *Grant admin consent* for these permissions. +Even if your company does not require admin consent, consider doing so as it means users do not need to individually consent the first time they access {product-short}. Delegated Permissions:: -Enter permissions that enable authenticating users. - `email`::: - `offline_access`::: - `openid`::: - `profile`::: - -Optional::: Enter optional custom scopes for the Microsoft Graph API that you define both in this section and in the `{my-app-config-file}` {product-short} configuration file. +Enter permissions that enable authenticating users. + -[NOTE] -==== -Your company might require you to grant admin consent for these permissions. -Even if your company does not require admin consent, you might do so as it means users do not need to individually consent the first time they access backstage. -To grant administrator consent, a directory administrator must go to the link:https://learn.microsoft.com/en-us/azure/active-directory/manage-apps/user-admin-consent-overview[admin consent] page and click *Grant admin consent for COMPANY NAME*. -==== +Optional: Enter optional custom scopes for the Microsoft Graph API that you define both in this section and in the `{my-app-config-file}` {product-short} configuration file. + .. On the *Applications > App registrations > __{my-product-app-name-in-azure}__ > Manage > Certificates & secrets* page, in the *Client secrets* tab, create a *New client secret*. From e7c68412f6317d1f83ba49a658bff95d4b71f5a6 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Fabrice=20Flore-Th=C3=A9bault?= Date: Mon, 23 Jun 2025 15:48:07 +0200 Subject: [PATCH 18/27] Update modules/authentication/proc-enabling-user-authentication-with-microsoft-azure.adoc --- .../proc-enabling-user-authentication-with-microsoft-azure.adoc | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/modules/authentication/proc-enabling-user-authentication-with-microsoft-azure.adoc b/modules/authentication/proc-enabling-user-authentication-with-microsoft-azure.adoc index cab98df021..997c91b3b9 100644 --- a/modules/authentication/proc-enabling-user-authentication-with-microsoft-azure.adoc +++ b/modules/authentication/proc-enabling-user-authentication-with-microsoft-azure.adoc @@ -41,7 +41,7 @@ Select *Web*. URL::: Enter the backend authentication URI set in {product-short}: `pass:c,a,q[{my-product-url}/api/auth/microsoft/handler/frame]` -.. On the *Applications > App registrations > __{my-product-app-name-in-azure}__ > Manage > API permissions* page, click *Add a Permission*, click *Microsoft Graph*, click *Applications permissions*, and select the following permissions: +.. On the *Applications > App registrations > __{my-product-app-name-in-azure}__ > Manage > API permissions* page, *Add a Permission*, *Microsoft Graph*, select the following permissions: Application Permissions:: `User.Read.All`::: From 25a711e0d0002199f5a4803b19f09e9391b065bd Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Fabrice=20Flore-Th=C3=A9bault?= Date: Mon, 23 Jun 2025 15:50:24 +0200 Subject: [PATCH 19/27] Update modules/authentication/proc-enabling-user-authentication-with-microsoft-azure.adoc --- .../proc-enabling-user-authentication-with-microsoft-azure.adoc | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/modules/authentication/proc-enabling-user-authentication-with-microsoft-azure.adoc b/modules/authentication/proc-enabling-user-authentication-with-microsoft-azure.adoc index 997c91b3b9..84b6b551c0 100644 --- a/modules/authentication/proc-enabling-user-authentication-with-microsoft-azure.adoc +++ b/modules/authentication/proc-enabling-user-authentication-with-microsoft-azure.adoc @@ -23,7 +23,7 @@ For retrieving organization data, including user and group data, to be ingested .. Sign in to the link:https://entra.microsoft.com/[Microsoft Entra admin center]. -.. If you have access to multiple tenants, use the *Settings* icon in the top menu to switch to the tenant in which you want to register the application from the *Directories + subscriptions* menu. +.. Optional: If you have access to multiple tenants, use the *Settings* icon in the top menu to switch to the tenant in which you want to register the application from the *Directories + subscriptions* menu. .. Browse to *Applications > App registrations*, and create a **New registration** with the configuration: From c2a2351bdae2cd981ab2f72e2fdb30b5eceece68 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Fabrice=20Flore-Th=C3=A9bault?= Date: Mon, 23 Jun 2025 15:53:08 +0200 Subject: [PATCH 20/27] Apply suggestions from code review --- .../proc-enabling-user-authentication-with-microsoft-azure.adoc | 2 -- 1 file changed, 2 deletions(-) diff --git a/modules/authentication/proc-enabling-user-authentication-with-microsoft-azure.adoc b/modules/authentication/proc-enabling-user-authentication-with-microsoft-azure.adoc index 84b6b551c0..8e69fc9f29 100644 --- a/modules/authentication/proc-enabling-user-authentication-with-microsoft-azure.adoc +++ b/modules/authentication/proc-enabling-user-authentication-with-microsoft-azure.adoc @@ -133,12 +133,10 @@ Enter the configured secret variable name: `${AUTHENTICATION_AZURE_CLIENT_SECRET `frequency`::: Enter the schedule frequency in the cron, ISO duration, or human duration format. -+ In a large organization, user provisioning might take a long time, therefore avoid using a low value. `timeout`::: Enter the schedule timeout in the ISO duration or human duration format. -+ In a large organization, user provisioning might take a long time, therefore avoid using a low value. `initialDelay`::: From 9062414b73d0052b4025f1355f167081fd25e269 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Fabrice=20Flore-Th=C3=A9bault?= Date: Mon, 23 Jun 2025 16:03:18 +0200 Subject: [PATCH 21/27] Update modules/authentication/proc-enabling-user-authentication-with-microsoft-azure.adoc --- .../proc-enabling-user-authentication-with-microsoft-azure.adoc | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/modules/authentication/proc-enabling-user-authentication-with-microsoft-azure.adoc b/modules/authentication/proc-enabling-user-authentication-with-microsoft-azure.adoc index 8e69fc9f29..1a9cb5beac 100644 --- a/modules/authentication/proc-enabling-user-authentication-with-microsoft-azure.adoc +++ b/modules/authentication/proc-enabling-user-authentication-with-microsoft-azure.adoc @@ -44,7 +44,6 @@ Enter the backend authentication URI set in {product-short}: `pass:c,a,q[{my-pro .. On the *Applications > App registrations > __{my-product-app-name-in-azure}__ > Manage > API permissions* page, *Add a Permission*, *Microsoft Graph*, select the following permissions: Application Permissions:: -`User.Read.All`::: `GroupMember.Read.All`::: Enter permissions that enable provisioning user and groups to the {product-short} software catalog. + @@ -52,6 +51,7 @@ Optional: *Grant admin consent* for these permissions. Even if your company does not require admin consent, consider doing so as it means users do not need to individually consent the first time they access {product-short}. Delegated Permissions:: +`User.Read.All`::: `email`::: `offline_access`::: `openid`::: From 6a225c09bcfac823ff91740bfa6b27f173c89823 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Fabrice=20Flore-Th=C3=A9bault?= Date: Tue, 24 Jun 2025 11:24:26 +0200 Subject: [PATCH 22/27] Update modules/authentication/proc-enabling-user-authentication-with-microsoft-azure.adoc --- ...-enabling-user-authentication-with-microsoft-azure.adoc | 7 ++++--- 1 file changed, 4 insertions(+), 3 deletions(-) diff --git a/modules/authentication/proc-enabling-user-authentication-with-microsoft-azure.adoc b/modules/authentication/proc-enabling-user-authentication-with-microsoft-azure.adoc index 1a9cb5beac..15ed6e5355 100644 --- a/modules/authentication/proc-enabling-user-authentication-with-microsoft-azure.adoc +++ b/modules/authentication/proc-enabling-user-authentication-with-microsoft-azure.adoc @@ -473,10 +473,11 @@ WARNING: Use `dangerouslyAllowSignInWithoutUserInCatalog` to explore {product-sh . To verify user and group provisioning, check the console logs for `MicrosoftGraphOrgEntityProvider` events. + .Successful synchronization example: -[source,json] +[source] ---- -backend:start: {"class":"MicrosoftGraphOrgEntityProvider$1","level":"info","message":"Read 1 msgraph users and 1 msgraph groups in 2.2 seconds. Committing...","plugin":"catalog","service":"backstage","taskId":"MicrosoftGraphOrgEntityProvider:default:refresh","taskInstanceId":"88a67ce1-c466-41a4-9760-825e16b946be","timestamp":"2024-06-26 12:23:42"} -backend:start: {"class":"MicrosoftGraphOrgEntityProvider$1","level":"info","message":"Committed 1 msgraph users and 1 msgraph groups in 0.0 seconds.","plugin":"catalog","service":"backstage","taskId":"MicrosoftGraphOrgEntityProvider:default:refresh","taskInstanceId":"88a67ce1-c466-41a4-9760-825e16b946be","timestamp":"2024-06-26 12:23:42"} +2025-06-23T13:37:55.804Z catalog info Read 9 msgraph users and 3 msgraph groups in 1.5 seconds. Committing... class="MicrosoftGraphOrgEntityProvider" taskId="MicrosoftGraphOrgEntityProvider:providerId:refresh" taskInstanceId="e104a116-6481-4ceb-9bc4-0f8f9581f959" trace_id="e4c633659cffd6b1529afa55a5bfbad7" span_id="76affd0420e8baa6" trace_flags="01" + +2025-06-23T13:37:55.811Z catalog info Committed 9 msgraph users and 3 msgraph groups in 0.0 seconds. class="MicrosoftGraphOrgEntityProvider" taskId="MicrosoftGraphOrgEntityProvider:providerId:refresh" taskInstanceId="e104a116-6481-4ceb-9bc4-0f8f9581f959" trace_id="e4c633659cffd6b1529afa55a5bfbad7" span_id="76affd0420e8baa6" trace_flags="01" ---- . To verify {azure-short} user authentication: From 9c59b60c851d818749ecc0375dad6c3f6967d019 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Fabrice=20Flore-Th=C3=A9bault?= Date: Tue, 24 Jun 2025 11:24:59 +0200 Subject: [PATCH 23/27] Update modules/authentication/proc-enabling-user-authentication-with-microsoft-azure.adoc --- .../proc-enabling-user-authentication-with-microsoft-azure.adoc | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/modules/authentication/proc-enabling-user-authentication-with-microsoft-azure.adoc b/modules/authentication/proc-enabling-user-authentication-with-microsoft-azure.adoc index 15ed6e5355..8eb3727e21 100644 --- a/modules/authentication/proc-enabling-user-authentication-with-microsoft-azure.adoc +++ b/modules/authentication/proc-enabling-user-authentication-with-microsoft-azure.adoc @@ -482,5 +482,5 @@ WARNING: Use `dangerouslyAllowSignInWithoutUserInCatalog` to explore {product-sh . To verify {azure-short} user authentication: .. Go to the {product-short} login page. -.. Your {product-short} sign-in page displays *Sign in using {azure-short}* and the Guest user sign-in is disabled. +.. Your {product-short} sign-in page displays *Sign in using Microsoft* and the Guest user sign-in is disabled. .. Log in with an {azure-short} account. From 91938a737e1644cd4f8cfa2057e6e158f0a8a2a7 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Fabrice=20Flore-Th=C3=A9bault?= Date: Tue, 24 Jun 2025 11:29:10 +0200 Subject: [PATCH 24/27] Update modules/authentication/proc-enabling-user-authentication-with-microsoft-azure.adoc --- ...ling-user-authentication-with-microsoft-azure.adoc | 11 ++++++++--- 1 file changed, 8 insertions(+), 3 deletions(-) diff --git a/modules/authentication/proc-enabling-user-authentication-with-microsoft-azure.adoc b/modules/authentication/proc-enabling-user-authentication-with-microsoft-azure.adoc index 8eb3727e21..cea7ff8c81 100644 --- a/modules/authentication/proc-enabling-user-authentication-with-microsoft-azure.adoc +++ b/modules/authentication/proc-enabling-user-authentication-with-microsoft-azure.adoc @@ -459,9 +459,14 @@ signInPage: microsoft Enter the sign-in resolver name. Available resolvers: -* `userIdMatchingUserEntityAnnotation` -* `emailLocalPartMatchingUserEntityName` -* `emailMatchingUserEntityProfileEmail` +`emailMatchingUserEntityAnnotation`::::: +This resolver looks up the user by matching their Microsoft email to the email entity annotation. + +`emailLocalPartMatchingUserEntityName`::::: +This resolver looks up the user by matching their Microsoft email user name to the user entity name. + +`emailMatchingUserEntityProfileEmail`::::: +This resolver looks up the user by matching their Microsoft email to the user entity profile email. `dangerouslyAllowSignInWithoutUserInCatalog: true`:::: Configure the sign-in resolver to bypass the user provisioning requirement in the {product-short} software catalog. From 5e61c83de8e792034885606024ad567a4596759d Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Fabrice=20Flore-Th=C3=A9bault?= Date: Tue, 24 Jun 2025 11:35:46 +0200 Subject: [PATCH 25/27] consistent variable names MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit Signed-off-by: Fabrice Flore-Thébault --- ...r-authentication-with-microsoft-azure.adoc | 32 +++++++++---------- 1 file changed, 16 insertions(+), 16 deletions(-) diff --git a/modules/authentication/proc-enabling-user-authentication-with-microsoft-azure.adoc b/modules/authentication/proc-enabling-user-authentication-with-microsoft-azure.adoc index cea7ff8c81..af7798ec44 100644 --- a/modules/authentication/proc-enabling-user-authentication-with-microsoft-azure.adoc +++ b/modules/authentication/proc-enabling-user-authentication-with-microsoft-azure.adoc @@ -70,13 +70,13 @@ Optional: Enter optional custom scopes for the Microsoft Graph API that you defi . To add your {azure-short} credentials to {product-short}, add the following key/value pairs to link:{configuring-dynamic-plugins-book-url}#provisioning-your-custom-configuration[your {product-short} secrets]: -`AUTH_AZURE_TENANT_ID`:: +`AUTHENTICATION_AZURE_TENANT_ID`:: Enter your saved *Directory (tenant) ID*. -`AUTH_AZURE_CLIENT_ID`:: +`AUTHENTICATION_AZURE_CLIENT_ID`:: Enter your saved *Application (client) ID*. -`AUTH_AZURE_CLIENT_SECRET`:: +`AUTHENTICATION_AZURE_CLIENT_SECRET`:: Enter your saved *Application (client) secret*. . Enable the Microsoft Graph organization provisioning plugin (`backstage-plugin-catalog-backend-module-msgraph-dynamic`). @@ -104,9 +104,9 @@ catalog: microsoftGraphOrg: providerId: target: https://graph.microsoft.com/v1.0 - tenantId: ${AUTH_AZURE_TENANT_ID} - clientId: ${AUTH_AZURE_CLIENT_ID} - clientSecret: ${AUTH_AZURE_CLIENT_SECRET} + tenantId: ${AUTHENTICATION_AZURE_TENANT_ID} + clientId: ${AUTHENTICATION_AZURE_CLIENT_ID} + clientSecret: ${AUTHENTICATION_AZURE_CLIENT_SECRET} schedule: frequency: hours: 1 @@ -351,9 +351,9 @@ auth: providers: microsoft: production: - clientId: ${AUTH_AZURE_CLIENT_ID} - clientSecret: ${AUTH_AZURE_CLIENT_SECRET} - tenantId: ${AUTH_AZURE_TENANT_ID} + clientId: ${AUTHENTICATION_AZURE_CLIENT_ID} + clientSecret: ${AUTHENTICATION_AZURE_CLIENT_SECRET} + tenantId: ${AUTHENTICATION_AZURE_TENANT_ID} signInPage: microsoft ---- @@ -361,14 +361,14 @@ signInPage: microsoft Enter `production` to disable the **Guest** login option in the {product-short} login page. `clientId`:: -Enter the configured secret variable name: `${AUTH_AZURE_CLIENT_ID}`. +Enter the configured secret variable name: `${AUTHENTICATION_AZURE_CLIENT_ID}`. `clientSecret`:: Enter the configured secret variable name: -`${AUTH_AZURE_CLIENT_SECRET}`. +`${AUTHENTICATION_AZURE_CLIENT_SECRET}`. `tenantId`:: -Enter the configured secret variable name: `${AUTH_AZURE_TENANT_ID}`. +Enter the configured secret variable name: `${AUTHENTICATION_AZURE_TENANT_ID}`. `signInPage`:: Enter `microsoft` to set the {azure-short} provider as your {product-short} sign-in provider. @@ -390,7 +390,7 @@ auth: providers: microsoft: production: - domainHint: ${AUTH_AZURE_TENANT_ID} + domainHint: ${AUTHENTICATION_AZURE_TENANT_ID} ---- `additionalScopes`:: @@ -445,9 +445,9 @@ auth: providers: microsoft: production: - clientId: ${AUTH_AZURE_CLIENT_ID} - clientSecret: ${AUTH_AZURE_CLIENT_SECRET} - tenantId: ${AUTH_AZURE_TENANT_ID} + clientId: ${AUTHENTICATION_AZURE_CLIENT_ID} + clientSecret: ${AUTHENTICATION_AZURE_CLIENT_SECRET} + tenantId: ${AUTHENTICATION_AZURE_TENANT_ID} signIn: resolvers: - resolver: usernameMatchingUserEntityName From 1b496c0e449f1f2c5526747e6606468881d83a53 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Fabrice=20Flore-Th=C3=A9bault?= Date: Fri, 27 Jun 2025 15:13:34 +0200 Subject: [PATCH 26/27] Update modules/authentication/proc-enabling-user-authentication-with-microsoft-azure.adoc --- .../proc-enabling-user-authentication-with-microsoft-azure.adoc | 1 + 1 file changed, 1 insertion(+) diff --git a/modules/authentication/proc-enabling-user-authentication-with-microsoft-azure.adoc b/modules/authentication/proc-enabling-user-authentication-with-microsoft-azure.adoc index af7798ec44..fadf45266d 100644 --- a/modules/authentication/proc-enabling-user-authentication-with-microsoft-azure.adoc +++ b/modules/authentication/proc-enabling-user-authentication-with-microsoft-azure.adoc @@ -45,6 +45,7 @@ Enter the backend authentication URI set in {product-short}: `pass:c,a,q[{my-pro Application Permissions:: `GroupMember.Read.All`::: +`User.Read.All`::: Enter permissions that enable provisioning user and groups to the {product-short} software catalog. + Optional: *Grant admin consent* for these permissions. From fb71f9ec5990442dbf5088fb5b5e87434f8c3fbf Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Fabrice=20Flore-Th=C3=A9bault?= Date: Fri, 27 Jun 2025 15:13:54 +0200 Subject: [PATCH 27/27] Update modules/authentication/proc-enabling-user-authentication-with-microsoft-azure.adoc Co-authored-by: Jessica He --- .../proc-enabling-user-authentication-with-microsoft-azure.adoc | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/modules/authentication/proc-enabling-user-authentication-with-microsoft-azure.adoc b/modules/authentication/proc-enabling-user-authentication-with-microsoft-azure.adoc index fadf45266d..f20ddf0213 100644 --- a/modules/authentication/proc-enabling-user-authentication-with-microsoft-azure.adoc +++ b/modules/authentication/proc-enabling-user-authentication-with-microsoft-azure.adoc @@ -52,7 +52,7 @@ Optional: *Grant admin consent* for these permissions. Even if your company does not require admin consent, consider doing so as it means users do not need to individually consent the first time they access {product-short}. Delegated Permissions:: -`User.Read.All`::: +`User.Read`::: `email`::: `offline_access`::: `openid`:::