diff --git a/docusaurus/docs/guides/Identity_Providers/entra/index.md b/docusaurus/docs/guides/Identity_Providers/entra/index.md index 7b5952b76..146d2ac98 100644 --- a/docusaurus/docs/guides/Identity_Providers/entra/index.md +++ b/docusaurus/docs/guides/Identity_Providers/entra/index.md @@ -4,8 +4,6 @@ sidebar_label: Microsoft Entra ID slug: /identity-providers-for-browZer-entra --- -import IdPGeneric from '/docs/_browzer-idp-generic.mdx'; - Microsoft Entra ID for OpenZiti BrowZer - +### Get an Entra ID Account + +If you don't already have an account you can sign up at https://entra.microsoft.com/ + +### Add a new Application + +Once you have an Azure account, click on the "Entra" icon in the navbar: + +

+ +![Entra icon](/img/entra-1.jpg) + +

+
+Then click on the "App Registrations" item in the left navbar: + +

+ +![Entra App Registrations](/img/entra-3.jpg) + +

+
+Then Click "New registration": + +

+ +![Entra New registration](/img/entra-4.jpg) + +

+ +Now Register an Application: + +For the `Name` of the application, enter the URL where you will be hosting your browZer bootstrapper. For the example used in this documentation, we will use `https://entra-demo.ziti.netfoundry.io` + +For the `Supported account types`, click the top option (`single tenant`) + +For the `Redirect URI`, make sure to select `SPA` and then enter the URL where you will be hosting your browZer bootstrapper. For the example used in this documentation, we will use `https://entra-demo.ziti.netfoundry.io` + +For example: + +

+ +![Entra Register an Application](/img/entra-5.jpg) + +

+ +Once all the above fields have been filled in, click the `Register` button at the bottom of the form. + +### Token configuration + +Then click on the "Token configuration" item in the left navbar: + +

+ +![Entra icon](/img/entra-7.jpg) + +

+
+ +Then click "Add optional claim": + +

+ +![Entra icon](/img/entra-8.jpg) + +

+
+ +Then select `Access` as the token type, and select `email` from the list of claims. + +Then click the `Add` button at the bottom of the form. + +For example: + +

+ +![Entra icon](/img/entra-9.jpg) + +

+
+ +A form will appear. Select the checkbox `Microsoft Graph email permission`, +Then click the `Add` button. + +For example: + +

+ +![Entra icon](/img/entra-10.jpg) + +

+
+ +### Expose an API + +Then click on the "Expose an API" item in the left navbar: + +

+ +![Entra icon](/img/entra-11.jpg) + +

+
+ +Click `Add a scope` + +

+ +![Entra icon](/img/entra-12.jpg) + +

+
+ +For the `Application ID URI`, enter the URL where you will be hosting your browZer bootstrapper. For the example used in this documentation, we will use `https://entra-demo.ziti.netfoundry.io` + +

+ +![Entra icon](/img/entra-13.jpg) + +

+
+ +For the `Scope name`, enter `OpenZiti.BrowZer`. + +For `Who can consent`, choose `Admins and users`. + +Enter what you like for the descriptions. + +Make sure the `State` is `Enabled`. + +Then click the `Add scope` button at the borrom of the form. + +For example: + +

+ +![Entra icon](/img/entra-14.jpg) + +

+
+ +### Owners + +Then click on the "Owners" item in the left navbar: + +

+ +![Entra icon](/img/entra-18.jpg) + +

+
+ +Add yourself as an owner of the application: + +

+ +![Entra icon](/img/entra-19.jpg) + +

+
+ + +### API permissions + +Then click on the "API permissions" item in the left navbar: + +

+ +![Entra icon](/img/entra-15.jpg) + +

+
+ +The `User.Read` permission is not needed for browZer, so you may use the 3-dot menu on the right side to remove it. + +

+ +![Entra icon](/img/entra-16.jpg) + +

+
+ +Now click `Add a permission`. + +

+ +![Entra icon](/img/entra-17.jpg) + +

+
+ +Now click `My APIs`. + +

+ +![Entra icon](/img/entra-22.jpg) + +

+
+ +Now click the item representing the URL where you will be hosting your browZer bootstrapper. For the example used in this documentation, we will use `https://entra-demo.ziti.netfoundry.io` + +

