tremolosecurity/openunison-k8s-login-github repository overview

⁠Orchestra Login Portal for GitHub

Short video of logging into Kubernetes and using kubectl using GitHub

Orchestra Login Portal provides a login portal for Kubernetes that allows you to authenticate with GitHub, use GitHub teams and organizations for RBAC authorizations and provides integration for both kubectl and the Kubernetes Dashboard (https://github.com/kubernetes/dashboard⁠). The portal runs inside of Kubernetes, leveraging Kubernetes for scalability, secret management and deployment.

When a user accesses Kubernetes using Orchestra, they'll access both the login portal and the dashboard through OpenUnison (instead of directly via an ingress). OpenUnison will inject the user's identity into each request, allowing the dashboard to act on their behalf. The login portal has no external dependencies outside of GitHub and Kubernetes. All objects for session state are stored as CRDs.

⁠Deployment

⁠Watch a Video

This 7 minute video shows the entire deployment and user onboarding process

⁠What You Need To Start

Prior to deploying Orchestra you will need:

1. Kubernetes 1.10 or higher
2. The Nginx Ingress Controller deployed (https://kubernetes.github.io/ingress-nginx/deploy/⁠)
3. Client id and secret from a GitHub OAuth2 Application
4. Deploy the dashboard to your cluster
5. helm 3.0+

When creating your GitHub OAuth2 application, the callback URL is https://host_name/auth/github where host_name is the host you want to use for your login portal.

The deployment is a four step process:

1. Add Tremolo Security's Helm repo to your own
2. Deploy the OpenUnison Operator
3. Create a secret for your Active Directory password
4. Deploy OpenUnison

⁠Add Tremolo Security's Helm Repo

helm repo add tremolo https://nexus.tremolo.io/repository/helm/
helm repo update

⁠Deploy The OpenUnison Operator

Create your namespace

kubectl create ns openunison

Deploy the operator

helm install openunison tremolo/openunison-operator --namespace openunison

Wait for the operator pod to be available

watch kubectl get pods -n openunison

⁠Create A Secret For Your Active Directory Password

Create a secret in the openunison namespace:

apiVersion: v1
type: Opaque
metadata:
  name: orchestra-secrets-source
  namespace: openunison
data:
  GITHUB_SECRET_ID: aW0gYSBzZWNyZXQ=
  K8S_DB_SECRET: aW0gYSBzZWNyZXQ=
  unisonKeystorePassword: aW0gYSBzZWNyZXQ=
kind: Secret

⁠Deploy OpenUnison

Copy values.yaml (https://raw.githubusercontent.com/OpenUnison/helm-charts/master/openunison-k8s-login-github/values.yaml⁠) and update as appropriate:

Finally, run the helm chart:

helm install orchestra tremolo/openunison-k8s-login-github --namespace openunison -f /path/to/values.yaml

⁠Complete SSO Integration with Kubernetes

Run kubectl describe configmap api-server-config -n openunison to get the SSO integration artifacts. The output will give you both the API server flags that need to be configured on your API servers. The certificate that needs to be trusted is in the ou-tls-certificate secret in the openunison namespace.

⁠First Login

To login, open your browser and go to the host you specified for OU_HOST in your input.props. For instance if OU_HOST is k8sou.tremolo.lan then navigate to https://k8sou.tremolo.lan⁠. You'll be prompted for your Active Directory username and password. Once authenticated you'll be able login to the portal and generate your .kube/config from the Tokens screen.

⁠Authorizing Access via RBAC

On first login, if you haven't authorized access to any Kubernetes roles you won't be able to do anything. There are two approaches you can take:

⁠Organization / Team Driven Membership

Kubernetes will see your user's organizations and teams as groups. To authorize users based on these groups, list them in your RBAC policies as groups with organizations being in the format OrgName/ and teams being the format OrgName/TeamName. To authorize members of team TremnoloSecurity/Ownsers to be cluster administrators, we create a ClusterRoleBinding:

kind: ClusterRoleBinding
apiVersion: rbac.authorization.k8s.io/v1
metadata:
  name: github-cluster-admins
subjects:
- kind: Group
  name: TremoloSecurity/Owners
roleRef:
  kind: ClusterRole
  name: cluster-admin
  apiGroup: rbac.authorization.k8s.io

⁠User Driven Membership

If you are not able to use teams or organizations in GitHub, you can directly add users to role bindings. Kubernetes requires that you identify openid connect users with the prefix of the url of the identity provider. So if your OU_HOST is k8sou.tremolo.lan and your user's login is mmosley your username to Kubernetes would be https://k8sou.tremolo.lan/auth/idp/k8sIdp#mmosley. To create a cluster role binding to give cluster-admin access to a specific user:

kind: ClusterRoleBinding
apiVersion: rbac.authorization.k8s.io/v1
metadata:
  name: github-cluster-admins
subjects:
- kind: User
  name: https://k8sou.tremolo.lan/auth/idp/k8sIdp#mmosley
roleRef:
  kind: ClusterRole
  name: cluster-admin
  apiGroup: rbac.authorization.k8s.io

NOTE: There are multiple reasons this is a bad idea:

1. Hard to audit - There is no easy way to say "what role bindings is mmosley a member of?
2. Difficult to remove access - Same reason as #1, you need to figure out every role binding a user is a member of to remove
3. Easy to get wrong - If you mistype a user's login id Kubernetes won't tell you

⁠Adding Applications and Clusters for Authentication

OpenUnison can support more applications for SSO then just Kubernetes and the dashboard. You can add other clusters and applications that support OpenID Connect by adding some custom resources to your openunison namespace.

⁠Add a Trust

The Trust tells your OpenID Connect enabled application it can trust authentication requests from your OpenUnison. To start you'll need:

1. Callback URL - This URL is where OpenUnison redirects the user after authenticating.
2. Client Secret - Web applications, like GitLab, will need a secret that is shared between the two systems. Applications with CLI components, like ArgoCD, don't need a client secret.
3. Client ID - This is how you identify your application to OpenUnison.

OpenUnison will provide the following claims for your application to consume:

Once you have everything you need to get started, create the Trust object.

⁠Create a Secret

If you're application is using a client secret, a Secret needs to be created to hold it. This can either be a new Secret or it can be a new one. Which ever Secret you add it to, keep a note of the name of the Secret and the key in the data section used to store it.

If your application doesn't have a client secret, skip this step.

⁠Create the Trust

Create a Trust object in the openunison namespace. Here's one for GitLab you can use as an example:

apiVersion: openunison.tremolo.io/v1
kind: Trust
metadata:
  name: gitlab
  namespace: openunison
spec:
  accessTokenSkewMillis: 120000
  accessTokenTimeToLive: 60000
  authChainName: LoginService
  clientId: gitlab
  clientSecret:
    keyName: gitlab
    secretName: orchestra-secrets-source
  codeLastMileKeyName: lastmile-oidc
  codeTokenSkewMilis: 60000
  publicEndpoint: false
  redirectURI:
  - https://gitlab.local.tremolo.dev/users/auth/openid_connect/callback
  signedUserInfo: false
  verifyRedirect: true

Here are the details for each option:

Once the Trust is added to the namespace, OpenUnison will pick it up automatically. You can test by trying to login to your application.

⁠Add a "Badge" to Your Portal

When you login to the Orchestra portal, there are badges for your tokens and for the dashboard. You can dynamically add a badge for your application too. Here's an example PortalUrl object for ArgoCD:

apiVersion: openunison.tremolo.io/v1
kind: PortalUrl
metadata:
  name: argocs
  namespace: openunison
spec:
  label: ArgoCD
  org: B158BD40-0C1B-11E3-8FFD-0800200C9A66
  url: https://ArgoCD.apps.192-168-2-140.nip.io
  icon: iVBORw0KGgoAAAANSUhEUgAAANIAAADwCAYAAAB1/Tp/AAAfQ3pUWHRSYXcgcHJvZ...
  azRules:
  - constraint: o=Tremolo
    scope: dn

Once created, the badge will appear in the Orchestra portal! No need to restart the containers.

⁠Organizing Badges

If you're adding multiple badges or clusters, you may find that the number of badges on your front page become difficult to manage. In that case you can enable orgnaizations in OpenUnison and organize your badges using an orgnaization tree.

⁠Enable Organizations on your Portal Page

Edit the orchestra object in the openunison namespace (kubectl edit openunison orchestra -n openunison). Look for the non_secret_data section and add the following:

- name: SHOW_PORTAL_ORGS
  value: "true"

Once you save, OpenUnison will restart and when you login there will now be a tree that describes your organizations.

⁠Creating Organizations

Add an Org object to the openunison namespace. Here's an example Org:

apiVersion: openunison.tremolo.io/v1
kind: Org
metadata:
  name: cluster2
  namespace: openunison
spec:
  description: "My second cluster"
  uuid: 04901973-5f4c-46d9-9e22-55e88e168776
  parent: B158BD40-0C1B-11E3-8FFD-0800200C9A66
  showInPortal: true
  showInRequestAccess: false
  showInReports: false
  azRules:
  - scope: dn
    constraint: o=Tremolo

Once added, the new organizations will be loaded dynamiclly by OpenUnison. Change the org in your PortalUrl object to match the uuid of the Org you want it to appear in.

⁠Using Your Own Certificates

If you want to integrate your own certificates see our wiki entry - https://github.com/TremoloSecurity/OpenUnison/wiki/troubleshooting#how-do-i-change-openunisons-certificates⁠

⁠Monitoring OpenUnison

This deployment comes with a /metrics endpoint for monitoring. For details on how to integrate it into a Prometheus stack - https://github.com/TremoloSecurity/OpenUnison/wiki/troubleshooting#how-do-i-monitor-openunison-with-prometheus⁠.

⁠Trouble Shooting Help

Please take a look at https://github.com/TremoloSecurity/OpenUnison/wiki/troubleshooting⁠ if you're running into issues. If there isn't an entry there that takes care of your issue, please open an issue on this repo.

⁠Whats next?

Now you can begin mapping OpenUnison's capabilities to your business and compliance needs. For instance you can add multi-factor authentication with TOTP or U2F, Create privileged workflows for onboarding, scheduled workflows that will deprovision users, etc.

⁠Customizing Orchestra

To customize Orchestra - https://github.com/TremoloSecurity/OpenUnison/wiki/troubleshooting#customizing-orchestra⁠