Skip to content

Commit

Permalink
Merge pull request #1262 from solliancenet/lino-docs-080
Browse files Browse the repository at this point in the history 
Restructure of the Entra ID App registration documents
  • Loading branch information
@ciprianjichici
ciprianjichici authored Jul 23, 2024
2 parents 8fd35ae + 2612ce2 commit 0b95206
Show file tree
Hide file tree
Showing 8 changed files with 176 additions and 155 deletions.
21 changes: 3 additions & 18 deletions docs/deployment/authentication-authorization/authorization-setup-entra.md
View file
Original file line number Diff line number Diff line change
Expand Up @@ -2,9 +2,9 @@

FoundationaLLM comes with out-of-the-box support for Microsoft Entra ID authorization. This means that you can use your Microsoft Entra ID to setup authorization access to FoundationaLLM's platform.

### Create the client application
### Create the API application

#### Register the client application in the Microsoft Entra ID admin center
#### Register the API application in the Microsoft Entra ID admin center

1. Sign in to the [Microsoft Entra ID admin center](https://entra.microsoft.com/) as at least a Cloud Application Administrator.
2. Browse to **Identity** > **Applications** > **App registrations**.
Expand Down Expand Up @@ -54,19 +54,4 @@ FoundationaLLM comes with out-of-the-box support for Microsoft Entra ID authoriz

2. Enter `http://localhost` under **Redirect URIs**. Then, below **Implicit grant and hybrid flows**, select both **Access tokens** and **ID tokens**. Finally, select **Configure**.

![Select "Access Tokens" and "ID Tokens".](media/set-grant-and-hybrid-flows.png)

### Update App Configuration settings

1. Sign in to the [Azure portal](https://portal.azure.com/) as at least a Contributor.
2. Navigate to the resource group that was created as part of the deployment.
3. Select the **App Configuration** resource and select **Configuration explorer** to view the values.
4. Enter `authorization` in the search box to filter the results.
5. Check the box next to **Key** in the header to select all items.
6. Find the key for `FoundationaLLM:APIs:AuthorizationAPI:APIScope` and click on edit.
7. Replace the value with the value from the scope we created earlier, as `api://FoundationaLLM-Authorization`
8. Select **Apply** to save the changes.

## Next steps

Now that Entra authorization is fully configured, navigate to your Entra ID management console and make sure you completed all app registrations for all the other apps mentioned in the deployment documentation.
![Select "Access Tokens" and "ID Tokens".](media/set-grant-and-hybrid-flows.png)
67 changes: 1 addition & 66 deletions docs/deployment/authentication-authorization/core-authentication-setup-entra.md
View file
Original file line number Diff line number Diff line change
Expand Up @@ -176,69 +176,4 @@ If you wish to [configure authentication in Postman](../../development/directly-

The client application's configured permissions should now look like the following:

![The client application's configured permissions are displayed.](media/entra-app-configured-permissions.png)

### Update App Configuration settings

1. Sign in to the [Azure portal](https://portal.azure.com/) as at least a Contributor.
2. Navigate to the resource group that was created as part of the deployment.
3. Select the **App Configuration** resource and select **Configuration explorer** to view the values.
4. Enter `entra` in the search box to filter the results.
5. Check the box next to **Key** in the header to select all items.
6. Select **Edit** to open a JSON editor for the selected items.

![The configuration settings are filtered by entra and all items are selected.](media/app-configuration-entra-settings.png "App Configuration settings for Microsoft Entra ID authentication")

7. Replace the values for the following settings with the values that you recorded earlier:
- `FoundationaLLM:Chat:Entra:ClientId`: The **Application (client) ID** of the client application that you [created earlier](#register-the-client-application-in-the-microsoft-entra-admin-center).
- `FoundationaLLM:Chat:Entra:Scopes`: The fully-qualified scopes path for the API application that you [created earlier](#expose-an-api-for-the-api-application). For example, it should look something like `api://FoundationaLLM-Core/Data.Read`.
- `FoundationaLLM:Chat:Entra:TenantId`: The **Directory (tenant) ID** of the client application that you [created earlier](#register-the-client-application-in-the-microsoft-entra-admin-center).
- `FoundationaLLM:CoreAPI:Entra:ClientId`: The **Application (client) ID** of the API application that you [created earlier](#register-the-api-application-in-the-microsoft-entra-admin-center).
- `FoundationaLLM:CoreAPI:Entra:TenantId`: The **Directory (tenant) ID** of the API application that you [created earlier](#register-the-api-application-in-the-microsoft-entra-admin-center).

8. Validate the following values while reviewing the settings:
- `FoundationaLLM:Chat:Entra:CallbackPath`: Should be `/signin-oidc`.
- `FoundationaLLM:Chat:Entra:Instance`: Should be `https://login.microsoftonline.com/`.
- `FoundationaLLM:CoreAPI:Entra:CallbackPath`: Should be `/signin-oidc`.
- `FoundationaLLM:CoreAPI:Entra:Instance`: Should be `https://login.microsoftonline.com/`.
- `FoundationaLLM:CoreAPI:Entra:Scopes`: Should be `Data.Read`.

9. Select **Apply** to save the changes.

<!-- ### Update Key Vault secrets
Key Vault stores the secrets for the client and API applications. You need to update the secrets with the values that you recorded earlier.
1. Return to the [Azure portal](https://portal.azure.com/).
2. Navigate to the resource group that was created as part of the deployment.
3. Select the **Key Vault** resource and select **Secrets**. If you cannot see the secrets, add your user account as a **Key Vault Secrets Officer** through Access Control (IAM). You need this role in order to access the secrets and update them as a required part of the authentication setup.
4. Open the `foundationallm-chat-entra-clientsecret` secret, then select **+ New Version**.
5. Within the **Secret value** field, enter the **Client secret** of the client application that you [created earlier](#client-secret-for-the-client-application), then select **Create**.
6. Open the `foundationallm-coreapi-entra-clientsecret` secret, then select **+ New Version**.
7. Within the **Secret value** field, enter the **Client secret** of the API application that you [created earlier](#client-secret-for-the-api-application), then select **Create**. -->

## Next steps

Now that Entra authentication is fully configured, restart the Core API and chat applications to apply the changes. Navigate to your chat application or refresh the page if it is already open. It should automatically prompt you to sign in with your Microsoft Entra ID account.

### Restart Core API and Chat UI applications in an ACA Deployment

To restart the Core API and Chat applications in an Azure Container Apps (ACA) deployment, you will need to navigate to the Core API and Chat applications and restart their container revisions, as indicated in the following Azure Portal screenshot:

![Restarting the Core API Azure Container App.](media/restart-coreapi-aca.png "Restarting the Container App in Azure Portal.")

1. From the `Revisions` blade in the left navigation panel of the Core API or Chat UI container app detail page in Azure Portal, select the name of the running revision.
2. A dialog panel titled `Revision details` should appear on the right side of the browser with a `Restart` button at the top. Select the `Restart` button to restart the running container.

Restarting in this manner will need to be performed for both the Core API container app and the Chat UI container app.

### Restart Core API and Chat UI applications in an AKS Deployment

To restart the Core API and Chat applications in an Azure Kubernetes Service (AKS) deployment, you will need to navigate to the AKS detail page in Azure Portal and perform the following:

1. Select the `Workloads` blade from the left navigation panel.
2. Select the `Pods` tab from the `Workloads` detail page.
3. Select the Core API and Chat UI pods from the list (it helps if you select `default` in the `Filter by namespace` dropdown first).
4. Select the `Delete` button to terminate the currently running pods. New pods will be instantiated to take their place.

![Restarting containers in AKS.](media/restart-containers-aks.png "Restarting the Core API and Chat UI services in an AKS deployment.")
![The client application's configured permissions are displayed.](media/entra-app-configured-permissions.png)
13 changes: 10 additions & 3 deletions docs/deployment/authentication-authorization/index.md
View file
Original file line number Diff line number Diff line change
Expand Up @@ -7,7 +7,14 @@ FoundationaLLM uses the [Microsoft Entra ID](https://learn.microsoft.com/entra/f
> [!IMPORTANT]
> The following steps are required to set up authentication and authorization for the solution. You will need to create app registrations in the Entra ID tenant in the Azure portal. There are currently **five** app registrations required for the solution as listed below. After you complete the 5 app registrations, you will need to finish the deployment process of the solution and revisit these app registrations to fill in some missing values that are generated during the deployment itself.
### Steps to perform before the deployment
- [Pre-requisites](pre-requisites.md)
- [Core API and user portal authentication setup - Microsoft Entra ID](core-authentication-setup-entra.md)
- [Management API and portal authentication setup - Microsoft Entra ID](management-authentication-setup-entra.md)
- [Authorization setup - Microsoft Entra ID](authorization-setup-entra.md)
- [Core API and user portal authentication pre-deployment - Microsoft Entra ID](core-authentication-setup-entra.md)
- [Management API and portal authentication pre-deployment - Microsoft Entra ID](management-authentication-setup-entra.md)
- [Authorization pre-deployment - Microsoft Entra ID](authorization-setup-entra.md)

### Steps to perform after the deployment
- [Core API and user portal authentication post-deployment - Microsoft Entra ID](post-core-deployment.md)
- [Management API and portal authentication post-deployment - Microsoft Entra ID](post-management-deployment.md)
- [Authorization post-deployment - Microsoft Entra ID](post-authorization-deployment.md)

66 changes: 1 addition & 65 deletions ...eployment/authentication-authorization/management-authentication-setup-entra.md
View file
Original file line number Diff line number Diff line change
Expand Up @@ -176,68 +176,4 @@ If you wish to [configure authentication in Postman](../../development/directly-

The client application's configured permissions should now look like the following:

![The client application's configured permissions are displayed.](media/entra-management-app-configured-permissions.png)

### Update App Configuration settings

1. Sign in to the [Azure portal](https://portal.azure.com/) as at least a Contributor.
2. Navigate to the resource group that was created as part of the deployment.
3. Select the **App Configuration** resource and select **Configuration explorer** to view the values.
4. Enter `entra` in the search box to filter the results.
5. Check the box next to **Key** in the header to select all items.
6. Select **Edit** to open a JSON editor for the selected items.

![The configuration settings are filtered by entra and all items are selected.](media/app-configuration-entra-settings.png "App Configuration settings for Microsoft Entra ID authentication")

7. Replace the values for the following settings with the values that you recorded earlier:
- `FoundationaLLM:Management:Entra:ClientId`: The **Application (client) ID** of the client application that you [created earlier](#register-the-client-application-in-the-microsoft-entra-admin-center).
- `FoundationaLLM:Management:Entra:Scopes`: The fully-qualified scopes path for the API application that you [created earlier](#expose-an-api-for-the-api-application). It should look like `api://FoundationaLLM.Management-API/Data.Manage`.
- `FoundationaLLM:Management:Entra:TenantId`: The **Directory (tenant) ID** of the client application that you [created earlier](#register-the-client-application-in-the-microsoft-entra-admin-center).
- `FoundationaLLM:ManagementAPI:Entra:ClientId`: The **Application (client) ID** of the API application that you [created earlier](#register-the-api-application-in-the-microsoft-entra-admin-center).
- `FoundationaLLM:ManagementAPI:Entra:TenantId`: The **Directory (tenant) ID** of the API application that you [created earlier](#register-the-api-application-in-the-microsoft-entra-admin-center).

8. Validate the following values while reviewing the settings:
- `FoundationaLLM:Management:Entra:CallbackPath`: Should be `/signin-oidc`.
- `FoundationaLLM:Management:Entra:Instance`: Should be `https://login.microsoftonline.com/`.
- `FoundationaLLM:ManagementAPI:Entra:Instance`: Should be `https://login.microsoftonline.com/`.
- `FoundationaLLM:ManagementAPI:Entra:Scopes`: Should be `Data.Manage`.

9. Select **Apply** to save the changes.

<!-- ### Update Key Vault secrets
Key Vault stores the secrets for the client and API applications. You need to update the secrets with the values that you recorded earlier.
1. Return to the [Azure portal](https://portal.azure.com/).
2. Navigate to the resource group that was created as part of the deployment.
3. Select the **Key Vault** resource and select **Secrets**. If you cannot see the secrets, add your user account as a **Key Vault Secrets Officer** through Access Control (IAM). You need this role in order to access the secrets and update them as a required part of the authentication setup.
4. Open the `foundationallm-management-entra-clientsecret` secret, then select **+ New Version**.
5. Within the **Secret value** field, enter the **Client secret** of the client application that you [created earlier](#client-secret-for-the-client-application), then select **Create**.
6. Open the `foundationallm-managementapi-entra-clientsecret` secret, then select **+ New Version**.
7. Within the **Secret value** field, enter the **Client secret** of the API application that you [created earlier](#client-secret-for-the-api-application), then select **Create**. -->

## Next steps

Now that Entra authentication is fully configured, restart the Management API and management portal applications to apply the changes. Navigate to your management portal application or refresh the page if it is already open. It should automatically prompt you to sign in with your Microsoft Entra ID account.

<!-- ### Restart Management API and Management Portal UI applications in an ACA Deployment
To restart the Management API and management portal applications in an Azure Container Apps (ACA) deployment, you will need to navigate to the Management API and management portal applications and restart their container revisions, as indicated in the following Azure Portal screenshot:
![Restarting the Core API Azure Container App.](media/restart-coreapi-aca.png "Restarting the Container App in Azure Portal.")
1. From the `Revisions` blade in the left navigation panel of the Core API or Chat UI container app detail page in Azure Portal, select the name of the running revision.
2. A dialog panel titled `Revision details` should appear on the right side of the browser with a `Restart` button at the top. Select the `Restart` button to restart the running container.
Restarting in this manner will need to be performed for both the Management API container app and the management portal container app.
### Restart Management API and Management Portal UI applications in an AKS Deployment
To restart the Management API and management portal applications in an Azure Kubernetes Service (AKS) deployment, you will need to navigate to the AKS detail page in Azure Portal and perform the following:
1. Select the `Workloads` blade from the left navigation panel.
2. Select the `Pods` tab from the `Workloads` detail page.
3. Select the Core API and Chat UI pods from the list (it helps if you select `default` in the `Filter by namespace` dropdown first).
4. Select the `Delete` button to terminate the currently running pods. New pods will be instantiated to take their place.
![Restarting containers in AKS.](media/restart-containers-aks.png "Restarting the Core API and Chat UI services in an AKS deployment.") -->
![The client application's configured permissions are displayed.](media/entra-management-app-configured-permissions.png)
17 changes: 17 additions & 0 deletions docs/deployment/authentication-authorization/post-authorization-deployment.md
View file
Original file line number Diff line number Diff line change
@@ -0,0 +1,17 @@
## Post Deployment
Follow the instruction below to complete the setup of Microsoft Entra ID authentication for the Authorization API application after the deployment is complete.

### Update App Configuration settings

1. Sign in to the [Azure portal](https://portal.azure.com/) as at least a Contributor.
2. Navigate to the resource group that was created as part of the deployment.
3. Select the **App Configuration** resource and select **Configuration explorer** to view the values.
4. Enter `authorization` in the search box to filter the results.
5. Check the box next to **Key** in the header to select all items.
6. Find the key for `FoundationaLLM:APIs:AuthorizationAPI:APIScope` and click on edit.
7. Replace the value with the value from the scope we created earlier, as `api://FoundationaLLM-Authorization`
8. Select **Apply** to save the changes.

## Next steps

Now that Entra authorization is fully configured, navigate to your Entra ID management console and make sure you completed all app registrations for all the other apps mentioned in the deployment documentation.
Loading

0 comments on commit 0b95206

Please sign in to comment.