+ +![Entra icon](/img/entra-23.jpg) + +

+
+ +Select the checkbox for `OpenZiti.BrowZer`, then click the `Add permissions` button at the bottom of the form. + +

+ +![Entra icon](/img/entra-24.jpg) + +

+
+ +### Manifest + +Then click on the "Manifest" item in the left navbar: + + +Now click `Microsoft Graph App Manifest`, then scroll the JSON down to line 31 where you see `requestedAccessTokenVersion`. This field defaults to `null`. +Change the value to `2`. This is extremely important. Failure to complete this step will results in invalid `access_token`'s being produced by Entra during the `PKCE` process performed between browZer and Entra when a user authenticates. + +Then click `Save` + +For example: + +

+ +![Entra icon](/img/entra-26.jpg) + +

+
+ +### Gather IdP Information + +Your OpenZiti network must be configured to become aware of your Entra identity provider. OpenZiti refers to the identity provider as an `External JWT Signer`. Before you can set up the new JWT signer, you must gather some information from the new Entra Application that you just created: +- the `clientId` +- the `issuer` +- the `jwks_uri` +
+
+ +#### Gather `clientId` + +The `clientID` value can be found in the `Overview` tab of the Application you Registered above: + +

+ +![Auth0 clientId](/img/entra-27.jpg) + +

+
+ +#### Gather `issuer` + +The `issuer` can be found via the openid-configuration endpoint that all OIDC-compliant identity providers expose. + +The openid-configuration endpoint URL for Entra looks like this: + +

+ +`https://login.microsoftonline.com//v2.0/.well-known/openid-configuration` + +

+ +where the value for `` can be found in the `Overview` tab of the Application you Registered above: + +

+ +![Auth0 Domain](/img/entra-28.jpg) + +

+ +When you enter the openid-configuration endpoint URL (`https://login.microsoftonline.com//v2.0/.well-known/openid-configuration`) into a browser, you will receive a response resembling the following: + +

+ +![Auth0 OIDC config](/img/entra-29.jpg) + +

