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 f90c846dfe..be673067c5 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::modules/authentication/proc-enabling-user-authentication-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 ee085c5f68..415f8100fc 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:enabling-user-authentication-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:enabling-user-authentication-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..f20ddf0213 --- /dev/null +++ b/modules/authentication/proc-enabling-user-authentication-with-microsoft-azure.adoc @@ -0,0 +1,492 @@ +[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`:: +This is the {azure-brand-name} authorization server, which enables the authentication flow. + +`graph.microsoft.com`:: +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-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 link:https://entra.microsoft.com/[Microsoft Entra admin center]. + +.. 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: + +Name:: +Enter a name to identify your application in {azure-short}, such as __{my-product-app-name-in-azure}__. + +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]` + +.. 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:: +`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. +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`::: +`email`::: +`offline_access`::: +`openid`::: +`profile`::: +Enter permissions that enable authenticating users. ++ +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*. + +.. Save the following values for the next step: +- **Directory (tenant) ID** +- **Application (client) ID** +- **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]: + +`AUTHENTICATION_AZURE_TENANT_ID`:: +Enter your saved *Directory (tenant) ID*. + +`AUTHENTICATION_AZURE_CLIENT_ID`:: +Enter your saved *Application (client) ID*. + +`AUTHENTICATION_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::{docdir}/artifacts/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: ${AUTHENTICATION_AZURE_TENANT_ID} + clientId: ${AUTHENTICATION_AZURE_CLIENT_ID} + clientSecret: ${AUTHENTICATION_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: ${AUTHENTICATION_AZURE_CLIENT_ID} + clientSecret: ${AUTHENTICATION_AZURE_CLIENT_SECRET} + tenantId: ${AUTHENTICATION_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: `${AUTHENTICATION_AZURE_CLIENT_ID}`. + +`clientSecret`:: +Enter the configured secret variable name: +`${AUTHENTICATION_AZURE_CLIENT_SECRET}`. + +`tenantId`:: +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. + +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: ${AUTHENTICATION_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: `userIdMatchingUserEntityAnnotation`. ++ +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: ${AUTHENTICATION_AZURE_CLIENT_ID} + clientSecret: ${AUTHENTICATION_AZURE_CLIENT_SECRET} + tenantId: ${AUTHENTICATION_AZURE_TENANT_ID} + signIn: + resolvers: + - resolver: usernameMatchingUserEntityName + dangerouslyAllowSignInWithoutUserInCatalog: true +signInPage: microsoft +---- + +`resolver`:::: +Enter the sign-in resolver name. +Available resolvers: + +`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. ++ +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 for `MicrosoftGraphOrgEntityProvider` events. ++ +.Successful synchronization example: +[source] +---- +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: +.. Go to the {product-short} login page. +.. 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. 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.