Configuring Azure API Management Integration

Last modified on September 27, 2023
Note: This information applies to SwaggerHub On-Premise 1.20.0 and later.

To use the Azure API Management integration, you first need to configure an application in Azure that will authenticate requests from your SwaggerHub instance to the Azure platform.

Requirements

  • Your company must have an Azure Active Directory (Azure AD) tenant. Many companies have existing tenants as part of Microsoft services (such as Microsoft 365) or Azure subscriptions.

  • Your SwaggerHub On-Premise instance must be on HTTPS. Make sure HTTPS is configured, and the SSL Termination setting in the Admin Center is set to either Use SSL with termination on SwaggerHub (certificate required) or Use SSL with termination on external load balancer.

Register an application in Azure

  1. Sign in to the Azure portal at https://portal.azure.com.

  2. Select Azure Active Directory from the portal sidebar.

  3. Select App registrations and click New registration.

    Registering a new application in Azure

    Click the image to enlarge it.

  4. Specify the following settings:

    • Name – SwaggerHub

    • Supported account types – Select one of the following, depending on which Microsoft account types your company uses:

      • Accounts in any organizational directory
      • Accounts in any organizational directory and personal Microsoft accounts (e.g. Skype, Xbox, Outlook.com)
      Accounts in any organizational directory

      Click the image to enlarge it.

    • Redirect URI – Select Web and specify the following value, replacing SWAGGERHUB with your SwaggerHub On-Premise domain:

      https://SWAGGERHUB/apiproxy/plugins/configurations/oauthWithState

  5. Click Register.

  6. Note down the Application (client) ID – you will need it later.

    Azure client ID

    Click the image to enlarge it.

  7. Select Certificates & secrets and click New client secret.

    Creating a new client secret for an Azure application

    Click the image to enlarge it.

  8. Set Expires to Never, enter a description for this client secret, and click Add.

    Client secret configuration
  9. Copy the generated client secret as you will not see it later.

    Azure client secret

    Click the image to enlarge it.

  10. Select API permissions and click Add a permission.

    Adding permissions to an application in Azure

    Click the image to enlarge it.

  11. Select Azure Service Management.

    Azure Service Management

    Click the image to enlarge it.

  12. Select the user_impersonation check box and click Add permissions.

    Adding the user_impersonation permission

    Click the image to enlarge it.

Configure SwaggerHub

  1. Open the Admin Center.

  2. Select Settings > Integrations on the left.

  3. In the Azure API Management Client ID and Azure API Management Client Secret fields, specify the Azure client ID and the client secret you created earlier.

  4. Click Save Changes and Restart. Wait a few minutes for the system to restart completely.

Verify the configuration

  1. Open an existing API definition or create a new one (for example, Petstore).

  2. Click the API name, switch to the Integrations tab, and click Add New Integrations.

  3. Select Azure API Management. This will open the integration settings screen.

  4. You should see the Sign in with Microsoft button at the bottom of the integration settings screen:

    Sign in with Microsoft
    Note: If the "Sign in with Microsoft" image does not appear, make sure you access SwaggerHub using the correct domain name or IP that matches the DNS name for this server value specified in the Admin Center.
    SwaggerHub On-Premise domain
  5. Click Sign in with Microsoft. You should be redirected to Azure and prompted to log in and grant the permissions required by the integration.

    Note: If the Azure login screen shows an error instead, see the troubleshooting tips below.
    Signing in into Azure

    Click the image to enlarge it.

If the "Sign in with Microsoft" button works, you can proceed to configure the Azure API Management integration for your API definitions.

Troubleshooting

AADSTS50011: The reply url specified in the request does not match the reply urls configured for the application

  • Make sure that SwaggerHub’s SSL Termination setting is set to Use SSL.

  • In the Azure portal, go to Azure Active Directory > App registrations > (click your application) > Authentication. Make sure that Redirect URI has Type=Web and the value is set to https://SWAGGERHUB/apiproxy/plugins/configurations/oauthWithState (with SWAGGERHUB replaced with your domain name).

AADSTS50194: Application is not configured as a multi-tenant application. Usage of the /common endpoint is not supported for such applications created after '10/15/2018'. Use a tenant-specific endpoint or configure the application to be multi-tenant.

In the Azure portal, go to Azure Active Directory > App registrations > (click your application) > Authentication and make sure that Supported account types are Accounts in ANY organizational directory, and not Accounts in THIS organizational directory only. If this option has a wrong value, delete the existing Azure application and create a new one as explained above. Remember also to update the Azure client ID and secret in the SwaggerHub Admin Center.

AADSTS650057: Invalid resource. The client has requested access to a resource which is not listed in the requested permissions in the client's application registration.

In the Azure portal, go to Azure Active Directory > App registrations > (click your application) > API permissions and add a permission for Azure Service Management > user_impersonation.

See Also

Configuring SwaggerHub On-Premise
Azure API Management Integration

Highlight search results