Skip to main content
Swagger
All documentation pages

Automatic API Authentication Settings

Automatic API Authentication lets Swagger Portal call a webhook that you host and add the returned token to Try It Out requests from organization members. For an overview, see Automatic API Authentication Tab.

On-premise installations often use HTTP between internal services, and the webhook and APIs sit on the internal network. To allow this, change the settings described below on the Config tab of the Admin Console. See Swagger Studio 2.x Configuration for the full list of settings.

After you change these settings, scroll down and click Save config, and then use the Version history tab to deploy the updated configuration. See Deploying Configuration Changes.

To configure Automatic API Authentication:

  1. In the Admin Console, open the Config tab.
  2. In the Security section, add the webhook host and every API host that receives the token to Swagger Studio proxy allowlist. For example: sts.internal:8080, api.internal:8080.
  3. If the webhook or the APIs use HTTP, or a port other than 443, enable SP_STS_ALLOW_INSECURE.
  4. Click Save config, and then deploy the configuration.

Settings

  • Swagger Studio proxy allowlist - The hosts that can resolve to private addresses. Enter a comma-separated list of domain names and IP addresses. Use an asterisk (*) as a wildcard. Add a port number to limit access to a single port. The webhook check and the Try It Out proxy both use this list.
  • SP_STS_ALLOW_INSECURE - Allows HTTP URLs and any port for the webhook URL and for audience origins. The default is false.

No other configuration is needed.

The following apply to on-premise:

  • Host names resolve through DNS A records only. Names that exist only in /etc/hosts and IPv6-only hosts don’t work.
  • Portal refuses IP addresses in the URL unless the host is on the allowlist.
  • Portal skips the address checks for an allowlisted host.
  • Credentials in the URL, redirects, the 64 KB response limit, request signing, and IP pinning for webhook calls work the same way as in other installations.

Over HTTP, the member email address and the token cross the network unencrypted. Use HTTP only on a network that you trust, and use HTTPS wherever you can.

Was this page helpful?