User Backends

User Backends are reusable sets of configuration which you can apply to components which require authentication and authorization. Having them defined as their own configuration item allows you to re-use them for multiple components.

Currently support is implemented for the following backend types:

LDAP
OAuth 2.0

Components which can utilize these user backends:

Component	Supported Types
Cloud Control API	`LDAP`
Dstore Report API	`OAuth 2.0`
Filtering Admin	`OAuth 2.0`
ZoneControl	`LDAP`

When configuring a user backend, you always need to supply the following:

userBackends:
  mybackend:
    type: <Type of user backend>

Based on the type you will have different configuration options available:

LDAP
OAuth 2.0

LDAP

When the type is set to ldap, you can configure the following parameters:

Parameter	Type	Default	Description
`attrFirstName`	`string`	`"givenName"`	Name of LDAP attribute to attempt to take a user's first name from
`attrLastName`	`string`	`"sn"`	Name of LDAP attribute to attempt to take a user's last name from
`attrEmail`	`string`	`"mail"`	Name of LDAP attribute to attempt to take a user's email address from
`bindUser`	`string`		DN of an LDAP user to connect with for user/group searching. Only used if `bindSecretName` is not set
`bindPassword`	`string`		Password of user configured via `bindUser`. Only used if `bindSecretName` is not set
`bindSecretName`	`string`		Name of a pre-existing secret holding DN & password of a user to connect with for user/group searching. Has priority over `bindUser` and `bindPassword`
`bindSecretUserKey`	`string`	`"username"`	Name of item in `bindSecretName` Secret containing the user DN
`bindSecretPasswordKey`	`string`	`"password"`	Name of item in `bindSecretName` Secret containing the password
`cacheTimeout`	`integer`	`0`	If configured, allow applications using this userBackend to cache data from LDAP for this duration (in seconds)
`caSecret`	`string`		Name of a pre-existing Secret from which to load CA certificates. Note: Secret must have a `ca.crt` data item
`clientSecret`	`string`		Name of a pre-existing Secret from which to load client certificate + key. Note: Secret must have `tls.crt` and `tls.key` data items
`groupType`	`string`	`"posixGroup"`	Object class of groups to use for determining group membership. Available options: `"posixGroup"` `"groupOfNames"` `"groupOfUniqueNames"`
`groupBases`	List of GroupBase	`[]`	List of base locations inside LDAP to search for groups
`host`	`string`		LDAP host to connect to
`insecureSkipVerify`	`boolean`	`false`	Whether or not to skip verification of certificates presented by the LDAP endpoint
`port`	`integer`	`389`	LDAP port to connect to. Only used if `host` is set
`scheme`	`string`	`"ldap"`	LDAP scheme to connect with. Only used if `host` is set
`uri`	`string`		LDAP connect string (Must be full connect string, ie: `ldap://my.ldap.service.local:389`). Has priority over `host`
`userAttr`	`string`	`"uid"`	Name of LDAP attribute to use to search for a user using their username. Usually `sAMAccountName` for Active Directory users
`userBases`	List of UserBase	`[]`	List of base locations inside LDAP to search for users

Note: You must set either a host or uri to ensure the LDAP connector has an address to connect to.

Group bases

Group bases allow you to specify base locations within LDAP to search for groups. You can configure a group base with the following parameters:

Parameter	Type	Required	Default	Description
`base`	`string`	`yes`		Base location for groups
`scope`	`string`		`"subtree"`	Scope to search base with. Available options: `"base"` `"onelevel"` `"subtree"`
`filters`	`dictionary`		`{}`	Dictionary of LDAP filters to apply when searching for groups

An example with 2 group bases defined:

userBackends:
  myLDAP:
    type: ldap
    uri: "ldap://openldap.openldap.svc.cluster.local:636"

    groupBases:
      - base: "ou=groups,dc=example,dc=org"
      - base: "ou=moregroups,dc=example,dc=org"
        scope: "onelevel"
        filters:
          objectClass: "orgGroup"
          cn: "internal-*"

The group base for "ou=moregroups,dc=example,dc=org" has a modified scope and applies filters:

