kubeauth is a experimental simple authentication backend for kubernetes. It is written in rust and uses the rocket framework. It is designed to be used in conjunction with the kubeapi server using webhook token authentication.
kubeauth is a simple http server. It listens on port 8000 by default. It has basically one endpoint. The endpoint token is used to authenticate a user using a Webhook Token Review Request send from the kubeapi server.
The user that has to be authenticated has a configured token. The token is send to the kubeapi server.
Example kubeconfig:
- name: kubernetes-webhook
user:
#Token
token: "alice:alicepassword"
The client sends the token in his request to the kubeapi server.
Then the kubeapi server will send a Webhook Token Review Request to kubeauth to check if the token is valid. Kubeauth will then check if the token is valid and if the user is allowed to authenticate. If the token is valid and the user is allowed to authenticate, kubeauth will send a Webhook Token Review Response back to the kubeapi server. The kubeapi server will then authenticate the user.
kubeauth supports the following authentication methods: * Json file (see contrib/users.json)
Currently there is planned support for the following authentication methods: * LDAP * Active Directory * Github OAuth
But feel free to contribute. This is an open source project and has been created originally for my bachelor thesis. So i dont have the time to implement all the features i want to implement. But i will try to implement as much as possible.
Yet, authentication methods can be added easily. You just have to implement the trait Authenticator and add the new authenticator to the Authenticator::auth function.
Authenticators are located in the src/authenticators directory.
Authenticators are loaded dynamically. So you dont have to recompile kubeauth to add a new authenticator you want to use. But the authenticator implementation has to be compiled.
The authentication method is set using arguments. You can set the authentication method using the -a argument. The argument takes a string as value. The string is the name of the authenticator. The authenticator has to be located in the src/authenticators directory.
Example:
kubeauth -a json_auth -a ldap_auth will load the jsonauth and ldapauth authenticators.
Currently kubeauth supports the following authentication methods: * Json file (see contrib/users.json) see src/authenticators/READMEjson.md * LDAP (Experimental) see src/authenticators/READMEldap.md
Each authentication method has environment variables associated with it. The environment variables are used to configure the authentication method. For names of the environment variables see the README.md of the authentication method.
There are a few options to install kubeauth. The current working method is installing kubeauth as standalone binary and let kubespray set all the necessary configuration. The other option is to install kubeauth as a kubernetes deployment. This is not yet fully tested and documented.
And i honestly dont know if its a good idea to install kubeauth as a kubernetes deployment since it is used as authentication backend for kubernetes. So if kubeauth is down, you cant authenticate to kubernetes anymore.
But im open for suggestions and pull requests.
cargo build --release will build the binary in the target/release directory. Copy the binary to a location of your choice and make sure it is in your PATH.
There is a systemd service file in the contrib directory. Copy it to /etc/systemd/system and adapt the path to the kubeauth binary. Then run systemctl enable kubeauth and systemctl start kubeauth.
This is not yet fully tested and documented. But the idea is to install kubeauth as a kubernetes deployment. There is a kubernetes deployment file in the contrib directory. Copy it to a location of your choice and adapt the path to the kubeauth binary. Then run kubectl apply -f kubeauth-deployment.yaml.
This is not yet fully tested and documented. But the idea is to install kubeauth as a docker container. There is a dockerfile in the contrib directory. Copy it to a location of your choice and adapt the path to the kubeauth binary. Then run docker build -f contrib/Dockerfile -t kubeauth . and docker run -d --name kubeauth kubeauth.
Currently i honestly didnt fully understand how to configure the cluster to use kubeauth. But i found kubespray to help me with that. So i used kubespray to configure the cluster. I will try to explain how i did it.
Follow the instructions on the kubespray github page to install kubespray. I used the master branch.
The magic lies behind group_vars/all/all.yml. There are a few options to configure the cluster. I will try to explain the most important ones.
You need to edit:
kube_webhook_token_auth: true
kube_webhook_token_auth_url_skip_tls_verify: true
kube_webhook_token_auth_url: https://yourhost:8000/token
Kubespray will then do the magic and configure the cluster to use kubeauth.
I had to set kube_webhook_token_auth_url_skip_tls_verify: true because i didnt have a valid certificate for my kubeauth server. You may want to change this to false and use a valid certificate.
The certificate is set in Rocket.toml. You can change the path to the certificate in Rocket.toml.
Kubeauth doesnt have to run on the same host as the kubeapi server. You can run kubeauth on any host you want. You just have to make sure that the kubeapi server can reach the kubeauth server.
Also, when kubeauth doesnt run, the kubeapi will still work because authentification plugins are chained in kubernetes. So if kubeauth is down, the next authentification plugin will be used. For example the x509 authentification plugin using certificates.
sudo apt-get install libsasl2-dev libldap2-dev libssl-dev
I am not a rust expert. So there may be some bad code in this project. Feel free to contribute and improve the code. I will try to improve the code as much as possible and im open for suggestions and pull requests.
This project is licensed under the GPL-3.0 License - see the license.md file for details