To make your service accessible outside the Kyma cluster, expose it using the Kyma API Gateway Controller, which listens for the custom resource (CR) objects that follow the apirules.gateway.kyma-project.io CustomResourceDefinition (CRD). Creating a valid CR triggers the API Gateway Controller to create an Istio Virtual Service. Optionally, you can specify the rules attribute of the CR to secure the exposed service with Oathkeeper Access Rules.

The API Gateway Controller allows you to secure the exposed services using JWT tokens issued by Kyma Dex, or OAuth2 tokens issued by the Kyma OAuth2 server. You can secure the entire service, or secure the selected endpoints. Alternatively, you can leave the service unsecured.

NOTE: To learn more, read about the Kyma OAuth2 server.

This diagram illustrates the workflow that leads to exposing a service in Kyma:

• API Gateway Controller is a component responsible for exposing services. The API Gateway Controller is an application deployed in the kyma-system Namespace, implemented according to the Kubernetes Controller principles. The API Gateway Controller listens for newly created custom resources (CR) that follow the set apirule.gateway.kyma-project.io CustomResourceDefinition (CRD), which describes the details of exposing services in Kyma.

• Istio Virtual Service specifies the services visible outside the cluster. The API Gateway Controller creates a Virtual Service for the hostname defined in the apirule.gateway.kyma-project.io CRD. The convention is to create a hostname using the name of the service as the subdomain, and the domain of the Kyma cluster. To learn more about the Istio Virtual Service concept, read this Istio documentation. To get the list of Virtual Services in Kyma, run:

  Click to copy

  kubectl get virtualservices.networking.istio.io --all-namespaces

• Oathkeeper Access Rule allows operators to specify authentication requirements for a service. It is an optional resource, created only when the CR specifies the desired authentication method, the trusted token issuer, allowed methods and paths, and required scopes. To learn more, read about ORY Oathkeeper Access Rules.

  To get the list of Oathkeeper Access Rules created in Kyma, run:

  Click to copy

  kubectl get rules.oathkeeper.ory.sh --all-namespaces

Request flow

This diagram illustrates the request flow for three cases:

• Accessing secured resources with an OAuth2 token
• Accessing secured resources with a JWT token
• Accessing unsecured resources without a token

Accessing secured resources with an OAuth2 token

The developer sends a request to access a secured resource with an OAuth2 access token issued for a registered client. The request is proxied by the Oathkeeper proxy. The proxy identifies the token as an OAuth2 access token and sends it to the registered Token Introspection endpoint in the Hydra OAuth2 server. The OAuth2 server validates the token and returns the outcome of the validation to Oathkeeper. If the validation is successful, Oathkeeper checks the token against the Access Rules that exist for the resource and authorizes the request. Upon successful authorization, the request is forwarded to the resource.

Accessing secured resources with a JWT token

The developer sends a request to access a secured resource with a JWT token. The request is proxied by the Oathkeeper proxy. The proxy identifies the token as a JWT token and fetches the public keys required for token validation from the registered Dex instance. Oathkeeper uses these keys to validate the token. If the validation is successful, Oathkeeper checks the token against the Access Rules that exist for the resource and authorizes the request. Upon successful authorization, the request is forwarded to the resource.

Accessing unsecured resources without a token

The developer sends a request to access a resource without a token. The request is proxied by the Oathkeeper proxy. The proxy checks if there are Access Rules created for the resource, and verifies if it can be accessed without a token. If the resource can be accessed without a token, the request is forwarded to the resource.

The API Gateway Controller uses a whitelist of domains for which it allows to expose services. Every time a user creates a new APIRule custom resource (CR) for a service, the API Gateway Controller checks the domain of the service specified in the CR against the whitelist. If the domain of the service matches a whitelisted entry, the API Gateway Controller creates a Virtual Service and Oathkeeper Access Rules for the service according to the details specified in the CR. If the domain is not whitelisted, the Controller creates neither a Virtual Service nor Oathkeeper Access Rules and, as a result, does not expose the service.

