Install

To install OpenBao using this component, there are a few things to decide and prepare.

Backups

By default, backups using k8up are enabled. For this to work k8up needs to be installed on the same cluster using the k8up component.

By default, the component uses the following configuration:

backup:
  enabled: true
  schedule: '*/13 * * * *'
  keepjobs: 5
  password: '?{vaultkv:${cluster:tenant}/${cluster:name}/openbao/${_instance}/backup/password}'
  bucket:
    name: '${_instance}-backup'
    accesskey: '?{vaultkv:${cluster:tenant}/${cluster:name}/openbao/${_instance}/backup/s3_access_key}'
    secretkey: '?{vaultkv:${cluster:tenant}/${cluster:name}/openbao/${_instance}/backup/s3_secret_key}'

The backup configuration expects that there is a bucket with the name ${INSTANCE}-backup.

The three referenced secrets need to be added to the OpenBao instance associated with the Lieutenant instance managing the cluster on which this component is installed:

  • The password to use for backup encryption in key clusters/kv/${TENANT_ID}/${CLUSTER_ID}/openbao/${INSTANCE}/backup/password}

  • The access key for the bucket in key clusters/kv/${TENANT_ID}/${CLUSTER_ID}/openbao/${INSTANCE}/backup/s3_access_key}

  • The secret key for the bucket in key clusters/kv/${TENANT_ID}/${CLUSTER_ID}/openbao/${INSTANCE}/backup/s3_secret_key}

Unless you explicitly configure multiple instances of the component, a single OpenBao instance will be deployed. In this case, ${INSTANCE} will simply be openbao. See Multiple Instances for more details on how to deploy multiple OpenBao instances using this component.

LDAP

By default, only the backup service account and the root user has access to openbao. You have the option to add more authentication methods and policies. Here is an example to add OpenBao access to all people in an LDAP group.

config:
  auth_:
    ldap:
      type: ldap
      description: LDAP auth
      options:
        listing_visibility: "unauth"
      config:
        url: ldaps://ldap.server.net:636
        binddn: "uid=openbao-service,ou=Special Users,dc=server,dc=net"
        bindpass: '?{vaultkv:${cluster:tenant}/${cluster:name}/openbao/${_instance}/ldappass}'
        userattr: uid
        userdn: "ou=openbao,ou=Service Access,ou=Views,dc=server,dc=net"
        groupdn: "ou=Groups,dc=vshn,dc=net"
        groupattr: cn
      groups:
        openbao-root:
          policies: cluster-root
  policies_:
    cluster-root:
      rules: |
        path "clusters/*" {
          capabilities = ["create", "read", "update", "delete", "list"]
        }

Under the hood, this component uses bank-vaults to configure OpenBao. This reference provides more details on how to configure policies and authentication methods.

The component provides some helper keys (as shown with auth_ and policies_) which allow users to provide the configuration as objects. These helper keys are transformed into the corresponding bank-vaults configuration parameter (auth and policies) by transforming each key-value pair into a list entry.

See the parameters reference for more details on the helper keys.

Lieutenant Integration

If your OpenBao should interact with a Lieutenant instance, we need to add some policies and authentication methods. See the how-to on integrating Lieutenant.

Multiple Instances

This component is able to deploy multiple instances of OpenBao on the same cluster. You can deploy multiple instances of OpenBao by instantiating the component. The following configuration creates two OpenBao instances named openbao-prod and openbao-test.

applications:
  - openbao as openbao-prod
  - openbao as openbao-test
parameters:
  openbao_prod:
    config:
      auth_:
        ldap:
          type: ldap
          description: LDAP auth
          options:
            listing_visibility: "unauth"
          config:
            url: ldaps://ldap.server.net:636
            binddn: "uid=openbao-service,ou=Special Users,dc=server,dc=net"
            bindpass: '?{vaultkv:${cluster:tenant}/${cluster:name}/openbao/${_instance}/ldappass}'
            userattr: uid
            userdn: "ou=openbao,ou=Service Access,ou=Views,dc=server,dc=net"
            groupdn: "ou=Groups,dc=vshn,dc=net"
            groupattr: cn
          groups:
            openbao-root:
              policies: cluster-root
      policies_:
        cluster-root:
          rules: |
            path "clusters/*" {
              capabilities = ["create", "read", "update", "delete", "list"]
            }
  openbao_test:
    backup:
      enabled: false

This will deploy a production OpenBao with LDAP access named openbao-prod to the namespace openbao-prod. And a test OpenBao without backups named openbao-test to the namespace openbao-test.

When instantiating a component the ${INSTANCE} parameter is set to the instance’s name. For the production OpenBao, the parameter is set to openbao-prod and for the test OpenBao it’s set to openbao-test.

