1. Home

Documentation

Installation

The installation of KubeAuth.io is very straight forward. There are not many steps to install KubeAuth.io on your personal Kubernetes.

Prerequisites

KubeAuth.io assumes you have a running Kubernetes, it does not matter if it is a cluster or a Minikube. The following prerequisites are needed for your environment:

  • Kubernetes, Version >= 1.16.0
  • In Kubernetes the MutatingAdmissionWebhook as an admission controller
  • For the installation admin rights are needed
  • Helm

HELM install

Add our Helm Repo. Credentials are not needed, it is free to use.

helm repo add yotron-helm-charts http://helm.yotron.de

Download und UnTar the repo from our Helm Repository.

helm pull yotron-helm-charts/kubernetes-authentication --untar

Now, you find the folder kubernetes-authentication with the Helm Package. Now you can change the configuration according to your needs. Most changes must be done in the setup of the proxy with the authentication. This is done in file proxy-configs.yml.

The installation of KubeAuth.io is done with:

helm install kubeauth ./kubernetes-authentication

Installation of the Demo

If you want to integrate the demo of KubeAuth.io with our identity provider, you can install the package in with

helm repo add yotron-helm-charts http://helm.yotron.de

and

helm install kubeauth yotron-helm-charts/kubernetes-authentication

No you can use our demo environment

Validation

KubeAuth.io is installed into the namespace kubeauth-system of Kubernetes. The following pods are installed and must have the status Running.

$ kubectl get pods -n kubeauth-system
NAME                                   READY   STATUS    RESTARTS   AGE
kubeauth-controller-5b547b859d-cv529   1/1     Running   0          2m19s
kubeauth-server-5868dd469d-hp9pj       1/1     Running   0          2m19s

Uninstall

You can remove the package with:

helm uninstall kubeauth

Activation in your Deployment

To activate KubeAuth.io for your individual Kubernetes Pod you need to label the Pods properly in their manifests.

Labels

kubeauthUniqueName (mandatory): The unique name of the Proxy. The name can be chosen freely but must reflect the prerequisites for Object Names of Kubernetes

kubeauthConfig (mandatory): The name of the Proxy settings which shall be used for the Reverse Proxy.

kubeauthInit (optional, [“true” or “false”], default “false”): You must activate KubeAuth.io for a Pod. Default KubeAuth.io will not set the Reverse Proxy of a Pod. Set it to ’true’ if you want to activate KubeAuth.io.

kubeauthService (optional, [“LoadBalancer”, “NodePort”, “ClusterIP”]): KubeAuth.io adds a Kubernetes service which is mapped onto the Reverse Proxy. You just have to choose which kind of Kubernetes service you want. If you do not want a service, just leave out or leave it empty.

kubeauthLogLevel (optional, [“TRACE”, “DEBUG”, “INFO”, “WARNING”, “ERROR”, “FATAL” and “PANIC”], default “INFO”): Setup the log level for the Proxy. The logs can get with the ordinary Kubernetes tools (kubectl logs ...)

Example

Here is an example how set up a manifest for a Kubernetes Pod with all proper Labels (based from our Demo):

apiVersion: apps/v1
kind: Deployment
metadata:
  name: webapp
spec:
  replicas: 1
  selector:
    matchLabels:
      kubeauthUniqueName: kubeauth-test
  template:
    metadata:
      labels:
        kubeauthUniqueName: kubeauth-test
        kubeauthInit: true
        kubeauthConfig: AWSCognito
        kubeauthLogLevel: DEBUG
        kubeauthService: LoadBalancer
    spec:
      containers:
      - name: webapp
        image: yotronpublic/proxytest:1.1.0
        imagePullPolicy: Always
        ports:
        - containerPort: 8080
        - containerPort: 8081

Configuration

You are able to set up your Reverse Proxy in a very detailed way. We provide a lot of defaults which is working for most of your scenarios.

All configs are done in the file proxy-configs.yml which you find in the root folder of the Helm package. In the default file in the package you find examples of configurations, based on our Demo.

This file contains, the settings for the authentication of a request as well as the settings for the requesting like timeout setting.

You can add as much Proxy Configurations as you like, e.g. for different purposes tenants or environment (prod, test, …).

An example of a complete setup of a proxy can be found here Download

Parameter: active

active (mandatory, [“true” or “false”]): To activate a proxy settings this flag must be set to “true”. If you want to deactivate a setting, then set it to “false”. Then it cannot be used during the bringup of a Kubernetes Pod.

Parameter for Authentication

There are two possibilities of authentication checking, we call it online if the Authentication validation shall be done by the identity provider (Keycloak, AWS-Cognito, …) and offline When the check is done without a connection to the identity provider.

Pro online:

  • Actively revoked token are handled as failed.
  • Is usable independently from the Encryption Types like RSA, EC, …

Pro offline:

  • The requests to check the tokens can be a lot. Less load on your identity provider.
  • No network connection needed
  • Faster

You have to set up one of the both possibilities. If you set up both, offline will be used.

Online authentication

For the online validation, KubeAuth.io needs a URL to check if the authorization token is valid. This can be every URl to the identity provider which needs an authentication. OpenID Connect or OAuth2 always provide an USERINFO-API to get the user data stored in the identity provider. We recommend using this API. As an example the userinfo Api of AWS-Cognito has the URL https:///oauth2/userInfo.

