diff --git a/docs/ConfigureAppAuthentication.md b/docs/ConfigureAppAuthentication.md index 91d60502..f9fb1eb4 100644 --- a/docs/ConfigureAppAuthentication.md +++ b/docs/ConfigureAppAuthentication.md @@ -4,7 +4,7 @@ This document provides step-by-step instructions to configure Azure App Registra ## Prerequisites -- Access to **Azure Active Directory (Azure AD)** +- Access to **Microsoft Entra ID** - Necessary permissions to create and manage **App Registrations** ## Step 1: Add Authentication Provider @@ -19,7 +19,12 @@ We will add Microsoft Entra ID as an authentication provider to API and Web Appl - Select **Microsoft** and set **Client secret expiration**, then click **Add** button. ![add_auth_provider_web_2](./Images/add_auth_provider_web_2.png) -2. Add Authentication Provider in API Service +> **Note:** If you encounter the following error message indicating that your organization's policy prohibits the automatic use of secrets, please refer to our [Manual App Registration Configuration](./ManualAppRegistrationConfiguration.md) for detailed manual setup instructions. +> ![add_auth_provider_web_3](./Images/add_auth_provider_web_3.png) + + + +1. Add Authentication Provider in API Service - Go to deployed Container App and select `ca-cps--api` and click **Add Identity Provider** button in Authentication. ![add_auth_provider_api_1](./Images/add_auth_provider_api_1.png) @@ -58,6 +63,10 @@ We will add Microsoft Entra ID as an authentication provider to API and Web Appl - Grant admin consent to permissions. ![configure_app_registration_web_8](./Images/configure_app_registration_web_8.png) + > ⚠️ **Granting Admin Consent:** If you don't have permission or aren't able to grant admin consent for the API permissions, please follow one of the steps below:

_Option 1 - Reach out to your Tenant Administrator:_ Contact your administrator to let them know your Application Registration ID and what permissions you woud like to have them consent and approve.

