In this tutorial I will show how you can use Oauth2 Proxy to limit access to your Kubernetes services only to members of your GitHub organization, team or just to yourself.
If you're like me then you might have a long list of self-hosted third-party services running inside of your Kubernetes clusters, such as Grafana, Sentry.io, Elastic and Jaeger. Some of these services may have their own mechanism for authentication, some can be configured with an external OAuth provider, and some won't have any authentication mechanism at all.
How can we easily expose our services over the internet with a proper audit trail and without letting any unauthorized users in?
One surprisingly simple solution is to create a GitHub OAuth app and configure your ingresses to use a proxy that permits access based on which GitHub teams a user is part of.
That's a lot of words, but I'll show you that setting it up is just minutes of work and the result is protected internal services with just two ingress annotations:
nginx.ingress.kubernetes.io/auth-signin: https://oauth2.symbiosis.host/oauth2/start?rd=https://$host$uri
nginx.ingress.kubernetes.io/auth-url: https://oauth2.symbiosis.host/oauth2/auth
Requirements
- A Kubernetes cluster
- Helm
- Kubectl
- NGINX ingress controller
- Cert-manager (to generate TLS certs for OAuth2 Proxy, optional)
What is OAuth2 Proxy?
OAuth2 Proxy is a reverse proxy that authenticates users for a whole range of different Oauth identity providers, such as Keycloak, Google, GitHub, OpenID Connect, and more.
Different providers have different configurations. What makes this powerful in the case of GitHub is the ability to allow or reject requests based on properties such as GitHub organization membership, team membership, email domain and others.
A running Oauth2 Proxy will expose endpoints for signing in, signing out, callbacks used by the OAuth provider, and more. These endpoints can in turn be used to configure NGINX Ingress to ensure that requests to a specific ingress are only performed by a user that is properly signed in and has the proper authority.
However, before we can install and configure OAuth2 Proxy we first have to configure the OAuth provider.
Creating an OAuth app on GitHub
Sign in to GitHub and browse to Settings → Developer settings → OAuth Apps → New OAuth App, fill in the name and page of your application.
The authorization callback URL is the URL that GitHub will redirect to when the authorization is finished. This URL will not be reachable as we haven't configured the OAuth2 Proxy ingress yet. However, it should have the following structure, with example.com
replaced by your domain name:
https://example.com/oauth2/callback
Once the app is created generate a client secret and save the generated value. We will use this value soon to configure OAuth2 Proxy.
Installing OAuth2 Proxy with Helm
I've used Helm to install OAuth2 Proxy and found it to be pretty convenient. Check out the Helm chart for the full list of parameters.
Below is an example values.yaml
file that permits access to any user that is part of the "example-org" GitHub organization, with TLS certificates generated by cert-manager.
config:
clientID: example-client-id # Replace with your GitHub OAuth app client ID
configFile: |
provider = "github"
scope = "user:email read:org"
github_org = "example-org" # Replace with your GitHub org name, or github_team=team_name to limit access to a specific team
email_domains = [ "*" ] # Replace with [ "example.com" ] to limit access to users with specific email domain
cookie_domains = [ "example.com" ] # Replace with domain names that the proxy is allowed to redirect to after auth, prepend . for wildcards, i.e. ".example.com"
whitelist_domains = [ "example.com" ] # Same as above
ingress:
enabled: true
path: /oauth2
pathType: Prefix
className: nginx
annotations:
acme.cert-manager.io/http01-edit-in-place: "true"
cert-manager.io/cluster-issuer: letsencrypt # Replace with name of your cert-manager ClusterIssuer
kubernetes.io/tls-acme: "true"
hosts:
- example.com # Replace with host address for the oauth2-proxy ingress
tls:
- hosts:
- example.com # Same as above
secretName: oauth2-tls
Make sure to replace example-client-id
, example-org
and example.com
with your GitHub OAuth app client ID, GitHub organization and domain name.
You may have to edit the cert-manager annotations based on your own configuration, for example by using the cert-manager.io/issuer
annotation for namespaced certificate issuers.
We also need to configure a cookie secret that is used by OAuth2 Proxy to encrypt and decrypt user session cookies. Any base64 encoded string is valid, a secure base64 encoded string can be generated using openssl
with the following command:
openssl rand -base64 32 | head -c 32 | base64
Finally, we can add the OAuth2 Proxy helm repository and install the chart with our values file, cookie and client secrets:
helm repo add oauth2-proxy https://oauth2-proxy.github.io/manifests
helm install oauth2-proxy oauth2-proxy/oauth2-proxy --file values.yaml --set config.cookieSecret=example-cookie-secret --set config.clientSecret=example-client-secret
oauth2-proxy without cert-manager
If you don't have cert-manager installed you can either create the TLS certificate manually or disable TLS altogether:
config:
clientID: example-client-id # Replace with your GitHub OAuth app client ID
configFile: |
github_org = "example-org" # Replace with your GitHub org name, or github_team=team_name to limit access to a specific team
scope = "user:email read:org"
email_domains = [ "*" ] # Replace with [ "example.com" ] to limit access to users with specific email domain
provider = "github"
cookie_secure = false
cookie_domains = [ "example.com" ] # Replace with domain names that the proxy is allowed to redirect to after auth
whitelist_domains = [ "example.com" ] # Same as above
ingress:
enabled: true
path: /oauth2
pathType: Prefix
className: nginx
hosts:
- example.com # Replace with host address for the oauth2-proxy ingress
Note that you need to change the schema of the callback and auth URLs to http://
, both in the GitHub OAuth configuration and in the annotations below.
Configuring our ingress to use OAuth2 Proxy
Now that OAuth2 Proxy is up and running, we can configure our ingress to protect our internal services with GitHub OAuth.
Add the following annotations to your ingress:
nginx.ingress.kubernetes.io/auth-signin: https://example.com/oauth2/start?rd=https://$host$uri
nginx.ingress.kubernetes.io/auth-url: https://example.com/oauth2/auth
Make sure to replace example.com
with your own domain name.
The first annotation auth-signin
will redirect unauthenticated requests to the OAuth2 Proxy login page. After the user logs in and authorizes the application, they will be redirected back to the original requested URL thanks to the rd
query parameter that fowards the redirect URL to the proxy.
The second annotation auth-url
specifies the authentication URL that is used to verify the user's session.
Use the commands below if you don't have a service to expose yet in order to launch a protected hello-world application. Make sure to replace example.com
with your domain name.
kubectl create deployment web --image=gcr.io/google-samples/hello-app:1.0
kubectl expose deployment web --port=8080
kubectl create ingress web --class nginx '--rule=example.com/=web:8080' \
--annotation 'nginx.ingress.kubernetes.io/auth-signin=https://example.com/oauth2/start?rd=https://$host$uri' \
--annotation 'nginx.ingress.kubernetes.io/auth-url=https://example.com/oauth2/auth'
Accessing an endpoint protected by OAuth2 Proxy will redirect you to a GitHub OAuth sign-in page.
Make sure to grant access to the organization that you are authenticating against for OAuth2 Proxy to be able to find it and verify your authority.
If everything is set up correctly you should be redirected to your protected endpoint after signing in.
Limitations
Unfortunately, OAuth2 Proxy cannot be configured to allow specific GitHub teams or organizations to access a resource on the ingress level. If you wish to limit access to ingress1 only to team1 while also limiting access to ingress2 only to team2 you will have to configure multiple OAuth2 Proxy instances and GitHub OAuth applications.
Your services are still exposed on the internet. A security vulnerability in GitHub OAuth, the OAuth2 Proxy or the configuration might expose your service to the whole wide world. Protecting internal services behind a private network is always a good idea.
Putting it all together
To conclude, we've set up a GitHub OAuth app that we've configured with OAuth2 Proxy to allow access to layer 7 ingresses only to the members of our GitHub organization or team. We can use the aforementioned annotations to tag any ingress that we wish to only protect to authenticated users.
Oauth2-proxy isn't the silver bullet for securing internal services, rather it is an easy way to secure many different services or UIs without much work. It can also act as a first line of defense even for services that are only routable on a private network, or services that offer their own authentication mechanism, like Grafana.
You can check out OAuth2 Proxy's official documentation for more tips, tricks and config parameters.
Top comments (0)