From c912cd5cdd8f3779009aca61e209f3094560dca9 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Jonas=20Kr=C3=BCger=20Svensson?= Date: Mon, 18 Oct 2021 14:07:52 +0200 Subject: [PATCH] Fix documentation wording, based on @terjelafton's feedback in intility/templates #56 --- docs/docs/multi-tenant/azure_setup.mdx | 24 ++++++++++++------------ docs/docs/single-tenant/azure_setup.mdx | 24 ++++++++++++------------ 2 files changed, 24 insertions(+), 24 deletions(-) diff --git a/docs/docs/multi-tenant/azure_setup.mdx b/docs/docs/multi-tenant/azure_setup.mdx index aa8f6a9..da97f4b 100644 --- a/docs/docs/multi-tenant/azure_setup.mdx +++ b/docs/docs/multi-tenant/azure_setup.mdx @@ -3,8 +3,8 @@ title: Azure configuration sidebar_position: 1 --- -For Azure AD authentication to cover both direct API use, and usage from the OpenAPI (swagger) documentation, -we'll need to do create two application registrations. +We'll need to create two application registrations for Azure AD authentication to cover both direct API +use and usage from the OpenAPI (swagger) documentation. We'll start with the API. @@ -15,7 +15,7 @@ Head over to [Azure -> Azure Active Directory -> App registrations](https://portal.azure.com/#blade/Microsoft_AAD_IAM/ActiveDirectoryMenuBlade/RegisteredApps), and create a new registration. -Select a fitting name for your project, this name will be presented to the user during consent. +Select a fitting name for your project; Azure will present the name to the user during consent. * `Supported account types`: `Multitenant` - If you want to create a multi-tenant application, you should head over to the [multi-tenant documentation](../multi-tenant/azure_setup.mdx) @@ -28,7 +28,7 @@ Press **Register** ### Step 2 - Change token version to `v2` First we'll change the token version to version 2. In the left menu bar, click `Manifest` and find the line -that says `accessTokenAcceptedVersion`. Change it's value from `null` to `2`. +that says `accessTokenAcceptedVersion`. Change its value from `null` to `2`. ![2_manifest](../../static/img/single-tenant/2_manifest.png) @@ -58,7 +58,7 @@ APP_CLIENT_ID= ![4_add_scope](../../static/img/multi-tenant/4_add_scope.png) -Add a scope named `user_impersonation`, that can be consented by `Admins and users`. +Add a scope named `user_impersonation` that can be consented by `Admins and users`. ![5_add_scope_props](../../static/img/multi-tenant/5_add_scope_props.png) You can use the following descriptions: @@ -68,13 +68,13 @@ Access API as user Allows the app to access the API as the user. Access API as you -Allows the app to acces the API as you. +Allows the app to access the API as you. ``` ## OpenAPI Documentation -Our OpenAPI documentation will use a flow called `Authorization Code Grant Flow, with Proof Key for Code Exchange`. -It's a flow that allow a user of a Single-Page Application safely log in, consent to permissions and fetch an `access_token` -in the `JWT` format. When the user then click `Try out` on the APIs, the `access_token` is attached to the header as a `Bearer ` token. +Our OpenAPI documentation will use the `Authorization Code Grant Flow, with Proof Key for Code Exchange` flow. +It's a flow that enables a user of a Single-Page Application to safely log in, consent to permissions and fetch an `access_token` +in the `JWT` format. When the user clicks `Try out` on the APIs, the `access_token` is attached to the header as a `Bearer ` token. This is the token the backend will validate. So, let's set it up! @@ -98,7 +98,7 @@ Press **Register** ### Step 2 - Change token version to `v2` Like last time, we'll change the token version to version 2. In the left menu bar, click `Manifest` and find the line -that says `accessTokenAcceptedVersion`. Change it's value from `null` to `2`. +that says `accessTokenAcceptedVersion`. Change its value from `null` to `2`. ![3_manifest](../../static/img/single-tenant/2_manifest.png) @@ -117,9 +117,9 @@ APP_CLIENT_ID= OPENAPI_CLIENT_ID= ```` -### Step 4 - Allow OpenAPI to talk to the Backend +### Step 4 - Allow OpenAPI to talk to the backend -To allow OpenAPI to talk to the Backend API, you need to add API permissions to the OpenAPI app registration. +To allow OpenAPI to talk to the backend API, you must add API permissions to the OpenAPI app registration. In the left menu, go to **API Permissions** and **Add a permission**. ![8_api_permissions](../../static/img/multi-tenant/8_api_permissions.png) diff --git a/docs/docs/single-tenant/azure_setup.mdx b/docs/docs/single-tenant/azure_setup.mdx index 9fb92ee..88d53ce 100644 --- a/docs/docs/single-tenant/azure_setup.mdx +++ b/docs/docs/single-tenant/azure_setup.mdx @@ -3,8 +3,8 @@ title: Azure configuration sidebar_position: 1 --- -For Azure AD authentication to cover both direct API use, and usage from the OpenAPI (swagger) documentation, -we'll need to do create two application registrations. +We'll need to create two application registrations for Azure AD authentication to cover both direct API +use and usage from the OpenAPI (swagger) documentation. We'll start with the API. @@ -15,7 +15,7 @@ Head over to [Azure -> Azure Active Directory -> App registrations](https://portal.azure.com/#blade/Microsoft_AAD_IAM/ActiveDirectoryMenuBlade/RegisteredApps), and create a new registration. -Select a fitting name for your project, this name will be presented to the user during consent. +Select a fitting name for your project; Azure will present the name to the user during consent. * `Supported account types`: `Single tenant` - If you want to create a multi-tenant application, you should head over to the [multi-tenant documentation](../multi-tenant/azure_setup.mdx) @@ -29,7 +29,7 @@ Press **Register** ### Step 2 - Change token version to `v2` First we'll change the token version to version 2. In the left menu bar, click `Manifest` and find the line -that says `accessTokenAcceptedVersion`. Change it's value from `null` to `2`. +that says `accessTokenAcceptedVersion`. Change its value from `null` to `2`. ![2_manifest](../../static/img/single-tenant/2_manifest.png) @@ -60,7 +60,7 @@ TENANT_ID= ![4_add_scope](../../static/img/single-tenant/4_add_scope.png) -Add a scope named `user_impersonation`, that can be consented by `Admins and users`. +Add a scope named `user_impersonation` that can be consented by `Admins and users`. ![5_add_scope_props](../../static/img/single-tenant/5_add_scope_props.png) You can use the following descriptions: @@ -70,13 +70,13 @@ Access API as user Allows the app to access the API as the user. Access API as you -Allows the app to acces the API as you. +Allows the app to access the API as you. ``` ## OpenAPI Documentation -Our OpenAPI documentation will use a flow called `Authorization Code Grant Flow, with Proof Key for Code Exchange`. -It's a flow that allow a user of a Single-Page Application safely log in, consent to permissions and fetch an `access_token` -in the `JWT` format. When the user then click `Try out` on the APIs, the `access_token` is attached to the header as a `Bearer ` token. +Our OpenAPI documentation will use the `Authorization Code Grant Flow, with Proof Key for Code Exchange` flow. +It's a flow that enables a user of a Single-Page Application to safely log in, consent to permissions and fetch an `access_token` +in the `JWT` format. When the user clicks `Try out` on the APIs, the `access_token` is attached to the header as a `Bearer ` token. This is the token the backend will validate. So, let's set it up! @@ -100,7 +100,7 @@ Press **Register** ### Step 2 - Change token version to `v2` Like last time, we'll change the token version to version 2. In the left menu bar, click `Manifest` and find the line -that says `accessTokenAcceptedVersion`. Change it's value from `null` to `2`. +that says `accessTokenAcceptedVersion`. Change its value from `null` to `2`. ![3_manifest](../../static/img/single-tenant/2_manifest.png) @@ -120,9 +120,9 @@ TENANT_ID= OPENAPI_CLIENT_ID= ```` -### Step 4 - Allow OpenAPI to talk to the Backend +### Step 4 - Allow OpenAPI to talk to the backend -To allow OpenAPI to talk to the Backend API, you need to add API permissions to the OpenAPI app registration. +To allow OpenAPI to talk to the backend API, you must add API permissions to the OpenAPI app registration. In the left menu, go to **API Permissions** and **Add a permission**. ![8_api_permissions](../../static/img/single-tenant/8_api_permissions.png)