Merge pull request #273123 from dlepow/gaport

[APIM][release-ga-api-center] Self-host APIC portal

Author: Stacyrch140

articles/api-center/TOC.yml

@@ -44,7 +44,7 @@
         href: enable-api-analysis-linting.md
 - name: API discovery and consumption
   items:
-      - name: Enable Azure API Center portal
+      - name: Self-host Azure API Center portal
         href: enable-api-center-portal.md
       - name: Discover APIs with GitHub Copilot Chat
         href: use-vscode-extension-copilot.md

articles/api-center/enable-api-center-portal.md

@@ -1,31 +1,45 @@
 ---
-title: Enable API Center portal - Azure API Center
-description: Enable the API Center portal, an automatically generated website that enables discovery of your API inventory.
+title: Self-host the API Center portal
+description: How to self-host the API Center portal, a customer-managed website that enables discovery of the API inventory in your Azure API center.
 author: dlepow
 ms.service: api-center
 ms.topic: how-to
-ms.date: 03/18/2024
+ms.date: 04/29/2024
 ms.author: danlep 
 ms.custom: 
 # Customer intent: As an API program manager, I want to enable a portal for developers and other API stakeholders in my organization to discover the APIs in my organization's API center.
 ---
 
-# Enable your API Center portal
+# Self-host your API Center portal
 
