General debugging

Begin debugging Gloo Portal by taking the following steps.

  1. Check that the gateway-portal-web-server is running.

      kubectl get pods -n gloo-system -l app=gateway-portal-web-server

  2. Check the logs of the Gloo Portal server.

      kubectl logs -n gloo-system deploy/gateway-portal-web-server

    Optionally, you can format the output with jq or save it in a local file so that you can read and analyze the output more easily.

      kubectl logs -n gloo-system deploy/gateway-portal-web-server > logs-gateway-portal-web-server.json

  3. Check the state of other Gloo components that the portal server interacts with, such as the gloo control plane, rate limiter, and external auth service. For more information, see the Debugging guide.

Backing database

Gloo Portal supports two types of backing databases: the default in-memory SQLite and bring-your-own Postgres.

  • Default in-memory: By default, the portal server includes a SQLite in-memory database. Any time that you upgrade or restart the portal server, the information in this database is removed. For example, your Teams, Apps, credentials, and other information that you created through the frontend portal get deleted. Use this method only for quick testing and temporary development environments.
  • Postgres (preferred): Gloo Portal supports setting up Postgres as the RDBMS. The Postgres instance can be a deployment in the same cluster as Gloo Portal or in an external instance. If you use an external instance, make sure that your cluster can connect to the instance. For example, you might need to create the instance in the same virtual private cloud (VCP) and configure firewall, security groups, and other network and access control features.

To set up Postgres, follow the Database guide. Optionally, you can include a Postgres admin UI to help troubleshoot.

Sample React frontend app

Gloo Portal provides a sample React app that you can use to try out or adapt a developer portal with your own development resources. Review the following topics for common issues when configuring the frontend app.

Frontend URL does not open

Review the Create a portal tutorial, paying particular attention to the following details:

  1. The VITE_PORTAL_SERVER_URL environment variable of the frontend app matches the hostname that you configure in the HTTPRoute.
  2. The HTTPRoute includes a matching hostname and is backed by the frontend app.

Common errors to check for include:

  • Having a mismatch between http and https for the URLs in the frontend app and the HTTPRoute hostname.
  • Using an https URL but forgetting to attach the HTTPRoute to an https listener instead of an http listener (or vice versa).
  • Not including the /v1 path at the end of the URL that the sample React frontend app requires.
  • Not having a Kubernetes ReferenceGrant if the HTTPRoute and the frontend’s service are in different namespaces.

No APIs or other resources show up

Sometimes when you open the frontend app, you do not see any APIs. Review the following possible issues in your setup.

  1. Make sure that you have an HTTPRoute to the backend portal server. The route must include the /v1 path that the sample Reach frontend app needs to serve the portal server APIs to the web page. For an example, see the Create a portal tutorial.

  2. If the hostnames for the backend and frontend portal HTTPRoutes differ, attach a CORS policy to the frontend route. For an example, see the Create a portal tutorial.

  3. Check the visibility settings of the Portal. If the visibility is set to public: false, then your ApiProducts are hidden until users log in.

  4. Check for a PortalGroup that specifies particular claims that a user must have when logging in. Without such claims, you cannot see the ApiProducts that the PortalGroup selects. For more information, see Set up AuthZ with PortalGroups.

Login leads to a 403

When you open the frontend app and click Login, you are redirected to a 403 Forbidden page.

  1. Increase the request timeout settings in the ext auth deployment, particularly if you use an IdP that is external to your cluster such as Okta.

    Example Helm settings:

      
global:
  extensions:
    extAuth:
      enabled: true
      requestTimeout: 3s

  2. Make sure that the credentials in the AuthConfig for the IdP are correct. Common errors include wrong client IDs and client secrets.

  3. If you still have issues, enable debug logging in the ext auth deployment, repeat the login flow, and check for any further errors in the logs.

    Example Helm settings:

      
global:
  extensions:
    extAuth:
      enabled: true
      requestTimeout: 3s
      deployment:
        logLevel: debug

Login does not redirect me to the IdP

When you open the frontend app and click Login, nothing seems to happen.

  1. Check the HTTPRoute for the frontend app. Make sure that the routes for the login and logout are configured with the required /v1 path.

      ...
