About authentication and authorization

You can set up two primary types of security for the portal: external authentication and user authorization.

  • External authentication: Require users to externally authenticate via an OpenID Connect (OIDC) provider when they send a request to a portal endpoint.
  • User authorization with PortalGroups: Specify claims that must be present in the user’s JWT from the OIDC provider before the user gets access to a particular API.

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.

Figure: OIDC authentication flow when logging in to the developer portal
Figure: OIDC authentication flow when logging in to the developer portal
Figure: OIDC authentication flow when logging in to the developer portal
Figure: OIDC 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.

Set up external authentication

For instructions, follow the Secure access to the portal tutorial.

User authorization for private APIs with 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 successful 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.

Figure: Authorization for private API products with portal groups
Figure: Authorization for private API products with portal groups
Figure: Authorization for private API products with portal groups
Figure: Authorization for private API products with portal groups

Create a portal group for authorization

To control access to private API products in your developer portal, you set up portal groups and specify the conditions that must be met to successfully authorize a user to see the private APIs.

  1. Set up an OIDC provider for the developer portal. For example, see Steps 1 and 2 in the Keycloak guide. This step is required to receive the ID token from your OIDC provider and identify the claims that you want to use for your PortalGroup.

  2. Identify the claims in the ID token that you want to match on. For example steps to create a custom claim, see Step 3 in the Keycloak guide. Only if a user presents a token with the right claims, the user is matched with the PortalGroup and is granted access to the private APIs and usage plans that you define in the PortalGroup. The ID token is returned by the OIDC provider during authentication. Depending on the OIDC provider that you use, you can customize the claims that are being returned in the ID token. However, some OIDC provider might not allow you to create custom claims.

    Your ID token might have a claim structure that is similar to the following:

      {
  "exp": 1681133278,
  "iat": 1681133218,
  "auth_time": 1681133218,
  "jti": "3e410301-d9a2-463f-a127-df78a94f87db",
  "iss": "http://34.xxx.xxx.xxx:8080/auth/realms/master",
  "aud": "4464fbac-ab29-4c6a-945b-14e4685c0ad4",
  "sub": "83a467a1-8f4e-4dd6-8fd1-34832ba0a84e",
  "typ": "ID",
  "azp": "4464fbac-ab29-4c6a-945b-14e4685c0ad4",
  "session_state": "aac7790f-036c-4367-b728-1f1d9dc355fe",
  "at_hash": "2nFLjyWQA2pEANc8zuhwTw",
  "acr": "1",
  "email_verified": false,
  "preferred_username": "user1",
  "email": "user1@example.com",
  "group": "users"
}

  3. Create a PortalGroup to allow access to the petstore API product for a user that presents an ID token with the X-groups: users claim.

      kubectl apply -f- <<EOF
apiVersion: portal.gloo.solo.io/v1
kind: PortalGroup
metadata:
  name: petstore-group
  namespace: gloo-system
spec:
  membership:
  - claimGroup:
    - key: X-groups
      value: users
  apiProducts:
  - name: '*'
    namespace: gloo-system
EOF
    SettingDescription
    membershipThe claims that determine whether a user belongs to the PortalGroup. Users must have a JWT ID token with claims that match all the claims in the membership list.
    claimGroupSet the claims in the JWT ID token that must be present to successfully include the user in this PortalGroup. Note that the claims that you specify must exist in the ID token that your OIDC provider returns. You have the option to specify one or multiple claim sets. In this example, the ID token must include the X-group: users claim.
    apiProductsSelect the ApiProducts that the user can view in the developer portal after the user is matched with this PortalGroup. In this example, the PortalGroup gives members access to all ApiProducts (*) in the gloo-system namespace.