Orchestra For Kubernetes - OpenID Connect
Orchestra is an automation portal for Kubernetes built on OpenUnison. Orachestra integrates a user's identity into Kubernetes enabling:
- SSO between the API server and your LDAP infrastructure
- SSO with the Kubernetes Dashboard
- Self service access to existing Namespaces
- Self service creation of new Namespaces
- Workflows for automating access approvals without getting system administrators involved
- Built in self service reporting
When a user accesses Kubernetes using Orchestra, they'll access both the self service portal and the dashboard through OpenUnison's reverse proxy (instead of directly via an ingress). OpenUnison will inject the user's identity into each request, allowing the dashboard to act on their behalf.
Orchestra stores all Kubernetes access information as a groups inside of a relational database, as opposed to a group in an external directory. OpenUnison will create the appropriate Roles and RoleBindings to allow for the access.
- Administration - Full cluster management access
- Administrators - All operations inside of a namespace
- Viewers - Can view contents of a namespace (except
Secrets), but can not make changes
- System Approver - Able to approve access to roles specific to OpenUnison
- Auditor - Able to view audit reports, but not request projects or approve access
What You Need To Start
Prior to deploying OpenUnison you will need:
- Kubernetes 1.10 or higher
- The Nginx Ingress Controller deployed (https://kubernetes.github.io/ingress-nginx/deploy/)
- A MySQL or MariaDB Database
- Information from your OpenID Connect Identity Provider per "Create Environments File" in the next section. When registering OpenUnison with your identity provider, use the hostname and
/auth/oidcas the redirect. For instance if OpenUnison will be running on
k8sou.tremolo.lan.comthen the redirect_uri will be
- An SMTP server for sending notifications
- Deploy the dashboard to your cluster
Required Attributes for Your Identity Provider
In order to integrate your identity provide make sure the following attributes are in the
These are then mapped into the user's object in OpenUnison for personalization.
Orchestra stores environment specific information, such as host names, passwords, etc, in a properties file that will then be loaded by OpenUnison and merged with its configuration. This file will be stored in Kubernetes as a secret then accessed by OpenUnison on startup to fill in the
# parameters in
myvd.conf. For instance the parameter
unison.xml would have an entry in this file. Below is an example
OU_HOST=k8sou.tremolo.lan K8S_DASHBOARD_HOST=k8sdb.tremolo.lan K8S_URL=https://k8s-installer-master.tremolo.lan:6443 OU_HIBERNATE_DIALECT=org.hibernate.dialect.MySQL5InnoDBDialect OU_QUARTZ_DIALECT=org.quartz.impl.jdbcjobstore.StdJDBCDelegate OU_JDBC_DRIVER=com.mysql.jdbc.Driver OU_JDBC_URL=jdbc:mysql://dbs.tremolo.lan:3308/unison OU_JDBC_USER=root OU_JDBC_PASSWORD=start123 OU_JDBC_VALIDATION=SELECT 1 SMTP_HOST=smtp.gmail.com SMTP_PORT=587 SMTP_USERfirstname.lastname@example.org SMTP_PASSWORD=xxxx SMTP_FROMemail@example.com SMTP_TLS=true OU_CERT_OU=k8s OU_CERT_O=Tremolo Security OU_CERT_L=Alexandria OU_CERT_ST=Virginia OU_CERT_C=US unisonKeystorePassword=start123 USE_K8S_CM=true SESSION_INACTIVITY_TIMEOUT_SECONDS=900 OIDC_CLIENT_ID=my_idp_client_id OIDC_CLIENT_SECRET=SOME_SECRET OIDC_IDP_AUTH_URL=https://accounts.google.com/o/oauth2/v2/auth OIDC_IDP_TOKEN_URL=https://oauth2.googleapis.com/token OIDC_IDP_LIMIT_DOMAIN=tremolosecurity-test.com
Detailed Description or Properties
|OU_HOST||The host name for OpenUnison. This is what user's will put into their browser to login to Kubernetes|
|K8S_DASHBOARD_HOST||The host name for the dashboard. This is what users will put into the browser to access to the dashboard. NOTE:
|K8S_URL||The URL for the Kubernetes API server|
|OU_HIBERNATE_DIALECT||Hibernate dialect for accessing the database. Unless customizing for a different database do not change|
|OU_QUARTZ_DIALECT||Dialect used by the Quartz Scheduler. Unless customizing for a different database do not change|
|OU_JDBC_DRIVER||JDBC driver for accessing the database. Unless customizing for a different database do not change|
|OU_JDBC_URL||The URL for accessing the database|
|OU_JDBC_USER||The user for accessing the database|
|OU_JDBC_PASSWORD||The password for accessing the database|
|OU_JDBC_VALIDATION||A query for validating database connections/ Unless customizing for a different database do not change|
|SMTP_HOST||Host for an email server to send notifications|
|SMTP_PORT||Port for an email server to send notifications|
|SMTP_USER||Username for accessing the SMTP server (may be blank)|
|SMTP_PASSWORD||Password for accessing the SMTP server (may be blank)|
|SMTP_FROM||The email address that messages from OpenUnison are addressed from|
|SMTP_TLS||true or false, depending if SMTP should use start tls|
|unisonKeystorePassword||The password for OpenUnison's keystore|
|USE_K8S_CM||Tells the deployment system if you should use k8s' built in certificate manager. If your distribution doesn't support this (such as Canonical and Rancher), set this to false|
|SESSION_INACTIVITY_TIMEOUT_SECONDS||The number of seconds of inactivity before the session is terminated, also the length of the refresh token's session|
|OIDC_CLIENT_ID||The client ID registered with your identity provider|
|OIDC_CLIENT_SECRET||The secret provided by your identity provider|
|OIDC_IDP_AUTH_URL||Your identity provider's authorization url|
|OIDC_IDP_TOKEN_URL||Your identity provider's token url|
|OIDC_IDP_LIMIT_DOMAIN||An email domain to limit access to|
Perform these steps from a location with a working
- Create a directory to store secrets, ie
input.props(the properties file defined above) in that directory
- Create an empty directory for config maps, ie
Based on where you put the files from
Prepare Deployment, run the following:
curl https://raw.githubusercontent.com/TremoloSecurity/kubernetes-artifact-deployment/master/src/main/bash/deploy_openunison.sh | bash -s /path/to/configmaps /path/to/secrets https://raw.githubusercontent.com/OpenUnison/openunison-k8s-idm-oidc/master/src/main/yaml/artifact-deployment.yaml
The output will look like:
namespace/openunison-deploy created configmap/extracerts created secret/input created clusterrolebinding.rbac.authorization.k8s.io/artifact-deployment created job.batch/artifact-deployment created NAME READY STATUS RESTARTS AGE artifact-deployment-jzmnr 0/1 Pending 0 0s artifact-deployment-jzmnr 0/1 Pending 0 0s artifact-deployment-jzmnr 0/1 ContainerCreating 0 0s artifact-deployment-jzmnr 1/1 Running 0 4s artifact-deployment-jzmnr 0/1 Completed 0 15s
Once you see
Completed, you can exit the script (
Ctl+C). This script creates all of the appropriate objects in Kubernetes, signs certificates and deploys both OpenUnison and the Dashboard.
Complete SSO Integration with Kubernetes
kubectl describe configmap api-server-config -n openunison to get the SSO integration artifacts. The output will give you both the certificate that needs to be trusted and the API server flags that need to be configured on your API servers.
First Login to Orchestra
At this point you should be able to login to OpenUnison using the host specified in the
OU_HOST of your properties. Once you are logged in, logout. Users are created in the database "just-in-time", meaning that once you login the data representing your user is created inside of the database deployed for Orchestra.
Create First Administrator
The user you logged in as is currently unprivileged. In order for other users to login and begin requesting access to projects this first user must be enabled as an approver. Login to the MySQL database deployed for Orchestra and execute the following SQL:
insert into userGroups (userId,groupId) values (2,1);
This will add the administrator group to your user. Logout of Orchestra and log back in.
Self Request & Approve Cluster Administrator
Once SSO is enabled in the next step, you'll need a cluster administrator to be able to perform cluster level operations:
- Login to Orchestra
- Click on "Request Access" in the title bar
- Click on "Kubernetes Administration"
- Click "Add To Cart" next to "Cluster Administrator"
- Next to "Check Out" in the title bar you'll see a red
1, click on "Check Out"
- For "Supply Reason", give a reason like "Initial user" and click "Submit Request"
- Since you are the only approver refresh OpenUnison, you will see a red
1next to "Open Approvals". Click on "Open Approvals"
- Click "Review" next to your email address
- Specify "Initial user" for the "Justification" and click "Approve"
- Click on "Confirm Approval"
At this point you will be provisioned to the
k8s-cluster-administrators group in the database that has a RoleBinding to the
cluster-admin Role. Logout of Orchestra and log back in. If you click on your email address in the upper left, you'll see that you have the Role
Updating Secrets and Certificates
In order to change the secrets or update certificate store:
Download the contents of
openunison-secrets in the
openunison namespace into an empty directory
kubectl get secret openunison-secrets -o json -n openunison | python /path/to/openunison-k8s-idm-oidc/src/main/python/download_secrets.py
download_secrets.py is a utility script for pulling the files out of secrets and config maps. Next, make your changes. You can't apply over an existing secret, so next delete the current secret:
kubectl delete secret openunison-secrets -n openunison
Finally, create the secret from the directory where you downloaded the secrets:
kubectl create secret generic openunison-secrets --from-file=. -n openunison
Redeploy Orchestra to pick up the changes. The easiest way is to update an environment variable in the
Users can now login to create namespaces, request access to cluster admin or request access to other clusters.
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.