{"id":17961012,"url":"https://github.com/slok/bilrost","last_synced_at":"2025-03-25T03:31:30.186Z","repository":{"id":45024912,"uuid":"254601255","full_name":"slok/bilrost","owner":"slok","description":"Kubernetes controller/operator to set up OAUTH2/OIDC security on any ingress based service","archived":false,"fork":false,"pushed_at":"2022-01-13T16:46:13.000Z","size":435,"stargazers_count":18,"open_issues_count":1,"forks_count":3,"subscribers_count":2,"default_branch":"master","last_synced_at":"2025-03-19T08:39:29.944Z","etag":null,"topics":["controller","ingress","k8s","kubernetes","oauth2","oidc","operator","proxy","security"],"latest_commit_sha":null,"homepage":"","language":"Go","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"apache-2.0","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/slok.png","metadata":{"files":{"readme":"README.md","changelog":"CHANGELOG.md","contributing":null,"funding":null,"license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":".github/CODEOWNERS","security":null,"support":null}},"created_at":"2020-04-10T09:56:19.000Z","updated_at":"2023-01-11T02:37:16.000Z","dependencies_parsed_at":"2022-09-24T21:30:55.832Z","dependency_job_id":null,"html_url":"https://github.com/slok/bilrost","commit_stats":null,"previous_names":[],"tags_count":2,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/slok%2Fbilrost","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/slok%2Fbilrost/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/slok%2Fbilrost/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/slok%2Fbilrost/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/slok","download_url":"https://codeload.github.com/slok/bilrost/tar.gz/refs/heads/master","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":245394751,"owners_count":20608122,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2022-07-04T15:15:14.044Z","host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["controller","ingress","k8s","kubernetes","oauth2","oidc","operator","proxy","security"],"created_at":"2024-10-29T11:08:03.185Z","updated_at":"2025-03-25T03:31:30.175Z","avatar_url":"https://github.com/slok.png","language":"Go","funding_links":[],"categories":[],"sub_categories":[],"readme":"\u003cp align=\"center\"\u003e\n    \u003cimg src=\"docs/img/logo.png\" width=\"30%\" align=\"center\" alt=\"bilrost\"\u003e\n\u003c/p\u003e\n\n# Bilrost [![Build Status][ci-image]][ci-url] [![Go Report Card][goreport-image]][goreport-url]\n\nSetting OAUTH2/OIDC in Kubernetes running apps should be easy, Bilrost solves this and removes the pain.\n\nBilrost is a kubernetes controller/operator to set up OAUTH2/OIDC on any ingress based service. It doesn't care  what ingress controller do you use, it supports multiple auth backends and multiple OAUTH2/OIDC proxies.\n\nBilrost will register/create OAUTH2/OIDC clients, create secrets, setup proxies, rollback if required...\n\nIn a few words, it automates the ugly work of setting the OAUTH2/OIDC security in your applications.\n\n## Table of contents\n\n- [Features](#features)\n- [How does it work](#how-does-it-work)\n- [Getting started](#getting-started)\n- [Advanced examples](#advanced-examples)\n- [Supported auth backends](#supported-auth-backends)\n- [Supported OAUTH2 OIDC proxies](#supported-oauth2-oidc-proxies)\n- [F.A.Q](#faq)\n\n## Features\n\n- Secure any external (ingress) service independent of the ingress controller.\n- Can rollback security to the original state.\n- Heals automatically (controller pattern/feedback loop).\n- Support multiple auth backends implementations (easy to add new ones).\n- Supports multiple proxy implementations (easy to add new ones).\n- Two modes of securing ingresses/app `simple` and `advanced`.\n- Prometheus metrics ready.\n- Have infinite different auth backends, e.g:\n  - Dex with Github for developers ingresses.\n  - Dex with Google for company internal backend ingresses.\n  - Dex with other Google accounts to allow access to poeple outside the company internal backends.\n- Automatic registering OIDC clients on auth backends.\n- Automatically create OAUTH2/OIDC client secrets (no need to be manipulating secrets).\n- Setup safe settings on proxies.\n- Splits responsibility about the auth backends and application security.\n\n## How does it work\n\nBilrost needs 2 things:\n\n- The `AuthBackend` is a cluster scoped CRD that has the data to be able to interact with the auth backend system of your election, for example [Dex].\n- The public application to be secured, this can be achieved in 2 ways:\n  - First select the ingress to be secured by adding an annotation that points to the auth backend that will act as the auth entity.\n  - As an optional step, along with the ingress annotatiton you can set advanced settings for the proxy using a CR called `IngressAuth`, this has the same name and namespace as the ingress.\n\nAfter this Bilrost is ready to start the setup of a secure OAUTH2/OIDC application like this:\n\n![kubernetes-architecture](docs/img/k8s-architecture.png)\n\nAs you see in the high level architecture graph, before Bilrost you have the regular setup of ingress-\u003eservice-\u003epods. After securing with Bilrost, it will set up a proxy in a kind of [MitM][mitm] style, so every request that forwards from the ingress to the service, will need to go through the OAUTH2/OIDC proxy that has been configured and registered with an auth backend, so the OAUTH2/OIDC flow is triggered. This is how eliminates the need of a specific ingress controller and is compatible with any setup.\n\n## Getting started\n\nThe requirements are:\n\n- A running and working Dex.\n- The Auth backend CRD registered (apply the [CRD]s).\n- A running Bilrost (check [this][bilrost-deployment] as an example).\n- An ingress that points to a running application (service, pods...).\n\nThis is an example, you will need to change the settings accordingly.\n\nFirst you need to register the dex as an auth backend for bilrost, using a cluster scoped CR, this example is for a backend on a Dex in `https://dex.my.cluster.slok.dev` public URL and running in `auth` namespace `dex` service:\n\n```yaml\napiVersion: auth.bilrost.slok.dev/v1\nkind: AuthBackend\nmetadata:\n  name: my-dex\nspec:\n  dex:\n    publicURL: https://dex.my.cluster.slok.dev\n    apiAddress: dex.auth.svc.cluster.local:81\n```\n\nNow you need to select this backend, to do this you will need to use the bilrost backed ingress annotation `auth.bilrost.slok.dev/backend` (**The annotation is mandatory**). and let the magic happen (this example is for an app available at `https://app.my.cluster.slok.dev` and a service `app`, namespace `app`):\n\n```yaml\napiVersion: extensions/v1beta1\nkind: Ingress\nmetadata:\n  name: app\n  namespace: app\n  annotations:\n    auth.bilrost.slok.dev/backend: my-dex\nspec:\n  rules:\n    - host: app.my.cluster.slok.dev\n      http:\n        paths:\n          - backend:\n              serviceName: app\n              servicePort: 80\n            path: /\n```\n\nIn case you want (**The CR is optional**) to set advanced settings to secure the app instead of the defaults you can use a CRD that should live in the same namespace of the ingress and the same name. e.g\n\n```yaml\napiVersion: auth.bilrost.slok.dev/v1\nkind: IngressAuth\nmetadata:\n  name: app\n  namespace: app\nspec:\n  authSettings:\n    scopeOrClaims: [\"email\", \"profile\", \"groups\", \"offline_access\"]\n  oauth2Proxy:\n    image: \"quay.io/oauth2-proxy/oauth2-proxy:latest\"\n    replicas: 4\n    resources:\n      requests:\n        memory: \"64Mi\"\n        cpu: \"250m\"\n      limits:\n        memory: \"128Mi\"\n        cpu: \"500m\"\n```\n\n## Advanced examples\n\nFor more advanced examples check [examples] dir, be aware of the `CHANGE_ME` prefix on the lines that you will need to change/pay attention.\n\n## Supported auth backends\n\n- [Dex]: Will set the applicaiton ready to be used in a Dex instance by:\n  - Creating a new Client secret.\n  - Storing this secret internally.\n  - Register the app with a client ID and the generated client secret using the Dex API.\n\n## Supported OAUTH2 OIDC proxies\n\n- [oauth2-proxy]: Will set up an oauth2-proxy by:\n  - Create a Service for the proxy.\n  - Create a Kubernetes secret with the OIDC client information (already ready on the auth backend).\n  - Setup a deployment with the proxy configured to use the auth backend and the original app service as the upstream.\n  - Store a backup of the app's ingress original data.\n  - Update the app ingress to forward the traffic to the proxy.\n\n## F.A.Q\n\n### Do I need bilrost?\n\nDepends, if you already have a way of securing public services with OAUTH2/OIDC in an automated way, I would say that you don't need Bilrost.\n\nFor example If you already use [nginx-controller] with `auth-url` and  `auth-signin` annotations ([more info here][nginx-oauth2]) you probably don't need Bilrost.\n\nBut if you use [Skipper], [Traefik] or any other ingress controller, you can use Bilrost to setup fast and easy OAUTH2/OIDC on public services.\n\n\n### How can I deploy Bilrost?\n\nCheck [deployment example][bilrost-deployment].\n\nYou have docker images ready in the [container image repository][docker-repository]\n\n```bash\ndocker pull slok/bilrost\n```\n\n### Where are the CRDs?\n\nYou can register Bilrost CRDs with [these][CRD] manifests.\n\n### How I manage the secrets of OAUTH2/OIDC clients?\n\nYou don't, Bilrost manages them, it generates random secrets, stores them on kubernetes, sets up on the proxies and registers them on the auth backends.\n\n### Can I rotate OAUTH2/OIDC client secrets?\n\nDepends on the auth backend used. Here are the ways in the different auth backends:\n\n#### Dex\n\nBilrost stores the autogenerated client secrets on its running namespace.\n\nYou can get all of them with:\n\n```bash\nkubectl -n {BILROST_NS} get secrets -l app.kubernetes.io/component=dex-client-data\n```\n\nIf you delete those secrets, on the next resync interval, Bilrost will generate new secrets and setup everything again.\n\n### Why `ClusterRoleBinding`?\n\nYou only need one bilrost per cluster, this Bilrost instance needs to manage deployments, secrets, ingresses... outside its namespace, this means that needs to access at a cluster scope level.\n\nIf you are concerned about this cluster wide security you can use multiple role bindings, one `ClusterRoleBinding` for cluster scope resources (`AuthBackends`) and multiple `RoleBinding` for each namespace you want Bilrost to access the namespaced resources (`Secrets`, `Ingresses`, `IngressAuths`, `Deployments`).\n\n### Can I rollback a secured application?\n\nYes, Bilrost will detect that the ingress is no longer require to be secured and will trigger a rollback process to let the ingress as it was. This can be triggerend in different ways:\n\n- Deleting the ingress annotation.\n- Deleting the ingress.\n\n### What triggers a reconciliation loop?\n\n- At regular intervals all ingresses (`5m` by default, use `--resync-interval` flag for custom interval).\n- Updates on `Ingress` core resources.\n- Updates on `IngressAuth` custom resources (CR).\n\n### I'm not happy with the default proxy settings\n\nIt's ok, use the `IngressAuth` CR in case you want special settings for the proxy, like number of replicas or custom resources.\n\nThe ingress annotation method without CR is a fast and simple way of enabling and disabling security, make tests and enable security in a temporary way.\n\n### If I use the CR, do I need to use the ingress annotation?\n\nYes, at the begginning we though of use the annotation or the CR to enable, but that opens corner cases and adds internal complexity, that translates in bugs.\n\nMaking the annotation a requirement also has good side effects, like:\n\nOnly have a single way of enabling/disabling bilrost security on an ingress, the annotation. If not this could mean that sometimes you would enable this with an annotation and others wiht the CR and we don't like making the same thing in different ways.\n\nAlso, although you can have the CR present, with the annotation you can enable and disable the security in a fast way without the need of deleting resources.\n\n### Do we have Bilrost metrics?\n\nYes, we support [Prometheus] metrics, by default metrics will be served in `0.0.0.0:8081/metrics`.\n\n### Do you support https `Service`s?\n\nNo at this moment, this will come with an available setting in the `IngressAuth` CR. By default and without advanced options will be http.\n\n### In what state is this controller?\n\nThe controller is very new, but is stable enough, although we are sure that lacks of some functionality or has bugs.\n\nIf you are using it a medium-big scale please let us know how is working in case we need to optimize or fix parts of the controller.\n\n### Is this another ingress controller?\n\nYes and no, is an ingress controller, but only sets up OAUTH2/OIDC security, it has small responsibility, so in other words no as a full ingress controller, this will not replace Nginx, Skipper, Traefik...\n\n### How about having multiple Bilrost instances?\n\nAlthough is not required because of its async nature and you could configure the number of workers to run, should be safe to have multiple instances, and in case of sharding you could have instances per namespace if you want.\n\n### Why running a proxy server instead using the ingress controller servers?\n\nWell, this is the way of not requiring any particular ingress setup. Nevertheless we plan to support ingress-controller based annotations, so users have the option of removing the proxy instances.\n\nFor now, this proxy approach makes easy to abstract the architecture in place and setup easy OAUTH2/OIDC security.\n\n### Are you planning to support more auth backends and proxies?\n\nYes.\n\nIn the short term we are planning Auth0 `AuthBackend` as an alternative to Dex.\n\nRegarding auth proxies we are planning what would it take to support ingress controller based annotations like [nginx-controller] annotation, this would remove the burden, resources and PoFs of related with the auth proxy instances.\n\nAnyway, if you want support for other kinds of auth backends and/or proxies, please open an Issue, that would be awesome.\n\n\n### What does Bilrost mean?\n\nWell is another name for [Bifrost], but there are a lot of projects called Bifrost, including in Kubernetes landscape.\n\n[ci-image]: https://github.com/slok/bilrost/workflows/CI/badge.svg\n[ci-url]: https://github.com/slok/bilrost/actions\n[goreport-image]: https://goreportcard.com/badge/github.com/slok/bilrost\n[goreport-url]: https://goreportcard.com/report/github.com/slok/bilrost\n[mitm]: https://en.wikipedia.org/wiki/Man-in-the-middle_attack\n[Dex]: https://github.com/dexidp/dex\n[oauth2-proxy]: https://github.com/oauth2-proxy/oauth2-proxy\n[manifests]: ./manifests\n[examples]: ./examples\n[Bifrost]: https://en.wikipedia.org/wiki/Bifr%C3%B6st\n[bilrost-deployment]: ./manifests/bilrost-deployment.yaml\n[CRD]: ./manifests/crd\n[nginx-oauth2]: https://github.com/kubernetes/ingress-nginx/tree/master/docs/examples/auth/oauth-external-auth\n[Skipper]: https://github.com/zalando/skipper/\n[Traefik]: https://github.com/containous/traefik\n[nginx-controller]: https://github.com/kubernetes/ingress-nginx\n[Prometheus]: https://prometheus.io/\n[docker-repository]: https://hub.docker.com/r/slok/bilrost","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fslok%2Fbilrost","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fslok%2Fbilrost","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fslok%2Fbilrost/lists"}