+
+ +Take note of the `issuer` value. +
+ + +#### Gather `jwks_uri` +Take note of the `jwks_uri` value returned from the above openid-configuration endpoint URL. +
+ +### Create External JWT Signer +Using the values described above, use the `ziti` CLI to configure an external JWT signer that represents your Auth0 identity provider. You can find details on how to do this in the [BrowZer Quickstart documentation](/docs/learn/quickstarts/browzer/) + diff --git a/docusaurus/static/img/entra-1.jpg b/docusaurus/static/img/entra-1.jpg new file mode 100644 index 000000000..b14f06074 Binary files /dev/null and b/docusaurus/static/img/entra-1.jpg differ diff --git a/docusaurus/static/img/entra-10.jpg b/docusaurus/static/img/entra-10.jpg new file mode 100644 index 000000000..1889359d2 Binary files /dev/null and b/docusaurus/static/img/entra-10.jpg differ diff --git a/docusaurus/static/img/entra-11.jpg b/docusaurus/static/img/entra-11.jpg new file mode 100644 index 000000000..f8ccb2869 Binary files /dev/null and b/docusaurus/static/img/entra-11.jpg differ diff --git a/docusaurus/static/img/entra-12.jpg b/docusaurus/static/img/entra-12.jpg new file mode 100644 index 000000000..3d1e7d63b Binary files /dev/null and b/docusaurus/static/img/entra-12.jpg differ diff --git a/docusaurus/static/img/entra-13.jpg b/docusaurus/static/img/entra-13.jpg new file mode 100644 index 000000000..fac0b11a0 Binary files /dev/null and b/docusaurus/static/img/entra-13.jpg differ diff --git a/docusaurus/static/img/entra-14.jpg b/docusaurus/static/img/entra-14.jpg new file mode 100644 index 000000000..6d67a8081 Binary files /dev/null and b/docusaurus/static/img/entra-14.jpg differ diff --git a/docusaurus/static/img/entra-15.jpg b/docusaurus/static/img/entra-15.jpg new file mode 100644 index 000000000..ff07d61f9 Binary files /dev/null and b/docusaurus/static/img/entra-15.jpg differ diff --git a/docusaurus/static/img/entra-16.jpg b/docusaurus/static/img/entra-16.jpg new file mode 100644 index 000000000..390a4e683 Binary files /dev/null and b/docusaurus/static/img/entra-16.jpg differ diff --git a/docusaurus/static/img/entra-17.jpg b/docusaurus/static/img/entra-17.jpg new file mode 100644 index 000000000..6b685e7fa Binary files /dev/null and b/docusaurus/static/img/entra-17.jpg differ diff --git a/docusaurus/static/img/entra-18.jpg b/docusaurus/static/img/entra-18.jpg new file mode 100644 index 000000000..07bfa7d56 Binary files /dev/null and b/docusaurus/static/img/entra-18.jpg differ diff --git a/docusaurus/static/img/entra-19.jpg b/docusaurus/static/img/entra-19.jpg new file mode 100644 index 000000000..2223b0bd9 Binary files /dev/null and b/docusaurus/static/img/entra-19.jpg differ diff --git a/docusaurus/static/img/entra-22.jpg b/docusaurus/static/img/entra-22.jpg new file mode 100644 index 000000000..1712b00f4 Binary files /dev/null and b/docusaurus/static/img/entra-22.jpg differ diff --git a/docusaurus/static/img/entra-23.jpg b/docusaurus/static/img/entra-23.jpg new file mode 100644 index 000000000..d49508238 Binary files /dev/null and b/docusaurus/static/img/entra-23.jpg differ diff --git a/docusaurus/static/img/entra-24.jpg b/docusaurus/static/img/entra-24.jpg new file mode 100644 index 000000000..29865a951 Binary files /dev/null and b/docusaurus/static/img/entra-24.jpg differ diff --git a/docusaurus/static/img/entra-26.jpg b/docusaurus/static/img/entra-26.jpg new file mode 100644 index 000000000..e72b8ebf9 Binary files /dev/null and b/docusaurus/static/img/entra-26.jpg differ diff --git a/docusaurus/static/img/entra-27.jpg b/docusaurus/static/img/entra-27.jpg new file mode 100644 index 000000000..f80ee2e8b Binary files /dev/null and b/docusaurus/static/img/entra-27.jpg differ diff --git a/docusaurus/static/img/entra-28.jpg b/docusaurus/static/img/entra-28.jpg new file mode 100644 index 000000000..628055b88 Binary files /dev/null and b/docusaurus/static/img/entra-28.jpg differ diff --git a/docusaurus/static/img/entra-29.jpg b/docusaurus/static/img/entra-29.jpg new file mode 100644 index 000000000..a53d247bf Binary files /dev/null and b/docusaurus/static/img/entra-29.jpg differ diff --git a/docusaurus/static/img/entra-3.jpg b/docusaurus/static/img/entra-3.jpg new file mode 100644 index 000000000..6889abd7a Binary files /dev/null and b/docusaurus/static/img/entra-3.jpg differ diff --git a/docusaurus/static/img/entra-4.jpg b/docusaurus/static/img/entra-4.jpg new file mode 100644 index 000000000..4a404fb68 Binary files /dev/null and b/docusaurus/static/img/entra-4.jpg differ diff --git a/docusaurus/static/img/entra-5.jpg b/docusaurus/static/img/entra-5.jpg new file mode 100644 index 000000000..6847ee72d Binary files /dev/null and b/docusaurus/static/img/entra-5.jpg differ diff --git a/docusaurus/static/img/entra-7.jpg b/docusaurus/static/img/entra-7.jpg new file mode 100644 index 000000000..ba78ff0d0 Binary files /dev/null and b/docusaurus/static/img/entra-7.jpg differ diff --git a/docusaurus/static/img/entra-8.jpg b/docusaurus/static/img/entra-8.jpg new file mode 100644 index 000000000..90be73b92 Binary files /dev/null and b/docusaurus/static/img/entra-8.jpg differ diff --git a/docusaurus/static/img/entra-9.jpg b/docusaurus/static/img/entra-9.jpg new file mode 100644 index 000000000..36c0db978 Binary files /dev/null and b/docusaurus/static/img/entra-9.jpg differ