rules:
  - backendRefs:
      - name: portal-frontend
        port: 4000
    matches:
    - path:
        type: PathPrefix
        value: /v1/login
    - path:
        type: PathPrefix
        value: /v1/logout

  2. If the frontend hostname and backend hostname differ, make sure that you have a CORS policy attached to the frontend route.

  3. In the AuthConfig for the oidcAuthorizationCode, make sure that the following fields are set:

    • The callbackPath field is set to /v1/login.
    • The logoutPath field is set to /v1/logout.
    • The issuerUrl field is set to the correct path for your IdP. Common errors include trailing slashes, the wrong realm, or http instead of https.
    • The appUrl is set to the frontend URL. Common errors include trailing slashes or http instead of https.

  4. In your IdP, make sure that the client or app you are using allows the portal frontend URLs as redirect URIs. Include both the main URL for your portal, such as https://portal.example.com and the login URL, https://portal.example.com/v1/login.

  5. If you still have issues, enable debug logging in the ext auth deployment, repeat the login flow, and check for any further errors in the logs.

    Example Helm settings:

      
global:
  extensions:
    extAuth:
      enabled: true
      requestTimeout: 3s
      deployment:
        logLevel: debug

Login redirects to IdP but does not log me in

When you open the frontend app and click Login, you are redirected to the IdP to log in. When you are redirected back to the frontend app, however, you are still not logged in.

  1. In the AuthConfig oidcAuthorizationCode section, make sure that you do not store session data in Redis. The frontend app expects to fetch the session cookie in the browser, not Redis.

      
       session:
         failOnFetchFailure: true
         cookie:
           allowRefreshing: true
         # --- Remove any Redis sessions such as the following ---
         # redis:
         #   cookieName: session
         #   options:
         #     host: redis:6379

  2. Verify that your IdP returns the required claims in your ID token. For example steps, see Add custom claims. The following claims are required:

    • email
    • name
    • preferred_username
    • sub
    • group: admin (for admin users)

  3. If you made many recent changes to your AuthConfig, you might need to restart the portal server to pick up on these changes.

      kubectl rollout restart deployment gateway-portal-web-server -n gloo-system

Login does not recognize me as an admin

You are able to log in to the frontend app. However, you do not have admin permissions, and cannot see the Subscriptions tab, even though you are an admin.

Make sure that the token returned from your IdP has the group: admin claim. This value cannot be an array. If you do not have this claim, configure your IdP provider and try again. For example steps, see Add custom claims.

Self-service of OAuth credentials fails

As a user of the portal frontend, you might try to create your own OAuth credentials to your team’s apps. Sometimes, this action fails with an error message.

  1. If the error message goes away before you can review it:

    1. From your browser developer tools, inspect the webpage.
    2. From the Network tab, find the failed oauth-credentials call.
    3. In the Response pane, review the error message.

  2. Review the following errors and descriptions.

Error messageDescription
500 Internal Server Error could not obtain token for client , Invalid client or Invalid client credentialsThe IdP Connect server has the wrong client credentials. Update the credentials by upgrading the gloo-portal-idp-connect Helm chart and try again.
403 Forbidden insufficient_scopeThe client that the IdP Connect server uses does not have the required scope to create a client. In your IdP, assign the client this scope. In Keycloak, you can assign the manage-clients scope from the Clients > Client details > Service accounts roles page.

No status or automatically generated resources

You might notice that your Gloo Portal resources such as ApiDocs and ApiProducts do not have any status.

Resources that Gloo Portal creates for you might not show up, such as the following:

  • No ApiDoc after annotating a service with the necessary gloo.solo.io/scrape-openapi-* annotations for automatic discovery.
  • No ApiDoc with a stitched schema after creating a Portal resource.
  • No PortalConfig after creating a Portal resource.

To fix these issues, make sure that you fully enabled Gloo Portal in your setup.

  1. Get the Helm values of your current Helm release.

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

  2. Check the values to ensure the following settings.

    • You have an Enterprise license set.
    • You have the Gloo Portal plugin enabled, such as in the following section.
        
gloo:
  kubeGateway:
    portal:
      # Enables the Gloo Portal plugin, as well as installs the Helm subchart with the Portal CRDs and necessary RBAC settings.
      enabled: true
    • You have the portal server deployed, such as in the following section. Note that the default value is true. To be safe, explicitly set this value to true.
        
gateway-portal-web-server:
  glooPortalServer:
    enabled: true

  3. If necessary, update your settings and upgrade your Helm release.