github.com/treeverse/lakefs@v1.24.1-0.20240520134607-95648127bfb0/docs/reference/security/authentication.md (about)

     1  ---
     2  title: Authentication 
     3  description: This section covers Authentication of your lakeFS server.
     4  grand_parent: Reference
     5  parent: Security
     6  redirect_from:
     7    - /reference/authentication.html
     8  ---
     9  
    10  # Authentication 
    11  
    12  {% include toc_2-3.html %}
    13  
    14  ## Authentication
    15  
    16  ### User Authentication
    17  
    18  lakeFS authenticates users from a built-in authentication database.
    19  
    20  #### Built-in database
    21  
    22  The built-in authentication database is always present and active. You can use the
    23  Web UI at Administration / Users to create users. Users have an access key
    24  `AKIA...` and an associated secret access key. These credentials are valid
    25  for logging into the Web UI or authenticating programmatic requests to the API
    26  Server or the S3 Gateway.
    27  
    28  #### Remote Authenticator Service 
    29  
    30  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.
    31  To configure a Remote Authenticator see the [configuration fields]({% link reference/configuration.md %}#authentication-and-authorization).
    32  
    33  ### API Server Authentication
    34  
    35  Authenticating against the API server is done using a key-pair, passed via [Basic Access Authentication](https://en.wikipedia.org/wiki/Basic_access_authentication).
    36  
    37  All HTTP requests must carry an `Authorization` header with the following structure:
    38  
    39  ```text
    40  Authorization: Basic <base64 encoded access_key_id:secret_access_key>
    41  ```
    42  
    43  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:
    44  
    45  ```text
    46  Authorization: Basic bXlfYWNjZXNzX2tleV9pZDpteV9hY2Nlc3Nfc2VjcmV0X2tleQ==
    47  ```
    48  
    49  
    50  ### S3 Gateway Authentication
    51  
    52  To provide API compatibility with Amazon S3, authentication with the S3 Gateway supports both [SIGv2](https://docs.aws.amazon.com/general/latest/gr/signature-version-2.html){:target="_blank"} and [SIGv4](https://docs.aws.amazon.com/general/latest/gr/signature-version-4.html){:target="_blank"}.
    53  Clients such as the AWS SDK that implement these authentication methods should work without modification.
    54  
    55  See [this example for authenticating with the AWS CLI]({% link integrations/aws_cli.md %}).
    56  
    57  
    58  ## OIDC support
    59  
    60  **Note**
    61  This feature is deprecated. For single sign-on with lakeFS, try [lakeFS Cloud](https://lakefs.cloud)
    62  {: .note }
    63  
    64  OpenID Connect (OIDC) is a simple identity layer on top of the OAuth 2.0 protocol.
    65  You can configure lakeFS to enable OIDC to manage your lakeFS users externally. 
    66  Essentially, once configured, this enables you the benefit of OpenID connect, such as a single sign-on (SSO), etc. 
    67  
    68  ### Configuring lakeFS server for OIDC
    69  
    70  To support OIDC, add the following to your [lakeFS configuration]({% link reference/configuration.md %}):
    71  
    72  ```yaml
    73  auth:
    74    oidc:
    75      enabled: true
    76      client_id: example-client-id
    77      client_secret: exampleSecretValue
    78      callback_base_url: https://lakefs.example.com       # The scheme, domain (and port) of your lakeFS installation
    79      url: https://my-account.oidc-provider-example.com
    80      default_initial_groups: ["Developers"]
    81      friendly_name_claim_name: name                      #  Optional: use the value from this claim as the user's display name
    82      persist_friendly_name: true                         #  Optional: persist friendly name to KV store so it can be displayed in the user list
    83  ```
    84  
    85  Your login page will now include a link to sign in using the 
    86  OIDC provider. When a user first logs in through the provider, a corresponding user is created in lakeFS.
    87  
    88  #### Friendly Name Persistence
    89  
    90  When the `persist_friendly_name` configuration property is set to `true` **and** `friendly_name_claim_name` is set to a valid claim name, which exists in the incoming `id_token`, the friendly name will be persisted to the KV store. This will allow users with access to the lakeFS administration section to see friendly names in the users list, when listing group members, and when adding/removing group members.  
    91  The friendly name stored in KV is updated with each successful login, if the incoming value is different than the stored value. This means it will be kept up-to-date with changes to the user's profile or if `friendly_name_claim_name` is re-configured.
    92  
    93  #### Notes
    94  {: .no_toc}
    95  1. As always, you may choose to provide these configurations using [environment variables]({% link reference/configuration.md %}).
    96  2. You may already have other configuration values under the _auth_ key, so make sure you combine them correctly.
    97  
    98  ## User permissions
    99  
   100  Authorization is managed via [lakeFS groups and policies]({% link reference/security/rbac.md %}}).
   101  
   102  By default, an externally managed user is assigned to the lakeFS groups configured in the _default_initial_groups_ property above.
   103  For a user to be assigned to other groups, add the _initial_groups_ claim to their **ID token** claims. The claim should contain a
   104  comma-separated list of group names.
   105  
   106  Once the user has been created, you can manage their permissions from the Administration pages in the lakeFS UI or using _lakectl_.
   107  
   108  ### Using a different claim name
   109  
   110  To supply the initial groups using another claim from your ID token, you can use the `auth.oidc.initial_groups_claim_name` 
   111  lakeFS configuration. For example, to take the initial groups from the _roles_ claim, add:
   112  
   113  ```yaml
   114  auth:
   115    oidc:
   116      # ... Other OIDC configurations
   117      initial_groups_claim_name: roles
   118  ```