About

To allow the Portal server to manage clients in your OIDC provider, you can deploy Gloo Portal IdP Connect. IdP Connect allows your users to use the portal server frontend, instead of navigating to the OIDC provider, to create OAuth credentials.

When an authorized user creates an OAuth client in the portal frontend, the IdP Connect client connects to the IdP that you configured. This IdP Connect client creates the OAuth client in your IdP, and the IdP Connect client passes the client ID and secret back to the portal server. Portal stores the hashed client ID and associates it with the application in the backing database that you set up, such as Postgres. However, the client secret is never stored in the database.

The client secret is shown to users only once at creation time, with a warning to store the secret in a secure place. Your users must keep this secret to make future requests to API products. If they forget the secret, you can access the client ID and secret directly in the IdP (but not the backing portal database). Users can then use the client ID and secret to request an access token from the OIDC provider, and use the access token to send requests to your APIs.

The OAuth credentials grant access to the ApiProducts that the approved Apps that are subscribed to. Your users get access to the Apps through the Teams that they are a part of through the portal frontend. When you apply an OAuth policy to require credentials from the IdP to access your ApiProducts, your users can then use the OAuth credentials that they self-serviced to access the underlying APIs.

You can create the IdP Connect server and OAuth policies before or after setting up the portal frontend. For steps to create the portal frontend, see the Next steps.

Before you begin

  1. Complete the tutorial to set up Gloo Portal, including the sample Tracks app and HTTPRoute.
  2. Set up the Portal database so that the credential data retrieved by the IdP Connect server persists across Portal upgrades and restarts.

Step 1: Set up the IdP

You can use an IdP to enforce authentication for several use cases in Gloo Portal, such as protecting APIs with external auth policies, the portal frontend app, and IdP Connect. It is recommended to use the same IdP for all your Gloo Portal use cases. The following IdPs have been successfully set up with Portal: Amazon Cognito and Keycloak. If you use another IdP, you might need to modify the steps for your setup.

For instructions, follow the Set up an IdP guide. The guide uses Keycloak as an example. You can adjust these steps for other IdPs.

Step 2: Set up IdP Connect

Deploy the IdP Connect implementation to your cluster via Helm.

  1. Add the Gloo Portal IdP Connect Helm repo.

      helm repo add gloo-portal-idp-connect https://storage.googleapis.com/gloo-mesh-enterprise/gloo-portal-idp-connect

  2. Deploy IdP Connect to your cluster. Change the following settings for your OIDC provider, such as the OIDC URL, client ID, and client secret. For more information, see the available Helm settings in the IdP Connect public GitHub repo.

      helm upgrade -i -n gloo-system \
  portal-idp gloo-portal-idp-connect/gloo-portal-idp-connect \
  --version 0.3.0 \
  -f -<<EOF
connector: keycloak
keycloak:
  realm: $KEYCLOAK_URL/realms/$REALM_NAME
  mgmtClientId: $KEYCLOAK_CLIENT
  mgmtClientSecret: $KEYCLOAK_SECRET
EOF

  3. Verify that the deployment completes.

      kubectl -n gloo-system rollout status deploy gloo-portal-idp-connect

  4. Update the Gloo Portal plugin settings in your Gloo Gateway installation to use IdP Connect.

    1. Get the Helm values files for your current installation.

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

    2. Add the following gateway-portal-web-server section to your Helm values file to include the IdP Connect settings. Tip: Check that Gloo Portal uses Postgres as the backing database, too. This way, the data persists across portal server upgrades. For more information, see Portal database.

        
gloo:
  kubeGateway:
    enabled: true
    portal:
      enabled: true
gateway-portal-web-server:
  enabled: true
  glooPortalServer:
    # Enable the IdP Connect settings
    idpServerUrl: http://idp-connect.gloo-system.svc.cluster.local
    # Check that Gloo Portal uses Postgres as the backing database
    database:
      type: postgres

    3. Upgrade your release. For more information about the upgrade process, see the Upgrade guide.

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

    4. Confirm that the Gloo components are healthy.

        glooctl check

      Example output:

        ...
No problems detected.

    5. Confirm that the portal server is running.

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

Good job! The IdP Connect server is ready to provision client credentials in your IdP.

Step 3: Create an OAuth policy

Create an OAuth policy to protect your ApiProducts. This way, users must provide credentials from the connected IdP in order to access the underlying APIs that they have access to through the Portal.

  1. In your IdP’s .well-known/openid-configuration endpoint, get the jwks_uri endpoint. In Keycloak, this endpoint is $KEYCLOAK_URL/realms/$REALM/protocol/openid-connect/certs.

  2. Create an AuthConfig that chains together OAuth2 access token validation and PortalAuth. This way, Gloo can authorize requests along the routes to your ApiProducts by the validated token in the Authorization: Bearer header.

      kubectl apply -f - <<EOF
apiVersion: enterprise.gloo.solo.io/v1
kind: AuthConfig
metadata:
  name: tracks-auth
  namespace: gloo-system