authUrl The complete URL to the identity provider, like https://auth.kubeauth.io/oauth2/userInfo

Offline authentication

When you want to use the offline check, KubeAuth.io provides different checks, reflecting the requirements of the different identity provider and encryption types (kty). For example mostly RSA (Rivest–Shamir–Adleman) is used as the key encryption type (kty). RSA expects an encoded public key for the validation of a token. If you are using ECDSA (Elliptic Curve Digital Signature Algorithm) a simple “password” is sufficient.

All information are provided by the identity provider (Keycloak, Okta, AWS-Cognito, …) you are using.

Please be aware that the key (PEM or “Password”) must be added base64 encoded.

PEM vs. JWK Sets

KubeAuth.io is providing two ways to define an RSA Public Key:

  • PEM encoded Certificate
  • JSON Web Key Sets (JWK Sets) for Public Keys (JWK)

Settings

These settings are used when your identity provider provides a PEM encoded Public Key. You can have more than one Key for validation. They are all separated by a “key id”.

kid (mandatory): The Key Identifier of the Key or Password the identity provider is using.

kty (mandatory, [“RSA”, “HMAC”, “ECDSA”, “EDDSA”]): The encryption type of the key. Most tokens are RSA encrypted.

The following settings are needed if your identity provider is providing a PEM-File or a “Password”:

key (optional): The PEM formatted certificate or the “Password” of the key. Both must be added Base64 encoded.

The following settings are needed if your identity provider is providing JWK Sets:

alg (mandatory): The algorithm of the RSA encryption, like RS256, HS256,

e (mandatory, [“AQAB”, “AAEAAQ”]): The public exponent of the key, like AQAB or AAEAAQ.

n (mandatory): The modulus of the key.

use (mandatory): Public Key Use. Most of the keys are used for signature (sig)

Examples

Some entries are shortened for the readability.

Online authentication

- kid: kGSxpEoT0jr1dUbgKr7OAUPJB-mbT65DoIwiErjktcw
  kty: RSA
  key: LS0tLS1CRUdJTiBDRVJUSUZJQ0FURS0tLS0tCk1JSUJJakFOQmdr ... BUUFCCi0tLS0tRU5EIENFUlRJRklDQVRFLS0tLS0=

Offline authentication

- kid: /599i4T4UPFbC0pEuMXBEs88CjnTq5GWxB+TKk7hCYk=
  alg: RS256
  e: AQAB
  kty: RSA
  n: yuLQaBl5EYnn__bKDMQviUSG ... xBoss5N_1K_WHeS-dmxljzXLqH2XgDzmEfxtpQ
  use: sig

Parameter for the Reverse Proxy

For the Reverse Proxy you have the follwoing settings.

  • TLS for the communication via https. KubeAuth.io is providing a default setup for the SSL-Key and Certs, but you are able to add an own Key and Cert.
  • Listener Ports
  • Default Kubernetes Services to allow the communication with the Reverse Proxy for all pods using this setting.
  • Timeout settings for Request reachin the Proxy and Request forwarded to the Application.

Settings for https

tls (optional, [“true”, “false], default “false”): If you want to use TLS (HTTPS), set this to true.

tlsKey (optional): The Base64 encoded certificate of the TLS.

tlsCrt (optional): The Base64 encoded key of the TLS.

Ports and Kubernetes Service

appListenerPort (optional, default 8080): The port your application server is listening on.

proxyListenersPort (optional, default with TLS: 7443, without: 8080): The port the Reverse Proxy is listening on.

proxyServiceType (optional, [LoadBalancer”, “NodePort”, “ClusterIP”]): When you want to get an additional Kubernetes Service for the Reverse Proxy, please define the type of Kubernetes Service.

Request timeouts

Settings for the Server

These settings are usable for all requests the Reverse Proxy is reaching.

idleTimeoutSeconds (optional, default 10): The maximum amount of time in seconds to wait for the next request when keep-alives are enabled.

readTimeoutSeconds (optional, default no timeout): The maximum amount of time allowed to read the complete Request (Header and Body).

Example:

proxyRevServerConfig:
  idleTimeoutSeconds: 50
  readTimeoutSeconds: 5

Outgoing

These settings are usable for all outgoing requests from the Reverse Proxy to your application.

disableKeepAlives (optional, [“true”, “false”], default false): All sessions are stopped after finishing.

maxIdleConns (optional, default 100): Maximum number of idled connections when keep-alive is active. Zero means no limit.

maxIdleConnsPerHost (optional, default 100): Maximum number of idled connections per host when keep-alive is active. Zero means no limit.

maxConnsPerHost (optional, default no limit): Maximum amount of connections allowed per Host. Zero means no limit.

idleConnTimeoutSeconds (optional, default 90): The time in seconds that idled connections are closed. Zero means no timeout.

Example:

proxyRevRequestConfig:
  disableKeepAlives: false
  maxIdleConns: 10
  idleConnTimeoutSeconds: 40
  expectContinueTimeoutSeconds: 20
  maxIdleConnsPerHost: 3
  maxConnsPerHost: 3