External auth server setup
Set up the default or customize your own external auth server.
In version 2.5.8 a regression was introduced that impacts the translation of external auth policies when a virtual destination is used for the external auth server. This issue is fixed in version 2.5.9. If you use a virtual destination for the external auth server, skip the 2.5.8 release and upgrade to 2.5.9 or later instead.
To enforce external authentication policies, your service mesh environment must have an external auth server. Choose from the following options.
Set up the Gloo Mesh external auth server
To enforce external auth policies across your service mesh environment, each Gloo Mesh Enterprise workspace must have one and only one external auth server. You can configure an ExtAuthServer
resource to customize the server behavior, or use the default settings.
Register your workload clusters with the
ext-auth-service
enabled setting. Gloo Mesh Enterprise automatically creates a deployment and service of an external auth server.- The example steps deploy the external auth server to the default
gloo-mesh
namespace. Use this namespace to refer to your server in theExtAuthServer
resource.
- The example steps deploy the external auth server to the default
Optional: To group the external auth services across clusters, create a virtual destination. This way, you get traffic management benefits like location-aware, priority-based routing.
kubectl apply --context ${REMOTE_CONTEXT2} -f - <<EOF apiVersion: networking.gloo.solo.io/v2 kind: VirtualDestination metadata: annotations: cluster.solo.io/cluster: "" name: ext-auth-service-global namespace: gloo-mesh spec: hosts: - ext-auth-service.vd ports: - number: 8083 protocol: GRPC services: - labels: app: ext-auth-service EOF
Review the following table to understand this configuration. For more information, see the API reference.
Setting Description --context ${REMOTE_CONTEXT2}
The virtual destination is created in cluster2
to demonstrate how virtual destinations group services across clusters.app: ext-auth-service
The virtual destination elects the default ext-auth-service
that you enabled during installation. This default installation meets the requirements to use a virtual destination as the destination server:- The service name (
ext-auth-service
) and namespace (gloo-mesh
) match across clusters. - The namespace is Istio-injected so that the ext auth service pods have sidecars.
- The service name (
Create an
Review the following table to understand this configuration.ExtAuthServer
resource for your workspace. This resource points to the destination server to use for external auth policies. The destination server can be the defaultext-auth-service
from your Gloo Mesh Enterprise installation, your own custom server, or the virtual destination that you optionally created in the previous step.You can also use theExtAuthServer
resource to customize certain behaviors such as request timeouts, buffering, and HTTP status codes. For more information, see the API reference.Setting Description metadata
The name and namespace for this external auth server resource. You can have only one external auth server resource per workspace. This resource does not have to be in the same namespace as the destination server. However, if this resource and the destination server are not in the same workspace, this resource’s workspace must import the destination server’s service. destinationServer
The external auth server for Gloo Mesh Enterprise to use to enforce external auth policies. The examples select either a virtual destination or the default Gloo Mesh Enterprise Kubernetes service. If unset, Gloo Mesh Enterprise looks for a service with the name extauth
in the same namespace as the Gloo Mesh Enterprise agent on each cluster where the selected workload is deployed. This destination server does not have to be in the same workspace as the external auth server configuration or external auth policies. However, you must export the destination server’s service to those workspaces.In your external auth policies, refer to the
ExtAuthServer
to use. In the example, the server configuration is referred to only by name because the policy is created in the same namespace.
Bring your own external auth server
Gloo Mesh Enterprise comes with an external auth server that implements a wide array of authentication and authorization models. However, you can deploy your own external auth server. Then, configure Gloo Mesh Enterprise to use this custom server to secure routes with external auth policies.
For example, you might create a custom external auth server to implement custom logic or to accept requests on certain routes.
The following steps demonstrate how to create a simple HTTP external auth server. Use these steps as a model to deploy your own gRPC server that implements the Envoy spec for an external authorization server.
Before you begin
This guide assumes that you use the same names for components like clusters, workspaces, and namespaces as in the getting started. If you have different names, make sure to update the sample configuration files in this guide.
Complete the multicluster getting started guide to set up the following testing environment.
- Three clusters along with environment variables for the clusters and their Kubernetes contexts.
- The Gloo
meshctl
CLI, along with other CLI tools such askubectl
andistioctl
. - The Gloo management server in the management cluster, and the Gloo agents in the workload clusters.
- Istio installed in the workload clusters.
- A simple Gloo workspace setup.
- Install Bookinfo and other sample apps.
Get the external address of your ingress gateway. The steps vary depending on the type of load balancer that backs the ingress gateway.
export INGRESS_GW_ADDRESS=$(kubectl get svc -n gloo-mesh-gateways istio-ingressgateway -o jsonpath="{.status.loadBalancer.ingress[0]['hostname','ip']}") echo $INGRESS_GW_ADDRESS
Note: Depending on your environment, you might see
<pending>
instead of an external IP address. For example, if you are testing locally in kind or minikube, or if you have insufficient permissions in your cloud platform, you can instead port-forward the service port of the ingress gateway:kubectl -n gloo-mesh-gateways port-forward deploy/istio-ingressgateway-1-20 8081
Send a request to verify that you can reach the
ratings
app without authorization. By default, Gloo allows any request on routes that do not specify authentication. Note that you are sending the request along/ratings/2
.Example output:
{"id":1,"ratings":{"Reviewer1":5,"Reviewer2":4}}
Create a simple HTTP external auth server
When a request matches a route that has an external auth policy applied, Gloo Mesh Enterprise forwards the request to an external auth service.
If that external auth service returns a 200 OK
response, Gloo Mesh Enterprise considers the request to be authorized and sends it to its original destination. If not, Gloo Mesh Enterprise denies the request.
You can fine tune settings such as sending headers or forwarding the body by configuring the ExtAuthServer
resource as shown in the previous section. Or, you can create your own external auth server to handle requests.
Implement your external auth server. For example, you might use the following Python app for a simple HTTP server. In this example, only requests to
/ratings/1
are authorized. All other requests are denied with a401
response.import http.server import socketserver class Server(http.server.SimpleHTTPRequestHandler): def do_GET(self): path = self.path print("path", path) if path.startswith("/ratings/1"): self.send_response(200, 'OK') else: self.send_response(401, 'Not authorized') self.send_header('x-server', 'pythonauth') self.end_headers() def serve_forever(port): socketserver.TCPServer(('', port), Server).serve_forever() if __name__ == "__main__": serve_forever(8000)
Verify that the namespace has Istio auto-injection enabled either through the
istio-injection=enabled
oristio.io/rev=$REVISION
label.kubectl get ns -L istio-injection,istio.io/rev --context ${REMOTE_CONTEXT1}
If not, enable auto-injection for the namespace in one of the following ways. For more information, see the Istio docs.
- If you use Istio revisions to manage Istio upgrades, label the namespace with
istio.io/rev=$REVISION
.export REVISION=$(kubectl get pod -L app=istiod -n istio-system --context $REMOTE_CONTEXT1 -o jsonpath='{.items[0].metadata.labels.istio\.io/rev}') echo $REVISION kubectl label namespace istio.io/rev=$REVISION --overwrite <namespace>
- If you do not use revisions, label the namespace with
istio-injection=enabled
.kubectl label namespace istio-injection=enabled --overwrite <namespace>
- If you do not want to enable auto-injection, manually inject the Istio sidecar after you complete the next step.
- If you use Istio revisions to manage Istio upgrades, label the namespace with
Create the a deployment for your HTTP server app. The following example uses the
gcr.io/solo-public/docs/sample-auth:latest
sample image, which is based on the HTTP server Python code in the previous step. The deployment is created in thebookinfo
namespace.kubectl apply --context $REMOTE_CONTEXT1 -f - <<EOF apiVersion: apps/v1 kind: Deployment metadata: name: sample-auth namespace: bookinfo labels: app: sample-auth spec: replicas: 1 selector: matchLabels: app: sample-auth template: metadata: labels: app: sample-auth spec: containers: - name: sample-auth image: gcr.io/solo-public/docs/sample-auth:latest imagePullPolicy: IfNotPresent ports: - containerPort: 8000 EOF
Create a service for your external auth server deployment.
kubectl apply --context $REMOTE_CONTEXT1 -f - <<EOF kind: Service apiVersion: v1 metadata: name: auth-service namespace: bookinfo labels: app: sample-auth spec: selector: app: sample-auth # Selects the external auth deployment ports: - protocol: TCP port: 80 # For HTTP traffic targetPort: 8000 # Matches the container port of the external auth deployment name: http # Include this name so that Gloo Mesh Enterprise knows that this is the HTTP port to use EOF
Verify that the external auth server is running.
kubectl get all -l app=sample-auth -n bookinfo --context $REMOTE_CONTEXT1
Optional: Depending on your setup, repeat these steps for each workspace where you want to use the external auth server.
Configure Gloo to use your custom external auth server
Now that you have an external auth server running in your cluster, configure Gloo Mesh Enterprise to use the server for authentication requests. You use an ExtAuthServer
custom resource.
Create an
ExtAuthServer
resource to configure the server.Review the following table to understand this configuration.kubectl apply --context $REMOTE_CONTEXT1 -f - <<EOF apiVersion: admin.gloo.solo.io/v2 kind: ExtAuthServer metadata: name: custom-server namespace: bookinfo labels: app: sample-auth spec: destinationServer: port: number: 8000 ref: cluster: ${CLUSTER_NAME} name: auth-service namespace: bookinfo EOF
You can also use theExtAuthServer
resource to customize certain behaviors such as request timeouts, buffering, and HTTP status codes. For more information, see the API reference.Setting Description metadata
The name and namespace for this external auth server resource. You can have only one external auth server resource per workspace. This resource does not have to be in the same namespace as the destination server. However, if this resource and the destination server are not in the same workspace, this resource’s workspace must import the destination server’s service. destinationServer
The external auth server for Gloo Mesh Enterprise to use to authentic requests with an external auth policy. If unset, Gloo Mesh Enterprise looks for a service with the name extauth
in the same namespace as the Gloo Mesh Enterprise agent on each cluster where the selected workload is deployed. This destination server does not have to be in the same workspace as the external auth server configuration or external auth policies. However, you must export the destination server’s service to those workspaces.Create an external auth policy that uses your custom auth server.
kubectl apply --context $REMOTE_CONTEXT1 -f - <<EOF apiVersion: security.policy.gloo.solo.io/v2 kind: ExtAuthPolicy metadata: name: custom-auth namespace: bookinfo labels: app: sample-auth spec: applyToRoutes: - route: labels: route: ratings config: customAuth: {} server: name: custom-server EOF
Review the following table to understand this configuration. For more information, see the API reference.
Setting Description applyToRoutes
Use labels to configure which routes to apply the policy to. This example label matches the app and route from the example route table that you apply separately. If omitted and you do not have another selector such as applyToDestinations
, the policy applies to all routes in the workspace.customAuth
Set this field to use your own custom auth server. server
The external auth server to use for the policy. Send a request to the
ratings
app along the/ratings/2
path. Now, your request is denied because the external auth server allows requests only along the/ratings/1
path.curl -vik --resolve www.example.com:80:${INGRESS_GW_IP} http://www.example.com:80/ratings/2
Repeat the previous request along the
/ratings/1
path.curl -vik --resolve www.example.com:80:${INGRESS_GW_IP} http://www.example.com:80/ratings/1
The request succeeds:
{"id":1,"ratings":{"Reviewer1":5,"Reviewer2":4}}
Cleanup
You can optionally remove the resources that you set up as part of this guide.
kubectl delete deploy,svc,extauthserver,extauthpolicy -n bookinfo -l app=sample-auth --context $REMOTE_CONTEXT1