Reference

Authentication

The Zuplo Developer Portal supports authenticating with any standard-compliant OpenID Connect identity provider such as Auth0, Okta, AWS Cognito, etc. The developer portal also supports external auth sources like Supabase.

Below are instructions on how to configure some of the common providers.

Production Authentication

Production Developer Portals must setup custom authentication.

Out of the box, authentication to your developer portal uses Zuplo's test Auth0 account. The test Auth0 account cannot be used in production (it will fail on custom domains) and is limited to a small number of users per month per project.

Auth0 Setup#

If you don't have an Auth0 account, you can sign up for a free Auth0 account that will provide you will 7,000 monthly active users.

1/ Create Auth0 Application#

Create a new Auth0 application in the Auth0 dashboard. When creating the application select type "Single Page Web Applications"

2/ Configure Auth0 Application#

You must set the following fields in the Auth0 application:

Application URIs

  • Allowed Callback URLs: Add your docs site url (i.e. https://my-app.zuplo.app/docs/). Note, you should include the trailing slash.
  • Allowed Logout URLs: Add your docs site url (i.e. https://my-app.zuplo.app/docs/). Not you should include the trailing slash.
  • Allowed Web Origins: Add your docs site url without the path (i.e. https://my-app.zuplo.app)

Refresh Token Rotation

  • Rotation: Enabled
  • Reuse Interval: Leave at 0

Refresh Token Expiration

  • Absolute Expiration: Enabled
  • Absolute Lifetime: Can be whatever time you want, default is 2592000
  • Inactivity Expiration: Enabled
  • Inactivity Lifetime: Can be whatever you want, default is 1296000

3/ Create an Auth0 API#

Create an API in the Auth0 portal. Set the Identifier to something like https://api.my-domain.com/. You will enter this value into Zuplo as the Audience in the next step.

Note

The identifier is commonly a URI, but it doesn't have to be, nor does the URI have to match where your API is hosted. It is common practice to use the same identifier for all different environments of your API even if they are on different URLs.

4/ Configure the Developer Portal#

Inside of the Zuplo Developer portal navigate to the Code Editor tab and open the dev-portal.json file. You can edit the JSON manually, but in this tutorial we will use the UI editor.

Set the following settings:

  • Enable Authentication: Checked
  • Provider: auth0
  • Authority: This is your Auth0 domain (i.e. my-company.us.auth0.com) in URL format like https://my-company.us.auth0.com/. The trailing slash is required.
  • Client ID: The client ID of the Auth0 application that was created in the earlier steps. This is a string of letters an numbers. The Client ID is not a secret value.
  • Audience: This is the value for identifier that you set when creating the Auth0 API earlier.

External Auth Setup#

You can setup non-OIDC auth sources to work with the developer portal. See our Supabase Auth Guide to learn how to configure an external auth provider.

Previous
OpenAPI Specifications