_Option 2 - Internal Microsoft Employees Only:_ Please refer to these detailed instructions on the admin consent granting process: [https://aka.ms/AzAdminConsentWiki](https://aka.ms/AzAdminConsentWiki) + + + 3. Grab Scope Name for Impersonation - Select **Expose an API** in the left menu. Copy the Scope name, then paste it in some temporary place. diff --git a/docs/Images/add_auth_provider_web_3.png b/docs/Images/add_auth_provider_web_3.png new file mode 100644 index 00000000..2da9f441 Binary files /dev/null and b/docs/Images/add_auth_provider_web_3.png differ diff --git a/docs/Images/configure_app_registration_api_2.png b/docs/Images/configure_app_registration_api_2.png index 87d5b04c..b8e3b970 100644 Binary files a/docs/Images/configure_app_registration_api_2.png and b/docs/Images/configure_app_registration_api_2.png differ diff --git a/docs/Images/manual_register_app_api_1.png b/docs/Images/manual_register_app_api_1.png new file mode 100644 index 00000000..4210a072 Binary files /dev/null and b/docs/Images/manual_register_app_api_1.png differ diff --git a/docs/Images/manual_register_app_api_2.png b/docs/Images/manual_register_app_api_2.png new file mode 100644 index 00000000..57de6131 Binary files /dev/null and b/docs/Images/manual_register_app_api_2.png differ diff --git a/docs/Images/manual_register_app_api_3.png b/docs/Images/manual_register_app_api_3.png new file mode 100644 index 00000000..3db00cc3 Binary files /dev/null and b/docs/Images/manual_register_app_api_3.png differ diff --git a/docs/Images/manual_register_app_api_5.png b/docs/Images/manual_register_app_api_5.png new file mode 100644 index 00000000..d54ed48c Binary files /dev/null and b/docs/Images/manual_register_app_api_5.png differ diff --git a/docs/Images/manual_register_app_web_1.png b/docs/Images/manual_register_app_web_1.png new file mode 100644 index 00000000..8e5ea96f Binary files /dev/null and b/docs/Images/manual_register_app_web_1.png differ diff --git a/docs/Images/manual_register_app_web_2.png b/docs/Images/manual_register_app_web_2.png new file mode 100644 index 00000000..de807107 Binary files /dev/null and b/docs/Images/manual_register_app_web_2.png differ diff --git a/docs/Images/manual_register_app_web_3.png b/docs/Images/manual_register_app_web_3.png new file mode 100644 index 00000000..bdc07a62 Binary files /dev/null and b/docs/Images/manual_register_app_web_3.png differ diff --git a/docs/Images/manual_register_app_web_4.png b/docs/Images/manual_register_app_web_4.png new file mode 100644 index 00000000..2ee3ee19 Binary files /dev/null and b/docs/Images/manual_register_app_web_4.png differ diff --git a/docs/Images/manual_register_app_web_5.png b/docs/Images/manual_register_app_web_5.png new file mode 100644 index 00000000..d54ed48c Binary files /dev/null and b/docs/Images/manual_register_app_web_5.png differ diff --git a/docs/ManualAppRegistrationConfiguration.md b/docs/ManualAppRegistrationConfiguration.md new file mode 100644 index 00000000..db3d3a21 --- /dev/null +++ b/docs/ManualAppRegistrationConfiguration.md @@ -0,0 +1,135 @@ +# Manual App Registration Configuration +This guide provides detailed steps to manually register both front-end and backend applications in Azure if automated registration is not an option due to security in place in your tenant and subscription. + +## Prerequisites + +- Access to **Microsoft Entra ID** +- Necessary permissions to create and manage **App Registrations** in your Azure tenant + +## Step 1: Register the Web Application +### 1. Create App Registration +- Go to **Azure Portal** > **Microsoft Entra ID** > **Manage** > **App registrations** +- Click **+ New registration** +- Name the app (e.g., `cps-app-web`) +- Under **Redirect URI**, choose **Web** and enter: + + ``` + https://azurecontainerapps.io/auth/login/aad/callback + ``` + + To find your Web App URL: + - Navigate to your newly deployed resource group in the Azure Portal. + - Locate the container app ending in `-web`. + - Copy the Ingress URL from the Overview . + +- Click **Register** + ![manual_register_app_web_1](./Images/manual_register_app_web_1.png) + + +### 2. Expose an API + +- Navigate to **Expose an API** +- Click **+ Add a scope** + - It will auto-fill the Application ID URI (use default or adjust as needed) + - Click **Save and continue** + - Add scope: + - Scope name: `user_impersonation` + - Admin consent display name: `Access Web App` + - Admin consent description: `Allows the app to access the web application as the signed-in user` +- Click **Add scope** + ![manual_register_app_web_2](./Images/manual_register_app_web_2.png) + + +### 3. Configure Certificates and Secrets + +- Go to **Certificates & secrets** +- Click **+ New client secret** +- Description: Provide a meaningful name to identify the secret +- Expires: Select from the options or define a custom range +- Start (Optional for custom range): Set the starting date of the secret's validity +- End (Optional for custom range): Set the ending date of the secret's validity +- Click **Add** and remember to copy and store the secret value securely as it will not be shown again +![manual_register_app_web_3](./Images/manual_register_app_web_3.png) + +### 4. Set Up Authentication in Web Container App + +- Go to your Web Container App +- Go to **Authentication** +- Click **Add Identity Provider** +- Choose **Microsoft** +- Input: +- **Client ID**: The Application (client) ID from the app registration +- **Client Secret**: The secret value you generated in Certificates & Secrets from the app registration +- **Issuer URL**: `https://sts.windows.net//v2.0` +- **Allowed Token Audiences**: Usually the Application ID URI or Client ID +- Click **Add** + +![manual_register_app_web_4](./Images/manual_register_app_web_4.png) + + + + +## Step 2: Register API Application + +### 1. Create App Registration +- Go to **Azure Portal** > **Microsoft Entra ID** > **Manage** > **App registrations** +- Click **+ New registration** +- Name the app (e.g., `cps-app-api`) +- Under **Redirect URI**, choose **Web** and enter: + + ``` + https://azurecontainerapps.io/auth/login/aad/callback + ``` + + To find your Web App URL: + - Navigate to your newly deployed resource group in the Azure Portal. + - Locate the container app ending in `-api`. + - Copy the Ingress URL from the Overview . + +- Click **Register** + ![manual_register_app_api_1](./Images/manual_register_app_api_1.png) + + ### 2. Expose an API + +- Go to **Expose an API** +- Click **+ Add a scope** +- Use default Application ID URI +- Add: + - Scope name: `user_impersonation` + - Admin consent details +- Click **Add scope** +![manual_register_app_api_2](./Images/manual_register_app_api_2.png) + +### 3. Configure Certificates and Secrets + +- Go to **Certificates & secrets** +- Click **+ New client secret** +- Description: Provide a meaningful name to identify the secret +- Expires: Select from the options or define a custom range +- Start (Optional for custom range): Set the starting date of the secret's validity +- End (Optional for custom range): Set the ending date of the secret's validity +- Click **Add** and remember to copy and store the secret value securely as it will not be shown again +![manual_register_app_api_3](./Images/manual_register_app_api_3.png) + +### 4. Set Up Authentication in API Container App + +- Navigate to your API Container App +- Go to **Authentication** +- Click **Add Identity Provider** + - Choose **Microsoft** + - Fill in: + - **Client ID**: The Application (client) ID from the app registration + - **Client Secret**: The secret value you generated in Certificates & Secrets + - **Issuer URL**: `https://sts.windows.net//v2.0` + - **Allowed Token Audiences**: Usually the Application ID URI or Client ID +- Click **Add** +![manual_register_app_api_4](./Images/manual_register_app_api_4.png) +![manual_register_app_api_5](./Images/manual_register_app_api_5.png) + +--- + +## Conclusion + +You have now manually configured Azure App Registrations. + +For further configuration and steps, proceed to Step 2 in [Configure App Authentication](./ConfigureAppAuthentication.md#step-2-configure-application-registration---web-application). \ No newline at end of file