If the domain does not match the whitelist, the API Gateway Controller sets an appropriate validation status on the APIRule CR created for that service.

TIP: For more information, read about the Api CR statuses.

By default, the only whitelisted domain is the domain of the Kyma cluster.

The API Gateway Controller uses a blacklist of services for which it does not create either a Virtual Service or Oathkeeper Access Rules. As a result, these services cannot be exposed. Every time a user creates a new APIRule custom resource (CR) for a service, the API Gateway Controller checks the name of the service specified in the CR against the blacklist. If the name of the service matches a blacklisted entry, the API Gateway Controller sets an appropriate validation status on the APIRule CR created for that service.

TIP: For more information, read about the Api CR statuses.

The blacklist works as a security measure and prevents users from exposing vital internal services of Kubernetes, Istio, and API Server Proxy.

This tutorial shows how to expose and secure services or Functions using API Gateway Controller. The controller reacts to an instance of the APIRule custom resource (CR) and creates an Istio Virtual Service and Oathkeeper Access Rules according to the details specified in the CR. To interact with the secured services, the tutorial uses an OAuth2 client registered through the Hydra Maester controller.

The tutorial comes with a sample HttpBin service deployment and a sample Function.

Register an OAuth2 client and get tokens

1. Export these values as environment variables:

• The name of your client and the Secret which stores the client credentials:

  Click to copy

  export CLIENT_NAME={YOUR_CLIENT_NAME}

• The Namespace in which you want to create the client and the Secret that stores its credentials:

  Click to copy

  export CLIENT_NAMESPACE={YOUR_CLIENT_NAMESPACE}

• The domain of your cluster:

  Click to copy

  export DOMAIN={CLUSTER_DOMAIN}

2. Create an OAuth2 client with read and write scopes. Run:

   Click to copy

   cat <<EOF | kubectl apply -f -
   apiVersion: hydra.ory.sh/v1alpha1
   kind: OAuth2Client
   metadata:
     name: $CLIENT_NAME
     namespace: $CLIENT_NAMESPACE
   spec:
     grantTypes:
       - "client_credentials"
     scope: "read write"
     secretName: $CLIENT_NAME
   EOF

3. Export the credentials of the created client as environment variables. Run:

   Click to copy

   export CLIENT_ID="$(kubectl get secret -n $CLIENT_NAMESPACE $CLIENT_NAME -o jsonpath='{.data.client_id}' | base64 --decode)"
   export CLIENT_SECRET="$(kubectl get secret -n $CLIENT_NAMESPACE $CLIENT_NAME -o jsonpath='{.data.client_secret}' | base64 --decode)"

4. Encode your client credentials and export them as an environment variable:

   Click to copy

   export ENCODED_CREDENTIALS=$(echo -n "$CLIENT_ID:$CLIENT_SECRET" | base64)

5. Get tokens to interact with secured resources using client credentials flow:

Deploy, expose, and secure the sample resources

Follow the instructions in the tabs to deploy an instance of the HttpBin service or a sample Function, expose them, and secure them with Oauth2 scopes.

CAUTION: When you secure a service, don't create overlapping Access Rules for paths. Doing so can cause unexpected behavior and reduce the security of your implementation.

Access the secured resources

Follow the instructions in the tabs to call the secured service or Functions using the tokens issued for the client you registered.

Basic diagnostics

API Gateway is a Kubernetes controller which operates on APIRule custom resources. To diagnose the problems, inspect the status field of the APIRule CR:

kubectl describe apirules.gateway.kyma-project.io -n {NAMESPACE} {NAME}

If the status is Error, edit the APIRule and fix issues described in .Status.APIRuleStatus.Desc. If you still encounter issues, make sure the API Gateway, Hydra and Oathkeeper are running or take a look at other, more specific troubleshooting guides.

401 Unauthorized or 403 Forbidden

If you reach your service and get 401 Unauthorized or 403 Forbidden in response, make sure that:

