Secure the portal

Learn how you can secure access to the developer portal and the private APIs that it serves by setting up external authentication and authorization.

External authentication with the developer portal

You can set up external authentication with a supported OpenID Connect (OIDC) provider to control access to the developer portal.

About OIDC

OIDC is an identity layer on top of the OAuth 2.0 protocol. In OAuth 2.0 flows, authentication is performed by an external Identity Provider (IdP) which, in case of success, returns an access token that represents the user's identity.

The OAuth protocol does not define the contents and structure of the access token, which greatly reduces the portability of OAuth 2.0 implementations. The goal of OIDC is to address this ambiguity by additionally requiring Identity Providers to return a well-defined ID Token. OIDC ID tokens follow the JSON Web Token standard and contain specific fields, also referred to as claims, that you can use to verify access to specific app resources.

This standardization allows you to switch between Identity Providers, or support multiple ones at the same time with minimal or no changes to your services.

OIDC authentication for a developer portal

Without OIDC authentication, unauthenticated users can log in to the developer portal and create API keys for public APIs, view API schemas, get information about portal usage plans, or details about the current user's session.

To protect your developer portal with an OIDC provider, you must decide on the developer portal APIs for which you want to require authentication. For example, you typically want to require authentication when logging in to the portal, creating API keys, or viewing a user's session data. However, you might not require authentication to view usage plans.

OIDC authentication flow

The following image illustrates the authentication flow when logging in to the developer portal.

When a user tries to log in to the portal, the request is intercepted by the external auth server and redirected to the OIDC provider where the user must enter the credentials to get authenticated.

After successful authentication, an ID and refresh token are returned by the OIDC provider. You have the option to store these tokens in Redis and get back a Redis session ID, or to return the raw ID token in the Set-Cookie response header. To prove successful authentication in subsequent requests, the user sends the ID token information in the Cookie request header. If you have private API products that your portal serves, the ID token is forwarded to the portal server to extract the claims and find a matching portal group. For more information, see User authorization for private APIs with portal groups.

To learn how to set up authentication for your portal with an OIDC provider, see Set up external authentication.

User authorization for private APIs with portal groups

If your portal serves private APIs, you must configure authorization by using portal groups. A portal group specifies the claims that must be present in a JWT ID token to allow access to specific private APIs and usage plans, and to perform actions, such as to create API keys for these APIs. Therefore, portal groups create an additional layer of security for your portal alongside the external OIDC authentication.

To configure authorization for private APIs, you must set up authentication with an OIDC provider first. After succesful authentication, the OIDC provider returns an ID token and refresh token. The ID token contains the claims that are used to match the user to a portal group. After a matching portal group is found, access to the private APIs and usage plans is granted.

The following image illustrates the authorization flow when trying to create an API key for a private API. Note that this flow assumes that the user is successfully authenticated with an OIDC provider and received an ID token.

To learn how to set up authorization for private API products in your portal, see Set up authorization for private APIs.