Skip to main content
Version: main 🚧

Tenant Configuration

Read or replace a tenant's configuration. A write replaces the entire configuration. Changing the hostname list also requires update permission on the tenant. Requires the Multi-Tenancy license.

TenantConfig example​

An example TenantConfig:

apiVersion: management.loft.sh/v1
kind: TenantConfig
metadata:
name: development
spec:
hostnames:
- hostname: development.example.com

TenantConfig reference​

spec object ​

Spec holds the per-tenant configuration.

hostnames object[] ​

Hostnames are the DNS names that resolve to this tenant. Used for SSO bootstrap, UI branding, and per-request tenant resolution.

This field is operator-only: it is set through this subresource and is not delegable to a tenant, for the reasons on storagev1.TenantPlatformConfig. It is stored here and read back from here, but the request path never reads the Secret: the Tenant controller projects these onto Tenant.Status.Hostnames, and resolution and the exclusivity check both go through the field index over that projection.

hostname required string ​

Hostname is the DNS name the platform will treat as belonging to this Tenant (e.g. acme.platform.example.com).

uiSettings object ​

UISettings holds per-tenant user-interface configuration (branding and UI customization), reusing the shared UISettingsConfig type.

loftVersion string ​

LoftVersion holds the current loft version

logoURL string ​

LogoURL is url pointing to the logo to use in the vCluster Platform UI. This path must be accessible for clients accessing the vCluster Platform UI!

faviconURL string ​

FaviconURL is url pointing to the favicon to use in the vCluster Platform UI. This path must be accessible for clients accessing the vCluster Platform UI!

smallLogoURL string ​

SmallLogoURL is url pointing to the small logo to use in the vCluster Platform UI. This path must be accessible for clients accessing the vCluster Platform UI!

logoBackgroundColor string ​

LogoBackgroundColor is the color value (ex: "#12345") to use as the background color for the logo

legalTemplate string ​

LegalTemplate is a text (html) string containing the legal template to prompt to users when authenticating to Loft

primaryColor string ​

PrimaryColor is the color value (ex: "#12345") to use as the primary color

sidebarColor string ​

SidebarColor is the color value (ex: "#12345") to use for the sidebar

accentColor string ​

AccentColor is the color value (ex: "#12345") to use for the accent

customCss string[] ​

CustomCSS holds URLs with custom css files that should be included when loading the UI

customJavaScript string[] ​

CustomJavaScript holds URLs with custom js files that should be included when loading the UI

navBarButtons object[] ​

NavBarButtons holds extra nav bar buttons

position string ​

Position holds the position of the button, can be one of: TopStart, TopEnd, BottomStart, BottomEnd. Defaults to BottomEnd

text string ​

Text holds text for the button

Link holds the link of the navbar button

icon string ​

Icon holds the url of the icon to display

externalURLs object ​

External URLs that can be called from the UI

block boolean ​

Block determines if requests to external URLs from the UI should be blocked

allow string[] ​

Allow specifies which external URLs can be called. In addition to the predefined modules,

  • "vcluster" (license page, feature descriptions, ...)
  • "gtm" (google tag manager)
  • "featurebase" (changelog) any URL can be added to this list. This will allow the UI to make any request to this URL. This is only active when Block is true.

authentication object ​

Authentication holds per-tenant SSO/authentication configuration. It reuses the shared storage authentication type (the same shape as the global platform Config), so a tenant's connectors have an identical schema. Connector client secrets are stored inline, protected by permission-gated projection and by encryption at rest when SECRETS_ENCRYPTION_KEY is set.

oidc object ​

OIDC holds oidc authentication configuration

issuerUrl string ​

IssuerURL is the URL the provider signs ID Tokens as. This will be the "iss" field of all tokens produced by the provider and is used for configuration discovery.

The URL is usually the provider's URL without a path, for example "https://accounts.google.com" or "https://login.salesforce.com".

The provider must implement configuration discovery. See: https://openid.net/specs/openid-connect-discovery-1_0.html#ProviderConfig

clientId string ​

ClientID the JWT must be issued for, the "sub" field. This plugin only trusts a single client to ensure the plugin can be used with public providers.

The plugin supports the "authorized party" OpenID Connect claim, which allows specialized providers to issue tokens to a client for a different client. See: https://openid.net/specs/openid-connect-core-1_0.html#IDToken

clientSecret string ​

ClientSecret to issue tokens from the OIDC provider

redirectURI string ​

