Configure Azure API Management Integration
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 or .
Register an application in Azure
Sign in to the Azure portal at https://portal.azure.com.
Select Azure Active Directory from the portal sidebar.
Select App registrations and click New registration.
Specify the following settings:
Name – SwaggerHub
Supported account types – Select one of the following, depending on which Microsoft account types your company uses:
Redirect URI – Select Web and specify the following value, replacing SWAGGERHUB with your SwaggerHub On-Premise domain:
https://SWAGGERHUB/apiproxy/plugins/configurations/oauthWithState
Click Register.
Note down the Application (client) ID – you will need it later.
Select Certificates & secrets and click New client secret.
Set Expires to Never, enter a description for this client secret, and click Add.
Copy the generated client secret as you will not see it later.
Select API permissions and click Add a permission.
Select Azure Service Management.
Select the user_impersonation check box and click Add permissions.
Configure SwaggerHub
Open the Admin Center.
Select Settings > Integrations on the left.
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.
Click Save Changes and Restart. Wait a few minutes for the system to restart completely.
Verify the configuration
Open an existing API definition or create a new one (for example, Petstore).
Click the API name, switch to the Integrations tab, and click Add New Integrations.
Select Azure API Management. This will open the integration settings screen.
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 value specified in the Admin Center.
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.
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 .
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.