Authorization code

Use authorization codes to authenticate requests with an external identity provider.

For more information or other OAuth options, see the OAuth about page.

Before you begin

1. Follow the Get started guide to install Solo Enterprise for kgateway.

2. Follow the Sample app guide to create a gateway proxy with an HTTP listener and deploy the httpbin sample app.

3. Get the external address of the gateway and save it in an environment variable.

   export INGRESS_GW_ADDRESS=$(kubectl get svc -n kgateway-system http -o jsonpath="{.status.loadBalancer.ingress[0]['hostname','ip']}")
   echo $INGRESS_GW_ADDRESS  

   kubectl port-forward deployment/http -n kgateway-system 8080:8080

Step 1: Set up your Identity Provider

Set up an OpenID Connect (OIDC) compatible identity provider (IdP).

For example, you can use Keycloak as an IdP.

Step 2: Enforce authorization code

Use AuthConfig and EnterpriseKgatewayTrafficPolicy resources to apply the auth rules to the routes that you want to secure with authorization code OAuth.

1. Create a Kubernetes secret to store your Keycloak client credentials.

   kubectl apply -f - <<EOF
   apiVersion: v1
   kind: Secret
   metadata:
     name: oauth-keycloak
     namespace: kgateway-system
   type: extauth.solo.io/oauth
   stringData:
     client-secret: ${KEYCLOAK_SECRET}
   EOF

2. Create an AuthConfig resource with your authorization code OAuth rules.

   kubectl apply -f- <<EOF
   apiVersion: extauth.solo.io/v1
   kind: AuthConfig
   metadata:
     name: oauth-authorization-code
     namespace: httpbin
   spec:
     configs:
     - oauth2:
         oidcAuthorizationCode:
           appUrl: "http://${INGRESS_GW_ADDRESS}:80"
           callbackPath: /callback
           clientId: ${KEYCLOAK_CLIENT}
           clientSecretRef:
             name: oauth-keycloak
             namespace: kgateway-system
           issuerUrl: "${KEYCLOAK_URL}/realms/master/"
           scopes:
           - email
           session:
             failOnFetchFailure: true
             redis:
               cookieName: keycloak-session
               options:
                 host: ext-cache-enterprise-kgateway:6379
           headers:
             idTokenHeader: jwt
   EOF

   Review the following table to understand this configuration. For more authorization code options, see the Gloo Edge API docs.

   Field	Description
   oauth2.oidcAuthorizationCode	Set up the OAuth policy to authenticate requests with an authorization code.
   appUrl	The public URL of the app that you want to set up external auth for. This setting is used in combination with the callbackPath attribute.
   callbackPath	The callback path, relative to the appUrl setting. After a user authenticates, the IdP redirects the user to this callback URL. Solo Enterprise for kgateway intercepts requests with this path, exchanges the authorization code received from the IdP for an ID token, places the ID token in a cookie on the request, and forwards the request to its original destination. Note: The callback path must have a matching route that the EnterpriseKgatewayTrafficPolicy applies to. For example, you could simply have a / path-prefix route which would match any callback path. The important part of this callback “catch all” route is that the request goes through the routing filters, including external auth.
   clientId	The client ID token that you got when you registered your app with the IdP. In this example, you set the client ID when you set up Keycloak.
   clientSecretRef	The Kubernetes secret that has the client secret that you got when you registered your app with the identity provider. The secret must exist on the same cluster as the external auth service that enforces this policy. In this example, you created the secret in an earlier step.
   issuerUrl	The URL of the OpenID Connect IdP. Solo Enterprise for kgateway automatically discovers OIDC configuration by querying the .well-known/openid-configuration endpoint on the issuer_url. In this example, Solo Enterprise for kgateway expects to find OIDC discovery information at "${KEYCLOAK_URL}/realms/master/".
   scopes	Scopes to request in addition to the openid scope, such as email in this example.
   session	Details on how to store the user session details. In this example, the cookie is stored as by the name keycloak-session in a Redis instance that is set up for the external auth service by default. The Redis service name is in the format ext-cache-<gateway-class-name>, such as ext-cache-enterprise-kgateway. If your Redis instance is for a different GatewayClass, update the name accordingly.
   headers	Forward the ID token to the destination after successful authentication. In this example, the ID token is sent as a JWT.

3. Create an EnterpriseKgatewayTrafficPolicy resource that refers to the AuthConfig that you created. The following policy applies external auth to all routes that the Gateway serves.

   kubectl apply -f - <<EOF
   apiVersion: enterprisekgateway.solo.io/v1alpha1
   kind: EnterpriseKgatewayTrafficPolicy
   metadata:
     name: oauth-authorization-code
     namespace: kgateway-system
   spec:
     targetRefs:
       - name: http
         group: gateway.networking.k8s.io
         kind: Gateway
     entExtAuth:
       authConfigRef:
         name: oauth-authorization-code
         namespace: httpbin
   EOF

4. Verify that the AuthConfig is ACCEPTED.

   kubectl get authconfig oauth-authorization-code -n httpbin -o yaml

   If you see a REJECTED error similar to invalid character 'k' looking for beginning of object key string, try copying the values of your environment variables manually into the AuthConfig resource.

Step 3: Verify access token validation

Sign in through your IdP to access your protected app.

Cleanup

kubectl delete authconfig oauth-authorization-code -n httpbin
kubectl delete EnterpriseKgatewayTrafficPolicy oauth-authorization-code -n kgateway-system
kubectl delete secret oauth-keycloak -n kgateway-system