spec:
  configs:
    - name: oauth2Validation
      oauth2:
        accessTokenValidation:
          jwt:
            remoteJwks:
              url: "https://$KEYCLOAK_URL/realms/$REALM/protocol/openid-connect/certs"
    - name: tracksAuth
      portalAuth:
        url: http://gateway-portal-web-server.gloo-system.svc.cluster.local:8080
        redisOptions:
          host: redis:6379
EOF

    Review the following table to understand this configuration.

    SettingDescription
    name: oauth2ValidationMake sure to name each section in your AuthConfig to differentiate across the multiple sections. The example uses oauth2Validation for the oauth2 auth type.
    oauth2.accessTokenValidationSet up access token validation so that the routes to your ApiProducts require an access token. The example uses the remote JSON Web Key Set (JWKS) endpoint from your IdP to validate the token. For more configuration options such as introspection, cache timeouts, or claims to headers, see the API reference in the Gloo Edge docs.
    name: oauth2PortalMake sure to name each section in your AuthConfig to differentiate across the multiple sections. The example uses oauth2Portal for the portalAuth auth type.
    jwt.remoteJwks.urlThe JWKS endpoint that you retrieved from your IdP’s .well-known/openid-configuration endpoint in the previous step.
    portalAuthSet up portalAuth to authorize requests for credentials that the portal server generates based on your users self-servicing through the portal frontend. For OAuth credentials, you must use portalAuth in combination with oauth2.accessTokenValidation. Then, Gloo authorizes requests based on the Bearer token that is already validated from the chained access token OAuth flow. For more configuration options such as cache durations and request timeouts, see the API reference in the Gloo Edge docs.
    portalAuth.urlThe URL for the backend portal server, which by default is the internal Kubernetes service address of http://gateway-portal-web-server.gloo-system.svc.cluster.local:8080.
    redisOptionsSet up the portal server to cache data in the default Redis instance. Otherwise, data is cached in memory.

  3. Create a RouteOption that refers to the AuthConfig that you created in the previous step. The example includes an optional CORS policy to allow credentials to be passed in the “Try it out” feature of the OpenAPI docs in the portal frontend. In the targetRefs, select the HTTPRoutes for the ApiProducts that you want to protect with the ext auth policy. The example applies to the Tracks HTTPRoute. Alternatively, you can update the HTTPRoute to refer to this RouteOption in the extensionRef for each individual API’s route that you want to protect.

      kubectl apply -f - <<EOF
apiVersion: gateway.solo.io/v1
kind: RouteOption
metadata:
  name: tracks
  namespace: gloo-system
spec:
  targetRefs:
  - group: gateway.networking.k8s.io
    kind: HTTPRoute
    name: tracks-route
  options:
    # Ext auth policy
    extauth:
      configRef:
        name: tracks-auth
        namespace: gloo-system
    # CORS policy
    cors:
      allowCredentials: true
      allowHeaders:
      - "*"
      allowMethods:
      - GET
      allowOriginRegex:
      - ".*"
EOF

Step 4: Verify the OAuth policy

Confirm that the routes to your ApiProducts are secured by the OAuth policy.

To test that the OAuth credentials work, you must have your users generate their own credentials. This step requires you to set up the portal frontend. If you do not want to do that, you can also generate your own credentials from the IdP.

  1. Send a request to the Tracks route. If the hostname for your Tracks HTTPRoute is different, update the following example accordingly.

      curl -vik http://api.tracks.com/tracks
  
      curl -vik https://api.tracks.com/tracks
  
      curl -vik localhost/api.tracks.com/tracks

    Example output: Verify that you get back a 403 Forbidden status.

      HTTP/2 403

  2. Get an access token from your IdP. The following example uses Keycloak. Replace the client ID and client secret with your credentials. If you already set up the portal frontend, these credentials can be those that you generated through the self-service feature. For links to these guides, see the Next steps. Otherwise, you can use existing IdP credentials.

      curl -X POST \
-H "Content-Type: application/x-www-form-urlencoded" \
-d "grant_type=client_credentials" \
-d "client_id=$KEYCLOAK_CLIENT" \
-d "client_secret=$KEYCLOAK_SECRET" \
$KEYCLOAK_URL/realms/$KEYCLOAK_REALM/protocol/openid-connect/token

    Example output:

      {"access_token":"eyJhb...","expires_in":60,"refresh_expires_in":0,"token_type":"Bearer","not-before-policy":0,"scope":"profile email"}

  3. Repeat the request to the Tracks route. This time, include your access token in the Authorization: Bearer <access_token> header.

      curl -vik http://api.tracks.com/tracks -H "Authorization: Bearer <access_token>"
  
      curl -vik https://api.tracks.com/tracks -H "Authorization: Bearer <access_token>"
  
      curl -vik localhost/api.tracks.com/tracks -H "Authorization: Bearer <access_token>"

    Example output: Verify that you get back a 200 Success response. If you get an error, your access token might be wrong, expired, or passed in the wrong header. You can check the default expiry and header in the output of the previous step.

      HTTP/2 200

Next steps

If you have not already done so, set up the Portal frontend.

  1. Build the frontend app.
  2. Set up a secure login.
  3. Manage API subscriptions.
  4. Set up rate limits for APIs.

Then, your users can self-service credentials in your connected IdP. Give your users the instructions for OAuth clients.