loft redirect uri. E.g. https://loft.my.domain/auth/oidc/callback

postLogoutRedirectURI string ​

Loft URI to be redirected to after successful logout by OIDC Provider

caFile string ​

Path to a PEM encoded root certificate of the provider. Optional

insecureCa boolean ​

Specify whether to communicate without validating SSL certificates

preferredUsername string ​

Configurable key which contains the preferred username claims

loftUsernameClaim string ​

LoftUsernameClaim is the JWT field to use as the user's username.

usernameClaim string ​

UsernameClaim is the JWT field to use as the user's id.

emailClaim string ​

EmailClaim is the JWT field to use as the user's email.

allowedExtraClaims string[] ​

AllowedExtraClaims are claims of interest that are not part of User by default but may be provided by the OIDC provider.

usernamePrefix string ​

UsernamePrefix, if specified, causes claims mapping to username to be prefix with the provided value. A value "oidc:" would result in usernames like "oidc:john".

groupsClaim string ​

GroupsClaim, if specified, causes the OIDCAuthenticator to try to populate the user's groups with an ID Token field. If the GroupsClaim field is present in an ID Token the value must be a string or list of strings.

groups string[] ​

If required groups is non empty, access is denied if the user is not part of at least one of the specified groups.

scopes string[] ​

Scopes that should be sent to the server. If empty, defaults to "email" and "profile".

getUserInfo boolean ​

GetUserInfo, if specified, tells the OIDCAuthenticator to try to populate the user's information from the UserInfo.

groupsPrefix string ​

GroupsPrefix, if specified, causes claims mapping to group names to be prefixed with the value. A value "oidc:" would result in groups like "oidc:engineering" and "oidc:marketing".

type string ​

Type of the OIDC to show in the UI. Only for displaying purposes

resource string ​

Resource, if specified, is the value that is set for the "resource" URL parameter when making a request to the /token endpoint of the OIDC provider.

github object ​

Github holds github authentication configuration

clientId string ​

ClientID holds the github client id

clientSecret required string ​

ClientID holds the github client secret

redirectURI required string ​

RedirectURI holds the redirect URI. Should be https://loft.domain.tld/auth/github/callback

orgs object[] ​

Loft queries the following organizations for group information. Group claims are formatted as "(org):(team)". For example if a user is part of the "engineering" team of the "coreos" org, the group claim would include "coreos:engineering".

If orgs are specified in the config then user MUST be a member of at least one of the specified orgs to authenticate with loft.

name string ​

Organization name in github (not slug, full name). Only users in this github organization can authenticate.

teams string[] ​

Names of teams in a github organization. A user will be able to authenticate if they are members of at least one of these teams. Users in the organization can authenticate if this field is omitted from the config file.

hostName string ​

Required ONLY for GitHub Enterprise. This is the Hostname of the GitHub Enterprise account listed on the management console. Ensure this domain is routable on your network.

rootCA string ​

ONLY for GitHub Enterprise. Optional field. Used to support self-signed or untrusted CA root certificates.

gitlab object ​

Gitlab holds gitlab authentication configuration

clientId required string ​

Gitlab client id

clientSecret required string ​

Gitlab client secret

redirectURI required string ​

Redirect URI

baseURL string ​

BaseURL is optional, default = https://gitlab.com

groups string[] ​

Optional groups whitelist, communicated through the "groups" scope. If groups is omitted, all of the user's GitLab groups are returned. If groups is provided, this acts as a whitelist - only the user's GitLab groups that are in the configured groups below will go into the groups claim. Conversely, if the user is not in any of the configured groups, the user will not be authenticated.

google object ​

Google holds google authentication configuration

clientId required string ​

Google client id

clientSecret required string ​

Google client secret

redirectURI required string ​

loft redirect uri. E.g. https://loft.my.domain/auth/google/callback

scopes string[] ​

defaults to "profile" and "email"

hostedDomains string[] ​

Optional list of whitelisted domains If this field is nonempty, only users from a listed domain will be allowed to log in

groups string[] ​

Optional list of whitelisted groups If this field is nonempty, only users from a listed group will be allowed to log in

serviceAccountFilePath string ​

Optional path to service account json If nonempty, and groups claim is made, will use authentication from file to check groups with the admin directory api

adminEmail string ​

Required if ServiceAccountFilePath The email of a GSuite super user which the service account will impersonate when listing groups

microsoft object ​

Microsoft holds microsoft authentication configuration

clientId required string ​