There are some things to consider when deploying multiple instances of OpenBao:

  • No two instances are allowed to have the same name. This includes instances of other components. You should never name an instance the same name as other components. Naming your OpenBao instance argocd can break in unexpected ways. In general it’s a good idea to prefix your instance with openbao-.

  • You can overwrite both the name and namespace of the instance. Two instances can either have the same name or be in the same namespace. If two instances have the same name and namespace bad things will break in unexpected ways.

  • If two instances are deployed to the same namespace, they can in principle read each others secrets. This means in practice you will want to put the production OpenBao in a separate namespace.

More information on how component instantiation works can be found here.

OIDC Integration

OpenBao has the option to authenticate users through OIDC. This guide describes the manual setup of the OpenBao OIDC integration for an OpenBao instance which is associated with a Lieutenant instance.

It should also be possible to configure OIDC integration through the component. However, this requires a client secret which should be stored in OpenBao. We don’t recommend configuring OIDC through the component when integrating OpenBao with Lieutenant as this will introduce a dependency for OpenBao on itself making setup and disaster recovery more difficult.

Configure OIDC Provider

This guide assumes that the OIDC provider is a Keycloak instance, but other OIDC providers should also work.

We first need to create an OIDC client for OpenBao.

  1. In the appropriate realm, create a OIDC client with:

    Access Type: Confidential
Redirect URLs:
  - https://${OPENBAO_URL}/ui/vault/auth/oidc/oidc/callback
  - https://${OPENBAO_URL}/oidc/callback
  - http://localhost:8250/oidc/callback

  2. Add a role syn-root under the Roles tab in the OIDC client

  3. Under the Mappers tab add a User Client Role mapper. Choose the created OIDC client as the Client ID and set the Token Claim Name to groups.

  4. Open the Keycloak group or user that should get access to OpenBao and add them to the syn-root role of the created OIDC client.

  5. Copy client secret of the created OIDC client located in the Credentials tab of the client.

Configure OpenBao

Via Project Syn

  1. Store the client secret of the OIDC client in the Project Syn OpenBao for the cluster.

  2. Add the following configuration to your component config

    auth_:
  oidc:
    type: oidc
    description: OIDC authentication
    options:
      listing_visibility: unauth
    config:
      default_role: default
      namespace_in_state: true
      oidc_client_id: <CLIENT_ID> (1)
      oidc_client_secret: ?{vaultkv:${cluster:tenant}/${cluster:name}/openbao/${_instance}/oidc/client_secret} (2)
      oidc_discovery_url: https://keycloak.example.com/auth/realms/example-realm (3)
    roles:
      default:
        allowed_redirect_uris: (4)
          - https://${openbao:ingress:host}/ui/vault/auth/oidc/oidc/callback
          - https://${openbao:ingress:host}/oidc/callback
          - http://localhost:8250/oidc/callback
        bound_claims_type: string
        groups_claim: groups
        policies: ["default"]
        role_type: oidc
        user_claim: sub
    1 The Client ID of the client that you configured in the previous section
    2 A secret reference to the Client secret in the Project Syn OpenBao. Adjust this to the secret where you stored the client secret in the previous step.
    3 Adjust this to https://${KEYCLOAK_URL}/auth/realms/${REALM}
    4 If necessary, update this parameter to match the redirect URIs that you configured in the Keycloak client

Manual configuration

  1. Add a new OIDC Authenication Method in the OpenBao UI under the Access tab with the following configuration

    List method when unauthenticated: true
OIDC discovery URI: https://${KEYCLOAK_URL}/auth/realms/${REALM}
Default role: default
OIDC client ID: ${CLIENT_ID}
OIDC client Secret: ${CLIENT_SECRET}

  2. Open a CLI connection to OpenBao, you can do this by clicking on the CLI icon in the UI, and enter

    bao write auth/oidc/role/default \
      allowed_redirect_uris="https://${OPENBAO_URL}/ui/vault/auth/oidc/oidc/callback" \
      allowed_redirect_uris="https://${OPENBAO_URL}/oidc/callback" \
      allowed_redirect_uris="http://localhost:8250/oidc/callback" \
      user_claim="sub" \
      policies="default" \
      groups_claim="groups"

    At this point you should be able to login to OpenBao using OIDC, but after the login you shouldn’t be able to access anything but the cubbyhole.

  3. Under the Access tab in the OpenBao UI create a new group called syn-root. The group should be of Type: external and add the syn-root policy to it (or any other policy you would like the OIDC users to have).

  4. Open the newly created group and add an alias with name syn-root and OIDC as the Auth Backend

When logging in with an OIDC user you should now be able to see the cluster/kv secret engine.