Skip to content

Certificate Management

How do I change OpenUnison's certificates?

OpenUnison's certificate when deployed in Kubernetes is hosted by the Ingress controller, not by the OpenUnison container its self. When used for the login portal, we want to supply the CA certificate for two reasons:

  1. So it can be embedded in the kubectl command correctly
  2. So that the dashboard SSO works properly when validating the login process

Before moving forward you'll need:

  1. A certificate with subject alternative names for your portal (network.openunison_host) and your dashboard (network.dashboard_host). If using impersonation, the impersonation host is needed too (network.api_server_host)
  2. The certificate authority (CA) certificate that signed your certificate from #1
  3. Any intermediate certs needed to complete the chain

Once you have your certificates and keys:

  1. Delete the ou-tls-certificate secret in the openunison namespace - kubectl delete secret ou-tls-certificate -n openunison
  2. Recreate the ou-tls-certificate secret - kubectl create secret tls ou-tls-certificate --cert=/path/to/chain.pem --key=/path/to/key.pem -n openunison - NOTE chain.pem should be your entire certificate chain, including the CA and all intermediate certs. You may also allow a tool like cert-manager to generate your certificate either directly or by specifying the correct annotations on your Ingress controller.
  3. Update your values.yaml file to specify network.createIngressCertificate=false.
  4. If your certificate isn't signed by a well known CA, such as Let's Encrypt, base64 encode the PEM certificate and add it to the trusted_certs section of your values.yaml with the name unison-ca:
trusted_certs:
  - name: unison-ca
    pem_b64: LS0tLS1CRUdJTiBDRVJUSU...

Finally, update both your orchestra and orchestra-login-portal helm deployments:

helm upgrade orchestra tremolo/orchestra --namespace openunison -f /path/to/values.yaml
helm install orchestra-login-portal tremolo/orchestra-login-portal --namespace openunison -f /path/to/values.yaml

How do I trust my API Server's Certificate?

When integrating your cluster via OIDC, your API Server often has certificate that needs to be trusted. If no certificate is specified, then the certificate is loaded from the direct connection to the API server. Since most production deployments use a load balancer, you may need to specify a different certificate. To specify a specific certificate for your API Server, add the correct certificate to your values.yaml's trusted_certs section with the name k8s-master. For instance:

trusted_certs:
- name: k8s-master
  pem_b64: ...

If your API server is protected with a commercial certificate, or the certificate is installed on all clients, you can change your values.yaml to tell OpenUnison to look at a non-existent certificate by adding K8S_API_SERVER_CERT to openunison.non_secret_data in your values.yaml:

openunison:
  replicas: 1
  non_secret_data:
    K8S_DB_SSO: oidc
    K8S_API_SERVER_CERT: api-server-none

This will tell OpenUnison to use a certificate that doesn't exist (api-server-none) when generating a token, so your kubectl configuration won't contain any API Server certificate relying on your workstation's own trusted certificate store.

How do I include additional keys and certificates?

If your OpenUnison needs to be able to include additional key pairs to support your environment deployment there are two options:

  1. Have OpenUnison's operator generate them for you - OpenUnison's operator is a mini "cert-manager", it's not nearly as extensive but for simple and internal keypair generation it works well.
  2. Import a Secret from a generated source - You can use a system like cert-manager to generate your Secrets and them let OpenUnison know where they are to import them.

In either case, the operator will make sure OpenUnison stays up to date. To add a new key pair, add the following YAML with customizations for your needs, to the openunison section of your values.yaml:

openunison:
  keys:
  - name: sts-aws
    # can be keypair or certificate
    import_into_ks: keypair
    # the name of the Secret the keypair is stored in
    tls_secret_name: aws-sts-keypair
    # if true, but wasn't generated by OpenUnison, it will get replaced.  If using
    # cert-manager or another generator for this key pair, set to false
    replace_if_exists: true
    create_data:
      # important for self-signed
      ca_cert: true
      key_size: 2048
      # sets the CN
      server_name: aws-sts-keypair

Rotating Keys

OpenUnison's built in certificate manager will automatically replace generated certificates 30 days prior to their expiration and will trigger the operator to reload them and redeploy.

Hot Key Reload

Starting with OpenUnison 1.0.45 keys can be reloaded without forcing the operator to re-rollout the OpenUnison pods. This allows you to setup an automated certificate rotation. An example is to use cert-manager to rotate keys on a more periodic basis. For instance if you create the following Certificate object:

apiVersion: cert-manager.io/v1
kind: Certificate
metadata:
  name: idp-cert
  namespace: openunison
spec:
  isCA: false
  commonName: idp-cert
  secretName: idp-cert
  duration: 2h
  renewBefore: 1h
  privateKey:
    algorithm: RSA
    size: 4096
  issuerRef:
    name: root-selfsigned
    kind: ClusterIssuer

Then update your values.yaml to import the key pair:

openunison:
  keys:
  - name: idp-cert
    # can be keypair or certificate
    import_into_ks: keypair
    # the name of the Secret the keypair is stored in
    tls_secret_name: idp-cert
    # if true, but wasn't generated by OpenUnison, it will get replaced.  If using
    # cert-manager or another generator for this key pair, set to false
    replace_if_exists: false
    create_data:
      # important for self-signed
      ca_cert: true
      key_size: 2048
      # sets the CN
      server_name: idp-cert

Whenever cert-manager regenerates the Secret idp-cert, it will get loaded directly into OpenUnison.

Kubernetes Identity Provider Short Lived Keys

OpenUnison automatically replaces the key used by the Kubernetes identity provider once a year. If you want to have keys that rotate more often, you may use a tool like cert-manager to automate the regeneration more quickly and allow OpenUnison to reload the key. First, generate a key using cert-manager using a Certificate:

apiVersion: cert-manager.io/v1
kind: Certificate
metadata:
  name: unison-saml2-rp-sig
  namespace: openunison
spec:
  commonName: unison-saml2-rp-sig
  duration: 2h
  isCA: false
  issuerRef:
    kind: ClusterIssuer
    name: internal-ca-issuer
  privateKey:
    algorithm: RSA
    size: 4096
  renewBefore: 1h
  secretName: unison-saml2-rp-sig

It's important that the Secret name is unison-saml2-rp-sig. Once Secret has been created, update your values.yaml with 

openunison:
  generate_idp_key_secret: false

This will configure the operator to leave an existing Secret alone. Once OpenUnison is redeployed the key will be reloaded whenever the Secret is updated.

NOTE: When the keys rotate, existing sessions will be invalidated and will need to re-login.