Navigation :

External auth server setup

Set up the default or customize your own external auth server.

This feature is available with a Gloo Gateway license only.

To enforce external authentication policies, your Gloo environment must have an external auth server. Choose from the following options.

Set up the Gloo Gateway external auth server.
Bring your own external auth server.

Set up the Gloo Gateway external auth server

To enforce external auth policies across your Gloo environment, each Gloo 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. Gloo Gateway automatically creates a deployment and service of an external auth server. The example steps set up a separate gloo-mesh-addons namespace to run the external auth server. Use this namespace to refer to your server in the ExtAuthServer resource.

Create an ExtAuthServer resource for your workspace. This resource points to the destination server to use for external auth policies. The destination server can be the default ext-auth-service from Gloo Gateway, or your own custom server.

kubectl apply -f - <<EOF
apiVersion: admin.gloo.solo.io/v2
kind: ExtAuthServer
metadata:
  annotations:
    cluster.solo.io/cluster: ""
  name: default-server
  namespace: bookinfo
spec:
  destinationServer:
    port:
      number: 8083
    ref:
      cluster: cluster-1
      name: ext-auth-service
      namespace: gloo-mesh-addons
EOF

Review the following table to understand this configuration.

You can also use the ExtAuthServer 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, but should be in the same workspace.
`destinationServer`	The external auth server for Gloo Gateway to use to authentic requests with an external auth policy. If unset, Gloo Gateway looks for a service with the name `extauth` in the same namespace as the Gloo Gateway agent on each cluster where the selected workload is deployed. The destination server, external auth server, and external auth policies should be in the same workspace.

In your external auth policies, refer to the ExtAuthServer to use. In the highlighted example, the server configuration is referred to only by name because the policy is created in the same namespace.

 
kubectl apply -f - <<EOF
apiVersion: security.policy.gloo.solo.io/v2
kind: ExtAuthPolicy
metadata:
  annotations:
    cluster.solo.io/cluster: ""
  name: basic-auth
  namespace: bookinfo
spec:
  applyToRoutes:
  - {}
  - route:
      labels:
        route: ratings
  config:
    glooAuth:
      configs:
      - basicAuth:
          apr:
            users:
              user:
                hashedPassword: 8BvzLUO9IfGPGGsPnAgSu1
                salt: TYiryv0/
    server:
      name: default-server
EOF

Bring your own external auth server

Gloo Gateway 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 Gateway 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

Complete the Getting started guide to install Gloo Gateway and sample apps in your cluster.
Send a request to verify that you can reach the ratings app without authorization. By default, Gloo Gateway allows any request on routes that do not specify authentication. Note that you are sending the request along /ratings/2.
- HTTP
- HTTPS
```
curl -vik --resolve www.example.com:80:${INGRESS_GW_IP} http://www.example.com:80/ratings/2
```
```
curl -vik --resolve www.example.com:443:${INGRESS_GW_IP} https://www.example.com:443/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 Gateway forwards the request to an external auth service.

If that external auth service returns a 200 OK response, Gloo Gateway considers the request to be authorized and sends it to its original destination. If not, Gloo Gateway 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 a 401 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)

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 the bookinfo namespace.

kubectl apply -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 -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 Gateway 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

Depending on your setup, repeat this step for each workspace where you want to use the external auth server.

Configure Gloo Gateway to use your custom external auth server

Now that you have an external auth server running in your cluster, configure Gloo Gateway to use the server for authentication requests. You use an ExtAuthServer custom resource.

Create an ExtAuthServer resource to configure the server.

kubectl apply -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:
      name: auth-service
      namespace: bookinfo
EOF

Review the following table to understand this configuration.

You can also use the ExtAuthServer 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, but should be in the same workspace.
`destinationServer`	The external auth server for Gloo Gateway to use to authentic requests with an external auth policy. If unset, Gloo Gateway looks for a service with the name `extauth` in the same namespace as the Gloo Gateway agent on each cluster where the selected workload is deployed. The destination server, external auth server, and external auth policies should be in the same workspace.

Create an external auth policy that uses your custom auth server.

kubectl apply -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.
- HTTP
- HTTPS
```
curl -vik --resolve www.example.com:80:${INGRESS_GW_IP} http://www.example.com:80/ratings/2
```
```
curl -vik --resolve www.example.com:443:${INGRESS_GW_IP} https://www.example.com:443/ratings/2
```

Repeat the previous request along the /ratings/1 path.

HTTP
HTTPS

curl -vik --resolve www.example.com:80:${INGRESS_GW_IP} http://www.example.com:80/ratings/1

curl -vik --resolve www.example.com:443:${INGRESS_GW_IP} https://www.example.com:443/ratings/1

The request succeeds:

{"id":1,"ratings":{"Reviewer1":5,"Reviewer2":4}}

Optional: Clean up the resources that you created with the following command.

kubectl delete deploy,svc,extauthserver,extauthpolicy -n bookinfo -l app=sample-auth