Repository files navigation

⚠️

Please go tohttps://openunison.github.io/ to integrate your cluster with OpenUnison. This repo is no longer supported and will no longer get updated builds

⚠️

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 bothkubectl 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.

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

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 ishttps://host_name/auth/github wherehost_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

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

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 in theopenunison namespace:

apiVersion: v1type: Opaquemetadata:  name: orchestra-secrets-source  namespace: openunisondata:  GITHUB_SECRET_ID: aW0gYSBzZWNyZXQ=  K8S_DB_SECRET: aW0gYSBzZWNyZXQ=  unisonKeystorePassword: aW0gYSBzZWNyZXQ=kind: Secret

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

Additionally, you can add your identity provider's TLS base64 encoded PEM certificate to your values undertrusted_certs forpem_b64. This will allow OpenUnison to talk to your identity provider using TLS if it doesn't use a commercially signed certificate. If you don't need a certificate to talk to your identity provider, replace thetrusted_certs section withtrusted_certs: [].

Finally, run the helm chart:

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

Runkubectl 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 theou-tls-certificate secret in theopenunison namespace.

To login, open your browser and go to the host you specified forOU_HOST in yourinput.props. For instance ifOU_HOST isk8sou.tremolo.lan then navigate tohttps://k8sou.tremolo.lan. You'll be prompted for your github username and password. Once authenticated you'll be able login to the portal and generate your.kube/config from the Tokens screen.

You can bypass manually launching a browser with theoulogin kubectl plugin -https://github.com/TremoloSecurity/kubectl-login. This plugin will launch a browser for you, authenticate you then configure your kubectl configuration without any pre-configuration on your clients.

OpenUnison's built in reverse proxy doesn't support the SPDY protocol which kubectl, and the client-go sdk, uses forexec,cp, andport-forward. If you require these options, and are using impersonation, you can now enable the JetStack OIDC proxy (https://github.com/jetstack/kube-oidc-proxy) instead of using OpenUnison's built in reverse proxy. To enable it, add theimpersonation options from the helm chart configuration to your chart.NOTE when using the oidc-proxyservices.enable_tokenrequest must befalse. TheDeployment created for the oidc proxy will inherrit theServiceAccount from OpenUnison, as well as theservices.pullSecret andservices.node_selectors configuration in your helm chart. Resource requests and limits should be set specifically for the OIDC proxy under theimpersonation section. The proxy is run as a non-privileged unix user as well. An example configuration when deploying with Let's Encrypt:

impersonation:  use_jetstack: true  jetstack_oidc_proxy_image: quay.io/jetstack/kube-oidc-proxy:v0.3.0  explicit_certificate_trust: false

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:

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 formatOrgName/ and teams being the formatOrgName/TeamName. To authorize members of teamTremnoloSecurity/Ownsers to be cluster administrators, we create aClusterRoleBinding:

kind: ClusterRoleBindingapiVersion: rbac.authorization.k8s.io/v1metadata:  name: github-cluster-adminssubjects:- kind: Group  name: TremoloSecurity/OwnersroleRef:  kind: ClusterRole  name: cluster-admin  apiGroup: rbac.authorization.k8s.io

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 yourOU_HOST isk8sou.tremolo.lan and your user's login ismmosley your username to Kubernetes would behttps://k8sou.tremolo.lan/auth/idp/k8sIdp#mmosley. To create a cluster role binding to give cluster-admin access to a specific user:

kind: ClusterRoleBindingapiVersion: rbac.authorization.k8s.io/v1metadata:  name: github-cluster-adminssubjects:- kind: User  name: https://k8sou.tremolo.lan/auth/idp/k8sIdp#mmosleyroleRef:  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 ismmosley 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

If you can't use github orgnization and teams, take a look at the OpenUnison Identity Manager for Kubernetes -https://github.com/TremoloSecurity/openunison-qs-kubernetes/tree/activedirectory. This tool adds on to the login capabilities with the ability to manage access to the cluster and namespaces, along with providing a self service way for users to request new namespaces and manage access.

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 youropenunison namespace.

TheTrust 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 theTrust object.

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

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

Create aTrust object in theopenunison namespace. Here's one for GitLab you can use as an example:

apiVersion: openunison.tremolo.io/v1kind: Trustmetadata:  name: gitlab  namespace: openunisonspec:  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 theTrust is added to the namespace, OpenUnison will pick it up automatically. You can test by trying to login to your application.

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 examplePortalUrl object for ArgoCD:

apiVersion: openunison.tremolo.io/v1kind: PortalUrlmetadata:  name: argocs  namespace: openunisonspec:  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.

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.

Edit theorchestra object in theopenunison namespace (kubectl edit openunison orchestra -n openunison). Look for thenon_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.

Add anOrg object to theopenunison namespace. Here's an exampleOrg:

apiVersion: openunison.tremolo.io/v1kind: Orgmetadata:  name: cluster2  namespace: openunisonspec:  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 theorg in yourPortalUrl object to match theuuid of theOrg you want it to appear in.

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

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.

Please take a look athttps://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.

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.

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

Using GitHub To Login to Kubernetes -https://www.tremolosecurity.com/post/using-github-to-access-kubernetes