Add managed domains to idp doc (#3443)

* add managed domains section

Author: mooreds

astro/src/content/docs/_shared/_identity-provider-limits.mdx

@@ -1,3 +1,3 @@
-Some Identity Providers, such as the Google and OIDC Identity Providers, request access tokens from a configured remote URL. Remote servers must respond within a certain time frame or the login workflow will fail.
+Some Identity Providers, such as the Google and OIDC Identity Providers, request access tokens from a configured remote URL. Remote servers must respond within a certain time frame or the login workflow will fail. The limit is currently 10 seconds. It is not configurable.
 
-The limit is currently 10 seconds. It is not configurable.
+Managed domains can only be used with OIDC and SAMLv2 Identity Providers.

astro/src/content/docs/lifecycle/authenticate-users/identity-providers/_managed-domains-description.mdx

@@ -5,3 +5,5 @@ You may optionally scope this identity provider to one or more managed domains.
 Adding one or more managed domains for this configuration will cause this provider not to be displayed as a button on your login page. Instead of a button the login form will first ask the user for their email address. If the user's email address matches one of the configured domains the user will then be redirected to this login provider to complete authentication. If the user's email address does not match one of the configured domains, the user will be prompted for a password and they will be authenticated using FusionAuth.
 
 These configured domains will be used by the [Lookup API](/docs/apis/identity-providers/#lookup-an-identity-provider).
+
+Learn more about [managed domains](/docs/lifecycle/authenticate-users/identity-providers/#managed-domains).

astro/src/content/docs/lifecycle/authenticate-users/identity-providers/index.mdx

@@ -9,6 +9,7 @@ navOrder: 0
 tags: authorization hub
 ---
 import Aside from 'src/components/Aside.astro';
+import Breadcrumb from 'src/components/Breadcrumb.astro';
 import InlineField from 'src/components/InlineField.astro';
 import InlineUIElement from 'src/components/InlineUIElement.astro';
 import ScrollRef from 'src/components/ScrollRef.astro';
@@ -19,9 +20,9 @@ import IdentityProviderLimitations from 'src/content/docs/_shared/_identity-prov
 
 Identity Providers allow you to enable third-party login in FusionAuth. This includes social options such as Facebook and Google, and enterprise options such as OIDC and SAML.
 
-Find the FusionAuth Identity Providers in the UI by navigating to <strong>Settings -> Identity Providers</strong> or use the [Identity Providers](/docs/apis/identity-providers/) APIs.
+Find the FusionAuth Identity Providers in the UI by navigating to <Breadcrumb>Settings -> Identity Providers</Breadcrumb> or use the [Identity Providers](/docs/apis/identity-providers/) APIs.
 
-<img src="/img/docs/get-started/core-concepts/identity-providers.png" alt="Identity Providers" width="1200" role="bottom-cropped" />
+![Identity Providers](/img/docs/get-started/core-concepts/identity-providers.png)
 
 ## Social Identity Providers
 
@@ -59,15 +60,15 @@ Identity providers can be configured to set a limit on the number of links that
 
 In the following, we have enabled "Limit links per user" on the Default tenant and set a "Maximum link count" of `2`. With this configuration, a user will only be able to establish at most two links for this IdP specifically.
 
-<img src="/img/docs/lifecycle/authenticate-users/identity-providers/identity-provider-tenant-config.png" alt="Identity Providers" width="1200" role="bottom-cropped" />
+![Identity Providers](/img/docs/lifecycle/authenticate-users/identity-providers/identity-provider-tenant-config.png)
 
 ## Identity Providers and Applications
 
 Identity providers can be enabled or disabled on a per application basis.
 
 In the following screenshot you will see that we have enabled this login provider for the Pied Piper application and enabled "Create registration". Enabling "Create registration" means that a user does not need to be manually registered for the application prior to using this login provider.
 
-<img src="/img/docs/lifecycle/authenticate-users/identity-providers/identity-provider-application-config.png" alt="Identity Providers" width="1200" role="bottom-cropped" />
+![Identity Providers](/img/docs/lifecycle/authenticate-users/identity-providers/identity-provider-application-config.png)
 
 For example, when a new user attempts to log into Pied Piper using Google, if their user does not exist in FusionAuth it will be created dynamically, and if the Create registration toggle has been enabled, the user will also be registered for Pied Piper and assigned any default roles assigned by the application.
 
@@ -85,7 +86,7 @@ You can have different identity provider configurations for different applicatio
 
 You can override none, some or all of the available configuration values by expanding the <InlineUIElement>Overrides</InlineUIElement> element for the application's identity provider setting. You may also modify the <InlineField>identityProvider.applicationConfiguration</InlineField> values using the API.
 
-<img src="/img/docs/lifecycle/authenticate-users/identity-providers/override-identity-provider-settings.png" alt="Overriding Identity Provider settings" width="1200" role="top-cropped" />
+![Overriding Identity Provider settings](/img/docs/lifecycle/authenticate-users/identity-providers/override-identity-provider-settings.png)
 
 For certain Identity Providers, there are no override settings since you can create more than one. You can have multiple configurations for these Identity Provider types:
 
@@ -113,6 +114,20 @@ An email address or domain may be provided in the `login_hint` request parameter
 
 You can read more about the `login_hint` and `idp_hint` parameters in the [OAuth Endpoints documentation](/docs/lifecycle/authenticate-users/oauth/endpoints).
 
+## Managed Domains
+
+For SAML v2 or OIDC identity providers, you can optionally enable managed domains. This feature is not available for any other types of identity providers.
+
+If users share a common email domain, such as `@example.com`, you can use managed domains to streamline their login process. Here's how it works:
+
+- On the login page, users are prompted to enter their email address.
+- If the email domain matches a managed domain defined in the identity provider settings, the user is automatically redirected to the configured identity provider for authentication.
+- If the email domain does not match, the user proceeds to the standard email/password login flow.
+
+Multiple email address domains can be managed by the same identity provider. Multiple identity providers can be configured with managed domains. Each email domain can be managed by at most one identity provider in a FusionAuth instance.
+
+Configuring managed domains on an identity provider and then configuring the identity provider to be enabled for an application changes the login page experience for all users logging into this application. Every user viewing the application login page will be required to enter their email address first. 
+
 ## Account Security
 
 When you configure an Identity Provider, you are explicitly trusting this federated identity system to authenticate users. MFA requirements and configuration, roles and groups, email or phone verification, and account identifiers are controlled by the provider.
@@ -132,7 +147,7 @@ Such attacks can be mitigated by:
 
 ## Linking Strategies
 
-<img src="/img/docs/lifecycle/authenticate-users/identity-providers/linking-strategy.png" alt="Linking Strategies"  role="top-cropped bottom-cropped"  width="1200" />
+![Linking Strategies](/img/docs/lifecycle/authenticate-users/identity-providers/linking-strategy.png)
 
 The linking strategy is used when creating the link between the Identity Provider and the user account in FusionAuth.
 
@@ -189,7 +204,7 @@ Richard is logging into Pied Piper. He has an account in FusionAuth with the ema
 * He logs in with `[email protected]`.
 * The FusionAuth account with the email `[email protected]` is linked to the Hooli `[email protected]` account.
 
-<img src="/img/docs/lifecycle/authenticate-users/identity-providers/idp-linking-pending-link.png" alt="Screen prompting a user to connect their pending link account." width="1200" role="bottom-cropped" />
+![Screen prompting a user to connect their pending link account.](/img/docs/lifecycle/authenticate-users/identity-providers/idp-linking-pending-link.png)
 
 ### Anonymous Link
 
@@ -205,7 +220,7 @@ Richard is logging into Pied Piper. He doesn't have an account in FusionAuth.
 * There is an account created in FusionAuth with no username or email address. It is not a full account.
 * Richard can interact with Pied Piper (a JWT is issued, etc), but cannot use FusionAuth workflows like 'forgot password'.
 
-<img src="/img/docs/lifecycle/authenticate-users/identity-providers/idp-linking-anonymous-account.png" alt="Admin view of a user who has linked anonymously." width="1200" role="bottom-cropped" />
+![Admin view of a user who has linked anonymously.](/img/docs/lifecycle/authenticate-users/identity-providers/idp-linking-anonymous-account.png)
 
 #### Anonymous Link, No Email Or Username Returned By The IdP
 
@@ -256,7 +271,7 @@ Richard is logging into Pied Piper. He doesn't have an account in FusionAuth.
 
 Here's an example of the error page:
 
-<img src="/img/docs/lifecycle/authenticate-users/identity-providers/idp-linking-user-must-exist.png" alt="Error when a user must exist for successful linking." width="1200" role="bottom-cropped" />
+![Error when a user must exist for successful linking.](/img/docs/lifecycle/authenticate-users/identity-providers/idp-linking-user-must-exist.png)
 
 #### Link On Email, User Account Is Created If Needed
 

config/vale/styles/config/vocabularies/FusionAuth/accept.txt

@@ -839,7 +839,7 @@ idp_display_name
 idp_hint
 idp_request
 idp_token_or_code
-idp|IDP
+idp|IdP
 impactful
 incentivizes
 inclusivity