Skip to content

Latest commit

 

History

History
154 lines (103 loc) · 7.3 KB

self-host-api-center-portal.md

File metadata and controls

154 lines (103 loc) · 7.3 KB
titledescriptionauthorms.servicems.topicms.datems.authorms.custom
Self-host the API Center portal
How to self-host the API Center portal, a customer-managed website that enables discovery of the API inventory in your Azure API center.
dlepow
azure-api-center
how-to
03/04/2025
danlep

Self-host your API Center portal

This article shows how to self-host the API Center portal, a website that developers and other stakeholders in your organization can use to discover the APIs in your API center. Deploy a reference implementation of the portal from the API Center portal starter repository.

:::image type="content" source="media/self-host-api-center-portal/api-center-portal-signed-in.png" alt-text="Screenshot of the API Center portal after user sign-in.":::

Tip

New! You can now set up an Azure-managed version of the API Center portal. For more information, see Set up the API Center portal.

About self-hosting the portal

You can build and deploy a reference implementation of the portal using code in the API Center portal starter repository. The portal uses the Azure API Center data plane API to retrieve data from your API center.

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.

Note

When you self-host the API Center portal, you become its maintainer and you're responsible for its upgrades. Azure support is limited.

[!INCLUDE api-center-portal-prerequisites]

  • To build and deploy the portal, you need a GitHub account and the following tools installed on your local machine:

Create Microsoft Entra app registration

[!INCLUDE api-center-portal-app-registration]

Note

When you're self-hosting the portal and want to test it locally before deploying to Azure, set the redirect URI in the app registration to https://localhost:5173.

Configure local environment

Follow these steps to build and test the API Center portal locally.

  1. Clone the API Center portal starter repository to your local machine.

    git clone https://github.com/Azure/APICenter-Portal-Starter.git

  2. Change to the APICenter-Portal-Starter directory.

    cd APICenter-Portal-Starter

  3. Check out the main branch.

    git checkout main

  4. To configure the service, copy or rename the public/config.example file to public/config.json.

  5. Then edit the public/config.json file to point to your service. Update the values in the file as follows:

    1. Replace <service name> and <location> with the name of your API center and the location where it's deployed
    2. 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.
    3. Update the value of title to a name that you want to appear in the top bar of the portal.
    { "dataApiHostName": "<service name>.data.<location>.azure-apicenter.ms/workspaces/default", "title": "API portal", "authentication": { "clientId": "<client ID>", "tenantId": "<tenant ID>", "scopes": ["https://azure-apicenter.net/user_impersonation"], "authority": "https://login.microsoftonline.com/" } }

  6. Install required packages.

    npm install

  7. Start the development server. The following command starts the portal in development mode running locally:

    npm start

    Browse to the portal at https://localhost:5173.

Deploy to Azure

For steps to deploy the portal to Azure Static Web Apps, see the API Center portal starter repository.

Enable sign-in to portal by Microsoft Entra users and groups

[!INCLUDE api-center-portal-user-sign-in]

Troubleshooting

Error: "You are not authorized to access this portal"

Under certain conditions, a user might encounter the following error message after signing into the API Center portal with a configured user account:

You are not authorized to access this portal. Please contact your portal administrator for assistance. `

First, confirm that the user is assigned the Azure API Center Data Reader role in your API center.

If the user is assigned the role, there might be a problem with the registration of the Microsoft.ApiCenter resource provider in your subscription, and you might need to re-register the resource provider. To do this, run the following command in the Azure CLI:

az provider register --namespace Microsoft.ApiCenter

Unable to sign in to portal

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 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

If you're unable to request API permissions to Azure API Center in your Microsoft Entra app registration for the API Center portal, check that you are searching for Azure API Center (or application ID c3ca1a77-7a87-4dba-b8f8-eea115ae4573).

If the app isn't present, there might be a problem with the registration of the Microsoft.ApiCenter resource provider in your subscription. You might need to re-register the resource provider. To do this, run the following command in the Azure CLI:

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 repository.

Related content

close