Skip to content

Commit

Permalink
Merge pull request #1998 from solliancenet/lino-docs-0.8.4
Browse files Browse the repository at this point in the history 
Documentation changes for 0.8.4 - Deployment and Branding
  • Loading branch information
@ciprianjichici
ciprianjichici authored Nov 25, 2024
2 parents 42f021c + 3cfb4f7 commit 8188b1c
Show file tree
Hide file tree
Showing 11 changed files with 221 additions and 142 deletions.
15 changes: 6 additions & 9 deletions docs/deployment/authentication-authorization/index.md
View file
Original file line number Diff line number Diff line change
Expand Up @@ -4,24 +4,21 @@ FoundationaLLM uses the [Microsoft Entra ID](https://learn.microsoft.com/entra/f

## Microsoft Entra ID

Starting `release 0.8.0` there are 2 options of completing the app registrations for the 5 apps required for FoundationaLLM. Option #1 is to run a script that will register all 5 applications for you. Option #2 is to manually register the 5 applications. The steps for both options are below.
Starting `release 0.8.0` there are 2 options of completing the app registrations for the 6 apps required for FoundationaLLM. Option #1 is to run a script that will register all 6 applications for you. Option #2 is to manually register the 6 applications. The steps for both options are below.

## Option #1 - Run the script to register all 5 applications
The script is available in the `\deploy\common\scripts\` folder. The script is called `Create-FllmEntraIdApps.ps1`. The script will register the 5 required applications in the Entra ID tenant that you are logged into.
## Option #1 - Run the script to register all 6 applications
The script is available in the `\deploy\common\scripts\` folder. The script is called `Create-FllmEntraIdApps.ps1`. The script will register the 6 required applications in the Entra ID tenant that you are logged into.

![Entra ID app registration script](../media/EntraIDAppsCreation.png)

After the completion of the script execution, you will see the 5 applications registered in the Entra ID tenant under `App registrations`
After the completion of the script execution, you will see the 6 applications registered in the Entra ID tenant under `App registrations`

![Entra ID registered apps in Portal](../media/EntraIDRegisteredAppsPortal.png)

> [!IMPORTANT]
> Make sure to copy and save the Application (Client) ID of all 5 applications in a text editor as you will need them in the next steps.
## Option 2 - Manually registering the 5 applications
## Option 2 - Manually registering the 6 applications

> [!IMPORTANT]
> The following steps are 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 manually if you choose not to run the automatic script for any reason. 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.
> The following steps are 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 manually if you choose not to run the automatic script for any reason. There are currently **five** app registrations required for the solution as listed below. After you complete the 6 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
- [Core API and user portal authentication pre-deployment - Microsoft Entra ID](core-authentication-setup-entra.md)
Expand Down
87 changes: 25 additions & 62 deletions docs/deployment/deployment-quick-start.md
View file
Original file line number Diff line number Diff line change
Expand Up @@ -51,21 +51,23 @@ If you are upgrading from a previous version, like `0.5.0`, please refer to the
```cmd
git clone https://github.com/solliancenet/foundationallm.git
cd foundationallm/deploy/quick-start
git checkout release/0.8.0
git checkout release/0.8.3
```
3. **For release 0.7.0+:** Run the following script to install the deployment utilities, including `AzCopy`, locally.
3. Run the following script to install the deployment utilities, including `AzCopy`, locally.
```cmd
./scripts/bootstrap.ps1
cd .\deploy\common\scripts
.\Get-AzCopy.ps1
```
4. Run the following commands to log into Azure CLI, Azure Developer CLI and AzCopy:
4. Run the following commands to log into Azure CLI, Azure Developer CLI and AzCopy (the instance you just installed above):
```azurecli
az login # Log into Azure CLI
azd auth login # Log into Azure Developer CLI
azcopy login # Log into AzCopy
cd .\deploy\quick-start
az login # Log into Azure CLI
azd auth login # Log into AZD
..\common\tools\azcopy\azcopy login # Log into AzCopy
```
5. Set up an `azd` environment targeting your Azure subscription and desired deployment region:
Expand All @@ -77,61 +79,24 @@ If you are upgrading from a previous version, like `0.5.0`, please refer to the
6. Run the following commands to set the appropriate application registration settings for OIDC authentication.
```text
azd env set ENTRA_AUTH_API_INSTANCE <Auth API Instance>
azd env set ENTRA_AUTH_API_CLIENT_ID <Auth API Client Id>
azd env set ENTRA_AUTH_API_SCOPES <Auth API Scope>
azd env set ENTRA_AUTH_API_TENANT_ID <Auth API Tenant ID>
azd env set ADMIN_GROUP_OBJECT_ID <Admin Group Object Id>
azd env set ENTRA_CHAT_UI_CLIENT_ID <Chat UI Client Id>
azd env set ENTRA_CHAT_UI_SCOPES <Chat UI Scope>
azd env set ENTRA_CHAT_UI_TENANT_ID <Chat UI Tenant ID>
azd env set ENTRA_CORE_API_CLIENT_ID <Core API Client Id>
azd env set ENTRA_CORE_API_SCOPES <Core API Scope>
azd env set ENTRA_CORE_API_TENANT_ID <Core API Tenant ID>
azd env set ENTRA_MANAGEMENT_API_CLIENT_ID <Management API Client Id>
azd env set ENTRA_MANAGEMENT_API_SCOPES <Management API Scope>
azd env set ENTRA_MANAGEMENT_API_TENANT_ID <Management API Tenant ID>
azd env set ENTRA_MANAGEMENT_UI_CLIENT_ID <Management UI Client Id>
azd env set ENTRA_MANAGEMENT_UI_SCOPES <Management UI Scope>
azd env set ENTRA_MANAGEMENT_UI_TENANT_ID <Management UI Tenant ID>
azd env set FOUNDATIONALLM_INSTANCE_ID <guid>
```cmd
cd .\deploy\quick-start
..\common\scripts\Set-AzdEnvEntra.ps1
```
> [!NOTE]
> You need to manually generate a GUID for `FOUNDATIONALLM_INSTANCE_ID`.
### In Bash:
```bash
uuidgen
```

### In PowerShell:
```powershell
[guid]::NewGuid().ToString()
```

> [!IMPORTANT]
> The ADMIN_GROUP_OBJECT_ID in the Entra ID Groups has to be of type `security` NOT `Microsoft 365` and you need to at least add yourself to the group and other members that need to be admins.
1. **Optional**: Bring Your Own Azure OpenAI Instance
## Optional: Bring Your Own Azure OpenAI Instance
If you have an existing Azure OpenAI instance, you can use it by setting the following environment variables:
```text
```azurecli
azd env set OPENAI_NAME <OpenAI Name>
azd env set OPENAI_RESOURCE_GROUP <OpenAI Resource Group>
azd env set OPENAI_SUBSCRIPTION_ID <OpenAI Subscription ID>
```
```
> [!IMPORTANT]
> Deploying with `Bring Your Own Azure OpenAI`, customers need to make sure that the relevant Managed Identities (LangChain API, Semantic Kernel API, and Gateway API) are assigned the `Open AI reader role` on the Azure OpenAI account object.
2. Deploy the solution
7. Deploy the solution

After setting the OIDC-specific settings in the AZD environment above, run `azd up` in the same folder location to provision the infrastructure, update the App Configuration entries, deploy the API and web app services, and import files into the storage account.

Expand All @@ -141,25 +106,23 @@ If you are upgrading from a previous version, like `0.5.0`, please refer to the
### Running script to allow MS Graph access through Role Permissions
After the deployment is complete, you will need to run the following script to allow MS Graph access through Role Permissions. [Role Permissions Script](https://github.com/solliancenet/foundationallm/blob/main/deploy/common/scripts/Assign-MSGraph-Roles.ps1)
This script will need to be executed twice for the principal IDs of the following:
- Core API Managed Identity
- Management API Managed Identity
These can be found in the Azure portal in the main resource group for the deployment.
After the deployment is complete, you will need to run the following script to allow MS Graph access through Role Permissions. (See below)
> [!IMPORTANT]
> The user running the script will need to have the appropriate permissions to assign roles to the managed identities. The user will need to be a `Global Administrator` or have the `Privileged Role Administrator` role in the Entra ID tenant.
The syntax for running the script from the `deploy\common\scripts` folder is:
The syntax for running the script from the `deploy\quick-start\common\scripts` folder is:
```pwsh
.\Assign-MSGraph-Roles.ps1 -principalId <GUID of the Core API Managed Identity Principal ID>
.\Assign-MSGraph-Roles.ps1 -principalId <GUID of the Management API Managed Identity Principal ID>
cd .\deploy\quick-start
..\common\scripts\Set-FllmGraphRoles.ps1 -resourceGroupName rg-<azd env name>
```
Finally, you will need to update the Authorization Callbacks in the App Registrations created in the Entra ID tenant by running the following script:

> [!IMPORTANT]
> For this release, you will need to restart the `CORE API` container and the `MANAGEMENT API` container in the resource group to allow the changes to take effect.
```pwsh
cd .\deploy\quick-start
..\common\scripts\Update-OAuthCallbackUris.ps1
```

# Teardown

Expand Down
Binary file modified docs/deployment/media/EntraIDRegisteredAppsPortal.png
View file
Loading
Sorry, something went wrong. Reload?
Sorry, we cannot display this file.
Sorry, this file is invalid so it cannot be displayed.
83 changes: 83 additions & 0 deletions docs/setup-guides/branding/branding-app-configuration.md
View file
Original file line number Diff line number Diff line change
@@ -0,0 +1,83 @@
# Branding Customization using the App Configurator

The `FoundationaLLM` application provides a way to customize the branding of the applications. The branding customization can be done by setting any of the **21 configuration values** available in the `App Configuration` resource in your Azure Resource Group. It can also be changed using the REST API calls pertaining to Branding.

### Accessing the App Configuration for branding customization

In your Azure Resource Group, navigate to the `App Configuration` resource and select the `Configuration Explorer` option under `Operations`. You will see a list of all configuration settings for `FoundationaLLM `, filter the list on the word `Branding` and you will be able to see the 21 relevant configuration settings pertaining to Branding.

![Branding App Configuration](./media/branding-1.jpg)

### The default User Interface of the `FoundationaLLM` is shown below

![Branding defaultn](./media/branding-2.jpg)

### The Login screen can also be customized as shown below

![Branding Login Page](./media/branding-3.jpg)

### The chat window can be customized as shown below

![Branding Chat Page](./media/branding-4.jpg)

## FoundationaLLM:Branding:AccentColor
Takes a hexadecimal or RGB color value to set the accent color of the chat application which is used for top header and the the token counter in the chat.
## FoundationaLLM:Branding:AccentTextColor
Takes a hexadecimal or RGB color value to set the accent text color of the chat application which is used for top header and the the token counter in the chat.
## FoundationaLLM:Branding:AgentIconUrl
A string value to set the Agent Icon Url which is displayed in the chat window.

> [!IMPORTANT]
> The AgentIconUrl can be an SVG or PNG image placed in the Public folder of the application's source code but will require rebuilding of the docker image to reflect the changes. The preferred ways of setting the LogoUrl is to set it to a relative accessible public URL to an SVG or PNG image or include the full Base64 encoded image in the configuration value directly.
## FoundationaLLM:Branding:BackgroundColor
Takes a hexadecimal or RGB color value to set the background color of the chat application.
## FoundationaLLM:Branding:CompanyName
Not is use. Reserved for future enhancements.

## FoundationaLLM:Branding:FavIconUrl
A string value to set the FavIcon Url which is displayed in the browser tab.
> [!IMPORTANT]
> The FavIconUrl can be an SVG or PNG image placed in the Public folder of the application's source code but will require rebuilding of the docker image to reflect the changes. The preferred ways of setting the FavIconUrl is to set it to a relative accessible public URL to an SVG or PNG image or include the full Base64 encoded image in the configuration value directly.
> [!IMPORTANT]
> Any changes to the `FoundationaLLM:Branding:FavIconUrl` will require a restart of the `CoreAPI` image to take effect.
## FoundationaLLM:Branding:FooterText
A string value to set the Footer Text value which is displayed at the bottom right of the screen.
## FoundationaLLM:Branding:KioskMode
This is a boolean flag to indicate if the application is running in kiosk mode, if true will remove the sessions panel on the left navigation panel.
Kiosk mode does not store user conversations and is meant to be used within a public kiosk setting
## FoundationaLLM:Branding:LogoText
A string value to set the Logo Text value which is displayed only if the `FoundationaLLM:Branding:LogoUrl` is not set.
## FoundationaLLM:Branding:LogoUrl
A string value to set the Logo Url which is displayed in top left header and also in the login screen.
> [!IMPORTANT]
> The LogoUrl can be an SVG or PNG image placed in the Public folder of the application's source code but will require rebuilding of the docker image to reflect the changes. The preferred ways of setting the LogoUrl is to set it to a relative accessible public URL to an SVG or PNG image or include the full Base64 encoded image in the configuration value directly.
## FoundationaLLM:Branding:PageTitle
A string value to set the Page Title value which is displayed in the browser tab.

![PageTitle](./media/branding-5.jpg)

> [!IMPORTANT]
> Any changes to the `FoundationaLLM:Branding:PageTitle` will require a restart of the `CoreAPI` image to take effect.
## FoundationaLLM:Branding:PrimaryButtonBackgroundColor
Takes a hexadecimal or RGB color value to set the Primary Button Background color of the chat application. It affects the `Send` button in the chat at the bottom right, the `Close` button the `View Prompt` screen and the `login` button in the login screen.
## FoundationaLLM:Branding:PrimaryButtonTextColor
Takes a hexadecimal or RGB color value to set the Primary Button Text color of the chat application. It affects the `Send` button in the chat at the bottom right, the `Close` button the `View Prompt` screen and the `login` button in the login screen.
## FoundationaLLM:Branding:PrimaryColor
Takes a hexadecimal or RGB color value to set the Primary color of the chat application. It affects the left navigation panel and the `User Message` panel in the chat.
## FoundationaLLM:Branding:PrimaryTextColor
Takes a hexadecimal or RGB color value to set the Primary Text color of the chat application. It affects the left navigation panel and the `User Message` panel in the chat.
## FoundationaLLM:Branding:SecondaryButtonBackgroundColor
Takes a hexadecimal or RGB color value to set the Secondary Button Background color of the chat application. It affects the `collapsable arrow` in the left navigation panel, the `Sign Out` bottom at the bottom and the `attachment` of files button in the chat window.
## FoundationaLLM:Branding:SecondaryButtonTextColor
Takes a hexadecimal or RGB color value to set the Secondary Button Text color of the chat application. It affects the `collapsable arrow` in the left navigation panel, the `Sign Out` bottom at the bottom and the `attachment` of files button in the chat window.
## FoundationaLLM:Branding:SecondaryColor
Takes a hexadecimal or RGB color value to set the Secondary color of the chat application. It affects the background color of the `session identifier` in the left navigations panel and the background of the entire `login screen`.
## FoundationaLLM:Branding:SecondaryTextColor
Takes a hexadecimal or RGB color value to set the Secondary Text color of the chat application. It affects the background color of the `session identifier` in the left navigations panel.
## FoundationaLLM:Branding:NoAgentsMessage
A string value to set the No Agents Message value which is displayed in the chat window when no agents are available. HTML allowed in this field.
## FoundationaLLM:Branding:DefaultAgentWelcomeMessage
A string value to set the Default Agent Welcome Message value which is displayed in the chat window when the agent is connected. HTML allowed in this field.
Loading

0 comments on commit 8188b1c

Please sign in to comment.