Microsoft client id

clientSecret required string ​

Microsoft client secret

redirectURI required string ​

loft redirect uri. Usually https://loft.my.domain/auth/microsoft/callback

tenant string ​

tenant configuration parameter controls what kinds of accounts may be authenticated in loft. By default, all types of Microsoft accounts (consumers and organizations) can authenticate in loft via Microsoft. To change this, set the tenant parameter to one of the following:

common - both personal and business/school accounts can authenticate in loft via Microsoft (default) consumers - only personal accounts can authenticate in loft organizations - only business/school accounts can authenticate in loft tenant uuid or tenant name - only accounts belonging to specific tenant identified by either tenant uuid or tenant name can authenticate in loft

groups string[] ​

It is possible to require a user to be a member of a particular group in order to be successfully authenticated in loft.

onlySecurityGroups boolean ​

configuration option restricts the list to include only security groups. By default all groups (security, Office 365, mailing lists) are included.

useGroupsAsWhitelist boolean ​

Restrict the groups claims to include only the user’s groups that are in the configured groups

saml object ​

SAML holds saml authentication configuration

redirectURI string ​

If the response assertion status value contains a Destination element, it must match this value exactly. Usually looks like https://your-loft-domain/auth/saml/callback

ssoURL string ​

SSO URL used for POST value.

caData string ​

CAData is a base64 encoded string that holds the ca certificate for validating the signature of the SAML response. Either CAData, CA or InsecureSkipSignatureValidation needs to be defined.

usernameAttr string ​

Name of attribute in the returned assertions to map to username

emailAttr string ​

Name of attribute in the returned assertions to map to email

groupsAttr string ​

Name of attribute in the returned assertions to map to groups

ca string ​

CA to use when validating the signature of the SAML response.

insecureSkipSignatureValidation boolean ​

Ignore the ca cert

entityIssuer string ​

When provided Loft will include this as the Issuer value during AuthnRequest. It will also override the redirectURI as the required audience when evaluating AudienceRestriction elements in the response.

ssoIssuer string ​

Issuer value expected in the SAML response. Optional.

groupsDelim string ​

If GroupsDelim is supplied the connector assumes groups are returned as a single string instead of multiple attribute values. This delimiter will be used split the groups string.

allowedGroups string[] ​

List of groups to filter access based on membership

filterGroups boolean ​

If used with allowed groups, only forwards the allowed groups and not all groups specified.

nameIDPolicyFormat string ​

Requested format of the NameID. The NameID value is is mapped to the ID Token 'sub' claim.

This can be an abbreviated form of the full URI with just the last component. For example, if this value is set to "emailAddress" the format will resolve to:

urn:oasis:names:tc:SAML:1.1:nameid-format:emailAddress

If no value is specified, this value defaults to:

urn:oasis:names:tc:SAML:2.0:nameid-format:persistent

password object ​

Password holds password authentication relevant information

disabled boolean ​

If true login via password is disabled

connectors object[] ​

Connectors are optional additional connectors for Loft.

id string ​

ID is the id that should show up in the url

displayName string ​

DisplayName is the name that should show up in the ui

oidc object ​

OIDC holds oidc authentication configuration

issuerUrl string ​

IssuerURL is the URL the provider signs ID Tokens as. This will be the "iss" field of all tokens produced by the provider and is used for configuration discovery.

The URL is usually the provider's URL without a path, for example "https://accounts.google.com" or "https://login.salesforce.com".

The provider must implement configuration discovery. See: https://openid.net/specs/openid-connect-discovery-1_0.html#ProviderConfig

clientId string ​

ClientID the JWT must be issued for, the "sub" field. This plugin only trusts a single client to ensure the plugin can be used with public providers.

The plugin supports the "authorized party" OpenID Connect claim, which allows specialized providers to issue tokens to a client for a different client. See: https://openid.net/specs/openid-connect-core-1_0.html#IDToken

clientSecret string ​

ClientSecret to issue tokens from the OIDC provider

redirectURI string ​

loft redirect uri. E.g. https://loft.my.domain/auth/oidc/callback

postLogoutRedirectURI string ​

Loft URI to be redirected to after successful logout by OIDC Provider

caFile string ​

Path to a PEM encoded root certificate of the provider. Optional

insecureCa boolean ​

Specify whether to communicate without validating SSL certificates

preferredUsername string ​

Configurable key which contains the preferred username claims

loftUsernameClaim string ​