LDAP group attribute objectClass must match "orgGroup"
LDAP group attribute cn must start with "internal-"

User bases

User bases allow you to specify base locations within LDAP to search for users. You can configure a user base with the following parameters:

Parameter	Type	Required	Default	Description
`base`	`string`	`yes`		Base location for users
`scope`	`string`		`"subtree"`	Scope to search base with. Available options: `"base"` `"onelevel"` `"subtree"`
`filters`	`dictionary`		`{}`	Dictionary of LDAP filters to apply when searching for users

An example with a user base defined:

userBackends:
  myLDAP:
    type: ldap
    uri: "ldap://openldap.openldap.svc.cluster.local:636"

    userBases:
      - base: "ou=users,dc=example,dc=org"
        filters:
          objectClass: "orgUser"

The user base for "ou=users,dc=example,dc=org" has a filter applied:

LDAP user attribute objectClass must match "orgUser"

Posix-based LDAP example

A configuration example with a Posix-based LDAP user backend:

userBackends:
  myLDAP:
    type: ldap
    uri: "ldaps://openldap.openldap.svc.cluster.local:636"
    caSecretName: "ldap-ca-cert"
    bindSecretName: "ldap-bind-user"

    userBases:
      - base: "ou=users,dc=example,dc=org"

    groupBases:
      - base: "ou=groups,dc=example,dc=org"

Active Directory example

A configuration example with an Active Directory-based LDAP user backend:

userBackends:
  myLDAP:
    type: ldap
    uri: "ldaps://my.ldap.service:636"
    caSecretName: "ad-ca-cert"
    bindSecretName: "ad-bind-user"

    userAttr: sAMAccountName
    userBases:
      - base: "ou=users,dc=example,dc=org"

    groupType: groupOfNames
    groupBases:
      - base: "ou=groups,dc=example,dc=org"

OAuth2

When the type is set to oauth2, you can configure the following parameters:

Parameter	Type	Required	Default	Description
`clientID`	`string`			`client_id` to use in authentication towards the OAuth2 provider
`clientSecret`	`string`			`client_secret` to use in authentication towards the OAuth2 provider
`clientSecretName`	`string`			Name of a pre-existing Kubernetes Secret containing a client_id & client_secret for authentication with the OAuth2 provider
`clientSecretIDKey`	`string`		`"password"`	If `credentialsSecretName` is specified: name of the item inside the Secret which holds the `client_id`
`clientSecretSecretKey`	`string`		`"username"`	If `credentialsSecretName` is specified: name of the item inside the Secret which holds the `client_secret`
`introspectionURL`	`string`	`yes`		Full URL of the token introspection URL of the OAuth2 provider
`tlsconfig`	OAuthTLSConfig		`{}`	TLS configuration options

An example OAuth2 configuration:

userBackends:
  keycloak:
    type: oauth2
    introspectionURL: http://keycloak.oauth.endpoint/realms/myrealm/protocol/openid-connect/token/introspect
    clientID: "myclient"
    clientSecret: "h7Rwbv0xBiCVkhrjcA0uwsAQJ18Nxgtf"

Or with the client_id and client_secret obtained from a Secret:

userBackends:
  keycloak:
    type: oauth2
    introspectionURL: http://keycloak.oauth.endpoint/realms/myrealm/protocol/openid-connect/token/introspect
    clientSecretName: my-oauth2-secret

OAuth2 TLS Config

Parameters to configure TLS options, these should be child attributes of the tlsconfig node. For example:

userBackends:
  keycloak:
    type: oauth2
    introspectionURL: http://keycloak.oauth.endpoint/realms/myrealm/protocol/openid-connect/token/introspect
    clientSecretName: my-oauth2-secret
    tlsconfig:
      insecure_skip_verify: true

Parameter	Type	Default	Description
`ca`	`string`		CA in PEM format to use for validation
`caSecret`	`string`		Name of a pre-existing Kubernetes Secret with a data item named `ca.crt` containing the CA in PEM format to use for validation
`insecure_skip_verify`	`boolean`	`false`	Skip validation of the certificate chain and hostname