Configuring Azure API Management Integration

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

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.

   

   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)
     

     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.

   

   Click the image to enlarge it.

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

   

   Click the image to enlarge it.

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

   

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

   

   Click the image to enlarge it.

10. Select API permissions and click Add a permission.

    

    Click the image to enlarge it.

11. Select Azure Service Management.

    

    Click the image to enlarge it.

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

    

    Click the image to enlarge it.

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.

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:

   

   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.

   

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.

   

   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.

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.