Table of contents
lakeFS authenticates users from a built-in authentication database.
The built-in authentication database is always present and active. You can use the
Web UI at Administration / Users to create users. Users have an access key
AKIA... and an associated secret access key. These credentials are valid
for logging into the Web UI or authenticating programmatic requests to the API
Server or the S3 Gateway.
Remote Authenticator Service
lakeFS server supports external authentication, the feature can be configured by providing an HTTP endpoint to an external authentication service. This integration can be especially useful if you already have an existing authentication system in place, as it allows you to reuse that system instead of maintaining a new one. To configure a Remote Authenticator see the configuration fields.
Note This feature is deprecated (learn more). For single sign-on with lakeFS, try lakeFS Cloud
Configure lakeFS to authenticate users on an LDAP server. Once configured, users can additionally log into lakeFS using their credentials LDAP. These users may then generate an access key and a secret access key on the Web UI at Administration / My Credentials. lakeFS generates an internal user once logged in via the LDAP server. Adding this internal user to a group allows assigning them a different policy.
Configure the LDAP server using the configuration fields:
ldap:) URL of the LDAP server.
bind_password: Credentials for lakeFS to use to query the LDAP server for users. They must identify a user with Basic Authentication, and are used to convert a user ID attribute to a full user DN.
default_user_group: A group to add users the first time they log in using LDAP. Typically
Once logged in, LDAP users may be added as normal to any other group.
username_attribute: Attribute on LDAP user to identify user when logging in. Typically
user_base_dn: DN of root of DAP tree containing users, e.g.
user_filter: An additional filter for users allowed to login, e.g.
LDAP users log in using the following flow:
- Bind the lakeFS control connection to
- Receive an LDAP user-ID (e.g. “joebloggs”) and a password entered on the Web UI login page.
- Attempt to log in as internally-defined users; fail.
Search the LDAP server using the control connection for the user: out of all users under
user_filter, there must be a single user whose
username_attributewas specified by the user. Get their DN.
In our example, this may be
uid=joebloggs,ou=Users,dc=treeverse,dc=io(this entry must have
objectClass: personbecause of
- Attempt to bind the received DN on the LDAP server using the password.
- On success, the user is authenticated.
- Create a new internal user with that DN if needed. When creating a user,
add them to the internal group named
API Server Authentication
Authenticating against the API server is done using a key-pair, passed via Basic Access Authentication.
All HTTP requests must carry an
Authorization header with the following structure:
Authorization: Basic <base64 encoded access_key_id:secret_access_key>
For example, assuming my access_key_id is
my_access_key_id and my secret_access_key is
my_secret_access_key, we’d send the following header with every request:
Authorization: Basic bXlfYWNjZXNzX2tleV9pZDpteV9hY2Nlc3Nfc2VjcmV0X2tleQ==
S3 Gateway Authentication
To provide API compatibility with Amazon S3, authentication with the S3 Gateway supports both SIGv2 and SIGv4. Clients such as the AWS SDK that implement these authentication methods should work without modification.
See this example for authenticating with the AWS CLI.
Note This feature is deprecated. For single sign-on with lakeFS, try lakeFS Cloud
OpenID Connect (OIDC) is a simple identity layer on top of the OAuth 2.0 protocol. You can configure lakeFS to enable OIDC to manage your lakeFS users externally. Essentially, once configured, this enables you the benefit of OpenID connect, such as a single sign-on (SSO), etc.
Configuring lakeFS server for OIDC
To support OIDC, add the following to your lakeFS configuration:
auth: oidc: enabled: true client_id: example-client-id client_secret: exampleSecretValue callback_base_url: https://lakefs.example.com # The scheme, domain (and port) of your lakeFS installation url: https://my-account.oidc-provider-example.com default_initial_groups: ["Developers"] friendly_name_claim_name: name # Optional: use the value from this claim as the user's display name
Your login page will now include a link to sign in using the OIDC provider. When a user first logs in through the provider, a corresponding user is created in lakeFS.
- As always, you may choose to provide these configurations using environment variables.
- You may already have other configuration values under the auth key, so make sure you combine them correctly.
Authorization is managed via lakeFS groups and policies.
By default, an externally managed user is assigned to the lakeFS groups configured in the default_initial_groups property above. For a user to be assigned to other groups, add the initial_groups claim to their ID token claims. The claim should contain a comma-separated list of group names.
Once the user has been created, you can manage their permissions from the Administration pages in the lakeFS UI or using lakectl.
Using a different claim name
To supply the initial groups using another claim from your ID token, you can use the
lakeFS configuration. For example, to take the initial groups from the roles claim, add:
auth: oidc: # ... Other OIDC configurations initial_groups_claim_name: roles