-This article shows how to enable your *API Center portal*, an automatically generated website that developers and other stakeholders in your organization can use to discover the APIs in your [API center](overview.md). The portal is hosted by Azure at a unique URL and restricts user access based on Azure role-based access control.
+This article introduces the *API Center portal*, a website that developers and other stakeholders in your organization can use to discover the APIs in your [API center](overview.md). Deploy a reference implementation of the portal from the [API Center portal starter](https://github.com/Azure/APICenter-Portal-Starter.git) repository.
 
-> [!IMPORTANT]
-> The Azure-hosted API Center portal is experimental and will be removed from API Center in an upcoming release. You will have an option to self-host an API Center portal for API discovery in an upcoming release.
+:::image type="content" source="media/enable-api-center-portal/api-center-portal-signed-in.png" alt-text="Screenshot of the API Center portal after user sign-in.":::
+
+
+## About the API Center portal
 
+The API Center portal is a website that you can build and host to display the API inventory in your API center. The portal enables developers and other stakeholders in your organization to discover APIs and view API details. 
 
+You can build and deploy a reference implementation of the portal using code in the [API Center portal starter](https://github.com/Azure/APICenter-Portal-Starter.git) repository. The portal uses the [Azure API Center data plane API](/rest/api/dataplane/apicenter/operation-groups) to retrieve data from your API center. User access to API information is based on Azure role-based access control.
 
+The API Center portal reference implementation provides:
+
+* A framework for publishing and maintaining a customer-managed API portal using GitHub Actions
+* A portal platform that customers can modify or extend to meet their needs
+* Flexibility to host on different infrastructures, including deployment to services such as Azure Static Web Apps.  
 
 ## Prerequisites
 
 * An API center in your Azure subscription. If you haven't created one already, see [Quickstart: Create your API center](set-up-api-center.md).
 
 * Permissions to create an app registration in a Microsoft Entra tenant associated with your Azure subscription, and permissions to grant access to data in your API center. 
 
+* To build and deploy the portal, you need a GitHub account and the following tools installed on your local machine:
+
+    * [Node.js and npm](https://docs.npmjs.com/downloading-and-installing-node-js-and-npm)
+    * [Vite package](https://www.npmjs.com/package/vite)
+
 ## Create Microsoft Entra app registration
 
 First configure an app registration in your Microsoft Entra ID tenant. The app registration enables the API Center portal to access data from your API center on behalf of a signed-in user.
@@ -36,14 +50,12 @@ First configure an app registration in your Microsoft Entra ID tenant. The app r
 
     * Set **Name** to a meaningful name such as *api-center-portal*
     * Under **Supported account types**, select **Accounts in this organizational directory (Single tenant)**. 
-    * In **Redirect URI**, select **Single-page application (SPA)** and enter the following URI, substituting your API center name and region where indicated:
-
-        `https://<api-center-name>.portal.<region>.azure-apicenter.ms`
-
-        Example: `https://contoso.portal.westeurope.azure-apicenter.ms`
+    * In **Redirect URI**, select **Single-page application (SPA)** and set the URI.
 
+        * For local testing, set the URI to `http://localhost:5173`. 
+        * For production, set the URI to the URI of your API Center portal deployment.
     * Select **Register**.
-1. On the **Overview** page, copy the **Application (client) ID**. You use this value when you configure the identity provider for the portal in your API center.
+1. On the **Overview** page, copy the **Application (client) ID** and the **Directory (tenant) ID**. You set these values when you build the portal.
 
 1. On the **API permissions** page, select **+ Add a permission**. 
     1. On the **Request API permissions** page, select the **APIs my organization uses** tab. Search for and select **Azure API Center**. You can also search for and select application ID `c3ca1a77-7a87-4dba-b8f8-eea115ae4573`. 
@@ -54,41 +66,65 @@ First configure an app registration in your Microsoft Entra ID tenant. The app r
 
     :::image type="content" source="media/enable-api-center-portal/configure-app-permissions.png" alt-text="Screenshot of required permissions in Microsoft Entra ID app registration in the portal." lightbox="media/enable-api-center-portal/configure-app-permissions.png":::
 
+## Configure local environment
 
-## Configure Microsoft Entra ID provider for API Center portal
+Follow these steps to build and test the API Center portal locally.
 
-In your API center, configure the Microsoft Entra ID identity provider for the API Center portal.
+1. Clone the [API Center portal starter](https://github.com/Azure/APICenter-Portal-Starter.git) repository to your local machine.
 
-1. In the [Azure portal](https://portal.azure.com), navigate to your API center.
-1. In the left menu, under **API Center portal**, select **Portal settings**.
-1. Select **Identity provider** > **Start set up**.
-1. On the **Set up user sign-in with Microsoft Entra ID** page, in **Client ID**, enter the **Application (client) ID** of the app registration that you created in the previous section.
+    ```bash
+    git clone https://github.com/Azure/APICenter-Portal-Starter.git
+    ```
+1. Change to the `APICenter-Portal-Starter` directory.
 
-    :::image type="content" source="media/enable-api-center-portal/set-up-sign-in-portal.png" alt-text="Screenshot of the Microsoft Entra ID provider settings in the API Center portal." lightbox="media/enable-api-center-portal/set-up-sign-in-portal.png":::
+    ```bash
+    cd APICenter-Portal-Starter
+    ```
+1. Check out the main branch.
 
-1. Select **Save + publish**. The Microsoft Entra ID provider appears on the **Identity provider** page.
+    ```bash
+    git checkout main
+    ```  
+1. To configure the service, edit the `public/config.json` file to point to your service. Update the values in the file as follows:
+    * Replace `<service name>` and `<region>` with the name of your API center and the region where it's deployed
+    * Replace `<client ID>` and `<tenant ID>` with the **Application (client) ID** and **Directory (tenant) ID** of the app registration you created in the previous section.
+    * Update the value of `title` to a name that you want to appear on the portal.
 
-1. To view the API Center portal, on the **Portal settings** page, select **View API Center portal**.
+    ```json
+    {
+      "dataApiHostName": "<service name>.data.<region>.azure-apicenter.ms",
+      "title": "API portal",
+      "authentication": {
+          "clientId": "<client ID>",
+          "tenantId": "<tenant ID>",
+          "scopes": ["https://azure-apicenter.net/user_impersonation"],
+          "authority": "https://login.microsoftonline.com/"
+      }
+    }
+    ```
 
-The portal is published at the following URL that you can share with developers in your organization: `https://<api-center-name>.<region>.azure-apicenter.ms`.
+1. Start the development server to test the portal locally.
 
-:::image type="content" source="media/enable-api-center-portal/api-center-portal-home.png" alt-text="Screenshot of the API Center portal home page.":::
+    ```bash
+    npm start
+    ```
 
-## Customize portal name
+    Browse to the portal at `https://localhost:5173`.
 
-By default, the name that appears on the upper left of the API Center portal is the name of your API center. You can customize this name.
+1. When you're ready to build the portal for production, run the following command.
 
-1. In the Azure portal, go to the **Portal settings** > **Site profile** page.
-1. Enter a new name in **Add a website name**.
-1. Select **Save + publish**.
+    ```bash
+    npm run build
+    ```
 
-    :::image type="content" source="media/enable-api-center-portal/add-website-name.png" alt-text="Screenshot of adding a custom website name in the Azure portal.":::
+## Deploy to Azure
+
+For steps to deploy the portal to Azure Static Web Apps, see the [API Center portal starter](https://github.com/Azure/APICenter-Portal-Starter.git) repository.
 
-    The new name appears after you refresh the API Center portal.
 
 ## Enable sign-in to portal by Microsoft Entra users and groups 
 
-While the portal URL is publicly accessible, users must sign in to see the APIs in your API center. To enable sign-in, assign the **Azure API Center Data Reader** role to users or groups in your organization, scoped to your API center.
+Users must sign in to see the APIs in your API center. To enable sign-in, assign the **Azure API Center Data Reader** role to users or groups in your organization, scoped to your API center.
 
 > [!IMPORTANT]
 > By default, you and other administrators of the API center don't have access to APIs in the API Center portal. Be sure to assign the **Azure API Center Data Reader** role to yourself and other administrators.  
@@ -111,8 +147,6 @@ After you configure access to the portal, configured users can sign in to the po
 > [!NOTE]
 > The first user to sign in to the portal is prompted to consent to the permissions requested by the API Center portal app registration. Thereafter, other configured users aren't prompted to consent.
 
-:::image type="content" source="media/enable-api-center-portal/api-center-portal-signed-in.png" alt-text="Screenshot of the API Center portal after user sign-in.":::
-
 ## Troubleshooting
 
 ### Error: "You are not authorized to access this portal"
@@ -134,10 +168,7 @@ az provider register --namespace Microsoft.ApiCenter
 
 If users who have been assigned the **Azure API Center Data Reader** role can't complete the sign-in flow after selecting **Sign in** in the API Center portal, there might be a problem with the configuration of the Microsoft Entra ID identity provider.
 
-In the Microsoft Entra app registration, review and, if needed, update the **Redirect URI** settings:
-
-* Platform: **Single-page application (SPA)**
-* URI: `https://<api-center-name>.portal.<region>.azure-apicenter.ms`. This value must be the URI shown for the Microsoft Entra ID provider for your API Center portal.
+In the Microsoft Entra app registration, review and, if needed, update the **Redirect URI** settings to ensure that the URI matches the URI of the API Center portal deployment.
 
 ### Unable to select Azure API Center permissions in Microsoft Entra app registration
 
@@ -151,10 +182,12 @@ az provider register --namespace Microsoft.ApiCenter
 
 After re-registering the resource provider, try again to request API permissions.
 
+## Support policy
+
+Provide feedback, request features, and get support for the API Center portal reference implementation in the [API Center portal starter](https://github.com/Azure/APICenter-Portal-Starter.git) repository.
 
 ## Related content
 
-* [Azure CLI reference for API Center](/cli/azure/apic) 
 * [What is Azure role-based access control (RBAC)?](../role-based-access-control/overview.md)
 * [Best practices for Azure RBAC](../role-based-access-control/best-practices.md)
 * [Register a resource provider](../azure-resource-manager/management/resource-providers-and-types.md#register-resource-provider)

articles/api-center/index.yml

@@ -67,7 +67,7 @@ landingContent:
     linkLists:
       - linkListType: how-to-guide
         links:
-          - text: Enable Azure API Center portal
+          - text: Self-host Azure API Center portal
             url: enable-api-center-portal.md
           - text: Discover APIs with GitHub Copilot Chat
             url: use-vscode-extension-copilot.md