LoftUsernameClaim is the JWT field to use as the user's username.

usernameClaim string ​

UsernameClaim is the JWT field to use as the user's id.

emailClaim string ​

EmailClaim is the JWT field to use as the user's email.

allowedExtraClaims string[] ​

AllowedExtraClaims are claims of interest that are not part of User by default but may be provided by the OIDC provider.

usernamePrefix string ​

UsernamePrefix, if specified, causes claims mapping to username to be prefix with the provided value. A value "oidc:" would result in usernames like "oidc:john".

groupsClaim string ​

GroupsClaim, if specified, causes the OIDCAuthenticator to try to populate the user's groups with an ID Token field. If the GroupsClaim field is present in an ID Token the value must be a string or list of strings.

groups string[] ​

If required groups is non empty, access is denied if the user is not part of at least one of the specified groups.

scopes string[] ​

Scopes that should be sent to the server. If empty, defaults to "email" and "profile".

getUserInfo boolean ​

GetUserInfo, if specified, tells the OIDCAuthenticator to try to populate the user's information from the UserInfo.

groupsPrefix string ​

GroupsPrefix, if specified, causes claims mapping to group names to be prefixed with the value. A value "oidc:" would result in groups like "oidc:engineering" and "oidc:marketing".

type string ​

Type of the OIDC to show in the UI. Only for displaying purposes

resource string ​

Resource, if specified, is the value that is set for the "resource" URL parameter when making a request to the /token endpoint of the OIDC provider.

github object ​

Github holds github authentication configuration

clientId string ​

ClientID holds the github client id

clientSecret required string ​

ClientID holds the github client secret

redirectURI required string ​

RedirectURI holds the redirect URI. Should be https://loft.domain.tld/auth/github/callback

orgs object[] ​

Loft queries the following organizations for group information. Group claims are formatted as "(org):(team)". For example if a user is part of the "engineering" team of the "coreos" org, the group claim would include "coreos:engineering".

If orgs are specified in the config then user MUST be a member of at least one of the specified orgs to authenticate with loft.

name string ​

Organization name in github (not slug, full name). Only users in this github organization can authenticate.

teams string[] ​

Names of teams in a github organization. A user will be able to authenticate if they are members of at least one of these teams. Users in the organization can authenticate if this field is omitted from the config file.

hostName string ​

Required ONLY for GitHub Enterprise. This is the Hostname of the GitHub Enterprise account listed on the management console. Ensure this domain is routable on your network.

rootCA string ​

ONLY for GitHub Enterprise. Optional field. Used to support self-signed or untrusted CA root certificates.

gitlab object ​

Gitlab holds gitlab authentication configuration

clientId required string ​

Gitlab client id

clientSecret required string ​

Gitlab client secret

redirectURI required string ​

Redirect URI

baseURL string ​

BaseURL is optional, default = https://gitlab.com

groups string[] ​

Optional groups whitelist, communicated through the "groups" scope. If groups is omitted, all of the user's GitLab groups are returned. If groups is provided, this acts as a whitelist - only the user's GitLab groups that are in the configured groups below will go into the groups claim. Conversely, if the user is not in any of the configured groups, the user will not be authenticated.

google object ​

Google holds google authentication configuration

clientId required string ​

Google client id

clientSecret required string ​

Google client secret

redirectURI required string ​

loft redirect uri. E.g. https://loft.my.domain/auth/google/callback

scopes string[] ​

defaults to "profile" and "email"

hostedDomains string[] ​

Optional list of whitelisted domains If this field is nonempty, only users from a listed domain will be allowed to log in

groups string[] ​

Optional list of whitelisted groups If this field is nonempty, only users from a listed group will be allowed to log in

serviceAccountFilePath string ​

Optional path to service account json If nonempty, and groups claim is made, will use authentication from file to check groups with the admin directory api

adminEmail string ​

Required if ServiceAccountFilePath The email of a GSuite super user which the service account will impersonate when listing groups

microsoft object ​

Microsoft holds microsoft authentication configuration

clientId required string ​

Microsoft client id

clientSecret required string ​

Microsoft client secret

redirectURI required string ​

loft redirect uri. Usually https://loft.my.domain/auth/microsoft/callback

tenant string ​

tenant configuration parameter controls what kinds of accounts may be authenticated in loft. By default, all types of Microsoft accounts (consumers and organizations) can authenticate in loft via Microsoft. To change this, set the tenant parameter to one of the following:

common - both personal and business/school accounts can authenticate in loft via Microsoft (default) consumers - only personal accounts can authenticate in loft organizations - only business/school accounts can authenticate in loft tenant uuid or tenant name - only accounts belonging to specific tenant identified by either tenant uuid or tenant name can authenticate in loft

groups string[] ​

It is possible to require a user to be a member of a particular group in order to be successfully authenticated in loft.

onlySecurityGroups boolean ​

configuration option restricts the list to include only security groups. By default all groups (security, Office 365, mailing lists) are included.

useGroupsAsWhitelist boolean ​

Restrict the groups claims to include only the user’s groups that are in the configured groups

saml object ​

SAML holds saml authentication configuration

redirectURI string ​

If the response assertion status value contains a Destination element, it must match this value exactly. Usually looks like https://your-loft-domain/auth/saml/callback

ssoURL string ​

SSO URL used for POST value.

caData string ​

CAData is a base64 encoded string that holds the ca certificate for validating the signature of the SAML response. Either CAData, CA or InsecureSkipSignatureValidation needs to be defined.

usernameAttr string ​

Name of attribute in the returned assertions to map to username

emailAttr string ​

Name of attribute in the returned assertions to map to email

groupsAttr string ​

Name of attribute in the returned assertions to map to groups

ca string ​

CA to use when validating the signature of the SAML response.

insecureSkipSignatureValidation boolean ​

Ignore the ca cert

entityIssuer string ​

When provided Loft will include this as the Issuer value during AuthnRequest. It will also override the redirectURI as the required audience when evaluating AudienceRestriction elements in the response.

ssoIssuer string ​

Issuer value expected in the SAML response. Optional.

groupsDelim string ​

If GroupsDelim is supplied the connector assumes groups are returned as a single string instead of multiple attribute values. This delimiter will be used split the groups string.

allowedGroups string[] ​

List of groups to filter access based on membership

filterGroups boolean ​

If used with allowed groups, only forwards the allowed groups and not all groups specified.

nameIDPolicyFormat string ​

Requested format of the NameID. The NameID value is is mapped to the ID Token 'sub' claim.

This can be an abbreviated form of the full URI with just the last component. For example, if this value is set to "emailAddress" the format will resolve to:

urn:oasis:names:tc:SAML:1.1:nameid-format:emailAddress

If no value is specified, this value defaults to:

urn:oasis:names:tc:SAML:2.0:nameid-format:persistent

disableTeamCreation boolean ​

Prevents from team creation for the new groups associated with the user at the time of logging in through sso, Default behaviour is false, this means that teams will be created for new groups.

disableUserCreation boolean ​

DisableUserCreation prevents the SSO connectors from creating a new user on a users initial signin through sso. Default behaviour is false, this means that a new user object will be created once a user without a Kubernetes user object logs in.

accessKeyMaxTTLSeconds integer ​

AccessKeyMaxTTLSeconds is the global maximum lifespan of an accesskey in seconds. Leaving it 0 or unspecified will disable it. Specifying 2592000 will mean all keys have a Time-To-Live of 30 days.

loginAccessKeyTTLSeconds integer ​

LoginAccessKeyTTLSeconds is the time in seconds an access key is kept until it is deleted. Leaving it unspecified will default to 20 days. Setting it to zero will disable the ttl. Specifying 2592000 will mean all keys have a default Time-To-Live of 30 days.

customHttpHeaders object ​

CustomHttpHeaders are additional headers that should be set for the authentication endpoints

groupsFilters string[] ​

GroupsFilters is a regex expression to only save matching sso groups into the user resource

TenantConfig (Get)​

Retrieve the tenant's current configuration.

Run the following command:

# Exchange development in the url below with the name of the Tenant
kubectl get --raw "/kubernetes/management/apis/management.loft.sh/v1/tenants/development/config"

TenantConfig (Create)​

Replace the tenant's entire configuration. Include all settings that should remain configured.

Create a file object.yaml with the following contents:

apiVersion: management.loft.sh/v1
kind: TenantConfig
metadata:
name: development
spec:
hostnames:
- hostname: development.example.com

Then run the following curl command:

# Exchange development in the url below with the name of the Tenant
curl -s -X POST --insecure \
"https://$LOFT_DOMAIN/kubernetes/management/apis/management.loft.sh/v1/tenants/development/config" \
--data-binary "$(cat object.yaml)" \
-H "Content-Type: application/yaml" \
-H "Authorization: Bearer $ACCESS_KEY"