Upgrade

You can follow the same procedure to upgrade Portal as you do for other Gloo Gateway components.

  1. Review the gateway-portal-web-server.glooPortalServer* related Helm settings. Common settings that you might want to upgrade include:

    • database: Set up a Postgres backing database. For more information, see the Portal database guide.
    • env: Set a custom name for the claim key to use for admin permissions. For more information, see Customize the admin group claim name.
    • idpServerUrl: Connect the portal server with an IdP so that your users can self-service their own login credentials. For more information, see the OAuth guide.
    • resources: Set up resource requests and limits for the portal server.
    • verbose: Enable verbose logging to help debug the portal server.

  2. Follow the Upgrade guide.

Customize the admin group claim name

Gloo Portal includes a sample React frontend app for a developer portal. To protect the frontend app with an OAuth login, the OIDC provider must return access and ID tokens with the following claims. Keep in mind that your OIDC provider might also require the users to have values for these claims in order to return the claim (such as a first and last name, not just a username, configured in the user profile).

Claims required to log in:

  • email
  • name
  • preferred_username
  • sub

Claims required for admin tasks such as managing subscriptions:

  • group: admin, note that this claim cannot be returned as an array. If your IdP cannot provide the group claim, such as when group is a reserved claim in Okta, you can customize this claim key name. For an example, see Customize the admin group claim name.

Some OIDC providers do not return all of these claims by default. In the AuthConfig, you might be able to request additional scopes, such as openid, profile, and email to get back tokens with these claims. Otherwise, create custom claims and claim mapping for these tokens in your OIDC provider.

To customize the admin group claim name:

  1. In your IdP, determine the claim that you want to use to identify admin users. This claim’s value must be return admin, and cannot return the value in an array. For example steps on creating a custom claim, consult your IdP documentation or the IdP setup guide that uses Keycloak as an example.

  2. Get the Helm values file for your current Gloo Gateway installation.

      helm get values gloo -n gloo-system -o yaml > gloo-gateway.yaml
open gloo-gateway.yaml

  3. In the gateway-portal-web-server section, configure a CUSTOM_GROUP_CLAIM_KEY environment variable for the custom claim from your IdP. Replace <key-name> with the name of the key for the claim that you want to use to grant admin permissions.

      ...
gateway-portal-web-server:
  enabled: true
  glooPortalServer:
    env: 
    - name: CUSTOM_GROUP_CLAIM_KEY
      value: <key-name>

  4. Upgrade Gloo Gateway, such as with the following example command.

      helm repo update
helm upgrade -i gloo glooe/gloo-ee \
  --namespace gloo-system \
  -f gloo-gateway.yaml \
  --version $UPGRADE_VERSION

  5. Continue with the next steps for using your IdP for OAuth with Portal.

Uninstall Portal

You can follow the same procedure to uninstall Portal as you do for other Gloo Gateway components.

For more information, see Uninstall.