diff --git a/docs/docs/guides/integrate/azuread.md b/docs/docs/guides/integrate/azuread.md new file mode 100644 index 0000000000..889bb5a3da --- /dev/null +++ b/docs/docs/guides/integrate/azuread.md @@ -0,0 +1,89 @@ +--- +title: Connect with AzureAD +--- + +## AzureAD Tenant as Identity Provider for ZITADEL + +This guides shows you how to connect an AzureAD Tenant to ZITADEL. + +:::info +In ZITADEL you can connect an Identity Provider (IdP) like an AzureAD to your instance and provide it as default to all organizations or you can register the IdP to a specific organization only. This can also be done through your customers in a self-service fashion. +::: + +### Prerequisite + +You need to have access to an AzureAD Tenant. If you do not yet have one follow [this guide from Microsoft](https://docs.microsoft.com/en-us/azure/active-directory/develop/quickstart-create-new-tenant) to create one for free. + +### AzureAD Configuration + +#### Create a new Application + +Browse to the [App registration menus create dialog](https://portal.azure.com/#view/Microsoft_AAD_RegisteredApps/CreateApplicationBlade/quickStartType~/null/isMSAApp~/false) to create a new app. + +![Create an Application](/img/guides/azure_app_register.png) + +:::info +Mare sure to select `web` as application type in the `Redirect URI (optional)` section. +You can leave the second field empty since we will change this in the next step. +::: + +![Create an Application](/img/guides/azure_app.png) + +#### Configure Redirect URIS + +For this to work you need to whitelist the redirect URIs from your ZITADEL Instance. +In this example our test instance has the domain `test-qcon0h.zitadel.cloud`. In this case we need to whitelist these two entries: + +- `https://test-qcon0h.zitadel.cloud/ui/login/register/externalidp/callback` +- `https://test-qcon0h.zitadel.cloud/ui/login/login/externalidp/callback` + +:::info +To adapt this for you setup just replace the domain +::: + +![Configure Redirect URIS](/img/guides/azure_app_redirects.png) + +#### Create Client Secret + +To allow your ZITADEL to communicate with the AzureAD you need to create a Secret + +![Create Client Secret](/img/guides/azure_app_secrets.png) + +:::info +Please save this for the later configuration of ZITADEL +::: + +#### Configure ID Token Claims + +![Configure ID Token Claims](/img/guides/azure_app_token.png) + +### ZITADEL Configuration + +#### Create IdP + +Use the values displayed on the AzureAD Application page in your ZITADEL IdP Settings. + +- You can find the `issuer` for ZITADEL of your AzureAD Tenant in the `Endpoints submenu` +- The `Client ID` of ZITADEL corresponds to the `Application (client) ID` +- The `Client Secret` was generated during the `Create Client Secret` step + +![Azure Application](/img/guides/azure_app.png) + +![Create IdP](/img/guides/azure_zitadel_settings.png) + +#### Activate IdP + +Once you created the IdP you need to activate it, to make it usable for your users. + +![Activate the AzureAD](/img/guides/azure_zitadel_activate.png) + +![Active AzureAD](/img/guides/azure_zitadel_active.png) + +### Test the setup + +To test the setup use a incognito mode and browse to your login page. +If you succeeded you should see a new button which should redirect you to your AzureAD Tenant. + +![AzureAD Button](/img/guides/azure_zitadel_button.png) + +![AzureAD Login](/img/guides/azure_login.png) diff --git a/docs/docs/guides/integrate/identity-brokering.md b/docs/docs/guides/integrate/identity-brokering.md index 3b0fca5bbe..2e8748a288 100644 --- a/docs/docs/guides/integrate/identity-brokering.md +++ b/docs/docs/guides/integrate/identity-brokering.md @@ -97,7 +97,7 @@ ZITADEL will show a set of identity providers by default. This configuration can An organization's login settings will be shown -- as soon as the user has entered the loginname and ZITADEL can identitfy to which organization he belongs; or +- as soon as the user has entered the loginname and ZITADEL can identify to which organization he belongs; or - by sending a primary domain scope. To get your own configuration you will have to send the [primary domain scope](../../apis/openidoauth/scopes#reserved-scopes) in your [authorization request](../../guides/integrate/login-users#auth-request) . The primary domain scope will restrict the login to your organization, so only users of your own organization will be able to login, also your branding and policies will trigger. diff --git a/docs/sidebars.js b/docs/sidebars.js index 0288ce6b69..c7a5361aea 100644 --- a/docs/sidebars.js +++ b/docs/sidebars.js @@ -119,6 +119,7 @@ module.exports = { "guides/integrate/access-zitadel-apis", "guides/integrate/authenticated-mongodb-charts", "guides/integrate/auth0", + "guides/integrate/azuread", "guides/integrate/gitlab-self-hosted", "guides/integrate/login-users", "guides/integrate/serviceusers", diff --git a/docs/static/img/guides/azure_app.png b/docs/static/img/guides/azure_app.png new file mode 100644 index 0000000000..a7188e6696 Binary files /dev/null and b/docs/static/img/guides/azure_app.png differ diff --git a/docs/static/img/guides/azure_app_redirects.png b/docs/static/img/guides/azure_app_redirects.png new file mode 100644 index 0000000000..4368b4a2ff Binary files /dev/null and b/docs/static/img/guides/azure_app_redirects.png differ diff --git a/docs/static/img/guides/azure_app_register.png b/docs/static/img/guides/azure_app_register.png new file mode 100644 index 0000000000..f553c76b68 Binary files /dev/null and b/docs/static/img/guides/azure_app_register.png differ diff --git a/docs/static/img/guides/azure_app_secrets.png b/docs/static/img/guides/azure_app_secrets.png new file mode 100644 index 0000000000..3057a41c64 Binary files /dev/null and b/docs/static/img/guides/azure_app_secrets.png differ diff --git a/docs/static/img/guides/azure_app_token.png b/docs/static/img/guides/azure_app_token.png new file mode 100644 index 0000000000..b6588b5551 Binary files /dev/null and b/docs/static/img/guides/azure_app_token.png differ diff --git a/docs/static/img/guides/azure_login.png b/docs/static/img/guides/azure_login.png new file mode 100644 index 0000000000..ff12a9b995 Binary files /dev/null and b/docs/static/img/guides/azure_login.png differ diff --git a/docs/static/img/guides/azure_zitadel_activate.png b/docs/static/img/guides/azure_zitadel_activate.png new file mode 100644 index 0000000000..af4cb37115 Binary files /dev/null and b/docs/static/img/guides/azure_zitadel_activate.png differ diff --git a/docs/static/img/guides/azure_zitadel_active.png b/docs/static/img/guides/azure_zitadel_active.png new file mode 100644 index 0000000000..eabb06e0af Binary files /dev/null and b/docs/static/img/guides/azure_zitadel_active.png differ diff --git a/docs/static/img/guides/azure_zitadel_button.png b/docs/static/img/guides/azure_zitadel_button.png new file mode 100644 index 0000000000..143330a38b Binary files /dev/null and b/docs/static/img/guides/azure_zitadel_button.png differ diff --git a/docs/static/img/guides/azure_zitadel_settings.png b/docs/static/img/guides/azure_zitadel_settings.png new file mode 100644 index 0000000000..5c3a8ec627 Binary files /dev/null and b/docs/static/img/guides/azure_zitadel_settings.png differ