heimdallr

[日本語]

Currently under development

Zero trust proxy for using in corporate.

Features

• Reverse proxy with identity-aware
• Can proxy the traffic not only HTTP but also SSH or something like
• Beyond NAT on each side of the proxy
• Manage an user by Browser
• Managing an user authority by RBAC
• Easy to deploy to Kubernetes

Configuration

The configuration files divide two parts.

The first part is for the daemon. The second part is for RBAC.

For Daemon

You can control a behavior of the proxy.

Upstream

Sample file of the configuration of the upstream

RBAC

You will define the role and the permission of RPC.

The role is a set of the upstream and ACL. The permission of RPC is a set of ACL.

Deployment

heimdallr is designed to deploying to a kubernetes by the operator. You also can deploying by yourself. but we highly recommend to using the operator.

Depend on

• cert-manager

When start up the operator, check to exist some CRDs. If not found all CRDs then the operator not start.

Optional

• prometheus-operator

How to deploy on k8s

This section describes how to deploy on k8s.

We've designed this software to deploy to k8s. Deploying to baremetal, VM or something like that is more complexity than deploying to k8s by the operator.

We've highly recommend to deploying to k8s by the operator.

1. Deploy cert-manager
2. Deploy the operator
3. Create Secret resource which contains the client secret
4. Create Proxy resource

Deploy cert-manager

You're following official guide .

Deploy the operator

We provide the manifest for the operator.

$ kubectl create namespace heimdallr
$ kubectl apply -f https://github.com/f110/heimdallr/releases/download/v0.9.0/all-in-one.yaml

Create Secret resource

You have to create Secret which contains the client secret before create Proxy resource.

$ kubectl -n heimdallr create secret generic client-secret --from-file=client-secret

Create Proxy resource

The operator automatically creates a related resources after you create Proxy resource.

apiVersion: proxy.f110.dev/v1
kind: Proxy
metadata:
  name: test
  namespace: heimdallr
spec:
  replicas: 3
  version: v0.9.0
  domain: x.f110.dev
  port: 443
  backendSelector:
    matchLabels:
      instance: test
  roleSelector:
    matchLabels:
      instance: test
  issuerRef:
    name: lets-encrypt
    kind: ClusterIssuer
  identityProvider:
    provider: google
    clientId: [your oauth client id]
    clientSecretRef:
      name: client-secret
      key: client_secret
    redirectUrl: [The callback url you configured]
  rootUsers:
    - [Your email address]
  session:
    type: secure_cookie
    keySecretRef:
      name: cookie-secret

Ingress support

The operator also supports Ingress and IngressClass. But very limited support yet.

The operator will not create IngressClass automatically. If you want to integrate with Ingress, you have to create IngressClass by hand.

apiVersion: networking.k8s.io/v1
kind: IngressClass
metadata:
  name: heimdallr
  labels:
    instance: proxy-sample
spec:
  controller: heimdallr.f110.dev/ingress-controller

.spec.controller is constant value. Only accepts heimdallr.f110.dev/ingress-controller.

And .metadata.labels is a mandatory value. Because it will be inherited to Backend.

Build & Run

First of all, install latest Bazel

Generate some secret keys and certificates for development.

$ bazel run //cmd/heimctl -- bootstrap -c $(pwd)/config_debug.yaml

config_debug.yaml is configuration for development. DO NOT USE THIS FILE IN PRODUCTION WITHOUT CHANGES.

And you need to create a credential file that is Client Secret. How to get a client secret is depend on an IdP.

After running bootstrap command, build and run.

$ make run

All dependent libraries are included in the repository.

Connector

The connector is a sidecar of upstream server which behinds NAT.

Traffic can be proxied through the agent even if it cannot be connect to the upstream server due to NAT.

How to run

The agent is a client program that beside a backend like a sidecar. the agent will connect to the proxy and relay ingress traffic of proxy. Thus it can be proxying to the backend that likes behind NAT.

The agent is designed to run the same host with the backend. And the agent is also designed for 1:1 corresponding between the agent and the server.

1. Decide the backend's name with your proxy admin
2. Generate CSR(Certificate Signing Request) and private key by heim-connector
3. Send CSR to the proxy admin
4. You got signed certificate from the proxy admin
5. Run heim-connector with signed certificate

DO NOT move the private key to outside of the agent server for any reason.

Generate CSR

Generating CSR by heim-connector. CSR includes the backend's name. so you have to pass it by an argument.

$ heim-connector --name test --privatekey $HOME/.heimdallr/privatekey.pem

heim-connector will create a CSR in temporary directory.

Start heim-connector with signed certificate

$ heim-connector --host your.proxy.f110.dev \
    --name test \
    --privatekey $HOME/.heimdallr/privatekey.pem \
    --backend 127.0.0.1:22 \
    --certificate $HOME/.heimdallr/cert.pem \
    --ca-cert $HOME/.heimdallr/cacert.pem

Reference

BeyondCorp by Google.

• BeyondCorp: A New Approach to Enterprise Security
• BeyondCorp: Design to Deployment at Google
• BeyondCorp: The Access Proxy
• Migrating to BeyondCorp: Maintainig Productivity While Improving Security
• BeyondCorp: The User Experience
• BeyondCorp 6: Building a Health Fleet

LICENSE

MIT

Author

Fumihiro Ito <fmhrit@gmail.com>