• You are using an access token with proper scopes and it is active:

  1. Export the credentials of your OAuth2Client as environment variables:

     Click to copy

     export CLIENT_ID="$(kubectl get secret -n $CLIENT_NAMESPACE $CLIENT_NAME -o jsonpath='{.data.client_id}' | base64 --decode)"
     export CLIENT_SECRET="$(kubectl get secret -n $CLIENT_NAMESPACE $CLIENT_NAME -o jsonpath='{.data.client_secret}' | base64 --decode)"

  2. Encode your client credentials and export them as an environment variable:

     Click to copy

     export ENCODED_CREDENTIALS=$(echo -n "$CLIENT_ID:$CLIENT_SECRET" | base64)

  3. Check access token status:

     Click to copy

     curl -X POST "https://oauth2.{DOMAIN}/oauth2/introspect" -H "Authorization: Basic $ENCODED_CREDENTIALS" -F "token={ACCESS_TOKEN}"

  4. Generate a new access token if needed.

• Your client from OAuth2Client resource is registered properly in Hydra OAuth2 and OpenID Connect server. You need to call the Hydra administrative endpoint /client from inside of the cluster. Follow this steps:

  1. Fetch the Client ID from Secret specified in the OAuth2Client resource:

     Click to copy

     kubectl get secrets {SECRET_NAME} -n {SECRET_NAMESPACE} -o jsonpath='{ .data.client_id }' | base64 --decode

  2. Create a simple curl Pod:

     Click to copy

     ---
     apiVersion: v1
     kind: Pod
     metadata:
       labels:
         app: ory-curl
       name: ory-curl
       namespace: {SECRET_NAMESPACE}
     spec:
       containers:
       - name: curl
         image: alpine
         terminationMessagePolicy: "FallbackToLogsOnError"
         command:
           - /bin/sh
           - -c
           - |
             apk add curl jq
             curl ory-hydra-admin.kyma-system.svc.cluster.local:4445/clients | jq '.'

  3. Check logs from the ory-curl Pod:

     Click to copy

     kubectl logs -n {SECRET_NAMESPACE} ory-curl curl

  4. If the Client ID from step 1 is not available on the clients list, make sure Hydra has access to the database and/or restart the Hydra Measter Pod. You can check the logs using the following commands:

  Click to copy

  # Check logs from the Hydra-Maester controller application
  kubectl logs -n kyma-system -l "app.kubernetes.io/name=hydra-maester" -c hydra-maester
  # Example output
  2020-05-04T12:19:04.472Z  INFO  controller-runtime.controller Starting EventSource  {"controller": "oauth2client", "source": "kind source: /, Kind="}
  2020-05-04T12:19:04.472Z  INFO  setup starting manager
  2020-05-04T12:19:04.573Z  INFO  controller-runtime.controller Starting Controller {"controller": "oauth2client"}
  2020-05-04T12:19:04.673Z  INFO  controller-runtime.controller Starting workers  {"controller": "oauth2client", "worker count": 1}
  2020-05-04T12:26:30.819Z  INFO  controllers.OAuth2Client  using default client
  2020-05-04T12:26:30.835Z  INFO  controllers.OAuth2Client  using default client
  # This log informs that a client has been created, and should be visible within hydra
  2020-05-04T12:26:31.468Z  DEBUG controller-runtime.controller Successfully Reconciled {"controller": "oauth2client", "request": "test-ns/test-client"}
  # Check logs from the Hydra application
  kubectl logs -n kyma-system -l "app.kubernetes.io/name=hydra" -c hydra

404 Not Found

If you reach your service and get 404 Not Found in response, make sure that:

• Proper Oathkeeper Rule has been created:

  Click to copy

  kubectl get rules.oathkeeper.ory.sh -n {NAMESPACE}

  TIP: Name of the Rule consists of the name of the APIRule and a random suffix.

• Proper VirtualService has been created:

  Click to copy

  kubectl get virtualservices.networking.istio.io -n {NAMESPACE}

  TIP: Name of the VirtualService consists of the name of the APIRule and a random suffix.