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

     1  ---
     2  title: Short-lived token (STS like) Authentication for lakeFS
     3  description: Authenticate with lakeFS using Secure Token Service (STS) by leveraging a remote authenticator. This feature enables integration with Identity Providers (IdPs) for secure and efficient user authentication.
     4  grand_parent: Reference
     5  parent: Security
     6  redirect_from:
     7    - /reference/remote-authenticator.html
     8  ---
     9  
    10  # Short-lived token (STS like)
    11  
    12  {: .d-inline-block }
    13  <a style="color: white;" href="#sso-for-lakefs-cloud">lakeFS Cloud</a>
    14  {: .label .label-green }
    15  
    16  {: .d-inline-block }
    17  <a style="color: white;" href="#sso-for-lakefs-enterprise">lakeFS Enterprise</a>
    18  {: .label .label-purple }
    19  
    20  {: .note}
    21  > STS Login is available in lakeFS Cloud and lakeFS Enterprise. currently only tested on lakeFS Enterprise.
    22  
    23  Secure Token Service (STS) authentication in lakeFS enables users to authenticate to lakeFS using temporary credentials obtained from an Identity Provider (IdP) via the OpenID Connect (OIDC) Authentication workflow.
    24  This document outlines the process, from setting up the STS authentication flow to using temporary credentials to interact with lakeFS through the [high-level Python SDK](../../integrations/python.md).
    25  
    26  
    27  
    28  ## Login
    29  
    30  From the Python SDK call `from_web_identity` to initiate a client session with temporary credentials:
    31  
    32  ```python
    33  import lakefs
    34  myclient = lakefs.client.from_web_identity(code = '<CODE_FROM_IDP>', state = '<STATE_FROM_IDP>' , redirect_uri = '<URI_USED_FOR_REDIRECT_FROM_IDP>', ttl_seconds = 7200)
    35  ```
    36  
    37  ## Setup
    38  
    39  ### Prerequisites
    40  Asure you have a way to generate the code, redirect_uri and state values that are required to initiate a new client session using the STS login feature.
    41  For a reference implementation, see the [Sample implementation](#sample-implementation-to-generate-the-code-redirect_uri-and-state) section.
    42  
    43  ### Configuration
    44  
    45  To enable STS authentication, configure your lakeFS instance with the endpoint of the external Authentication Service.
    46  
    47  
    48  ```yaml
    49  
    50  auth:
    51      authentication_api:
    52          endpoint: <url-to-remote-authenticator-endpoint>
    53  
    54  
    55  ```
    56  
    57  - `auth.authentication_api.endpoint` `(string: https://external.authentication-service/api/v1)` - URL to external Authentication Service described at [authentication.yml](https://github.com/treeverse/lakeFS/blob/master/api/authentication.yml)
    58  
    59  Ensure you replace <url-to-remote-authenticator-endpoint> with the actual URL of your Authentication Service.
    60  
    61  
    62  ### Sample implementation to generate the code, redirect_uri and state
    63  
    64  The following code snippet demonstrates how to generate the code, redirect_uri and state values that are required to initiate a new client session using the STS login feature.
    65  replace `<Your-auth-client-id>` with your auth client id and `<path-to-your-idp-authorize>` with the path to your IdP authorize endpoint.
    66  e.g in case of Auth0, the authorize endpoint is `https://<your-auth0-domain>/authorize` in case of entra the authorize endpoint is `https://<your-entra-domain>/oauth2/v2.0/authorize`
    67  ```javascript
    68  import crypto from 'crypto';
    69  
    70  import express from 'express';
    71  import axios from 'axios';
    72  import url from 'url';
    73  import jsonwebtoken from 'jsonwebtoken';
    74  const app = express();
    75  
    76  
    77  const authClientId = '<Your-auth-client-id>'
    78  // the local script will will spin up the server and the IdP provider will return to this endpoint the response.
    79  const callback = "http://localhost:8080/oidc/callback"
    80  
    81  // step 1 
    82  // Create a code_verifier, which is a cryptographically-random, Base64-encoded key that will eventually be sent to Auth0 to request tokens.
    83  function base64URLEncode(str) {
    84      return str.toString('base64')
    85          .replace(/\+/g, '-')
    86          .replace(/\//g, '_')
    87          .replace(/=/g, '');
    88  }
    89  var verifier = base64URLEncode(crypto.randomBytes(32));
    90  console.log(`verifier: ${verifier}`);
    91  
    92  // step 2 
    93  // Generate a code_challenge from the code_verifier that will be sent to Auth0 to request an authorization_code.
    94  function sha256(buffer) {
    95      return crypto.createHash('sha256').update(buffer).digest();
    96  }
    97  
    98  var challenge = base64URLEncode(sha256(verifier));
    99  console.log(`challenge: ${challenge}`);
   100  
   101  
   102  const authorizeURL = `https://<path-to-your-idp-authorize>?response_type=code&code_challenge=${challenge}&code_challenge_method=S256&client_id=${auth0ClientId}&redirect_uri=${callback}&scope=openid&state=${verifier}`
   103  
   104  console.log(`authorizeURL: ${authorizeURL}`)
   105  
   106  // Endpoint for OIDC callback
   107  app.get('/oidc/callback', async (req, res) => {
   108      try {
   109          const code = req.query.code;
   110          const state = req.query.state;
   111          console.log(`code: ${code}`);
   112          console.log(`state: ${state}`);
   113          // Return a success response
   114          res.status(200).json({ code, state, redirect_uri: callback, python-cmd: `lakefs.client.from_web_identity(code = ${code} redirect_uri = ${callback} state = ${state}, ttl_seconds = 7200) ` });
   115          return
   116      } catch (err) {
   117          console.error(err);
   118          res.status(500).json({ message: 'Internal server error' });
   119      }
   120  });
   121  
   122  // Start the server
   123  const PORT = 8080;
   124  app.listen(PORT, () => {
   125      console.log(`Server is running on port ${PORT}`);
   126  });
   127  ```
   128  
   129  
   130  ## Architecture
   131  
   132  {: .note}
   133  > The architecture documentation begins at the stage [after the generation of the code by the Idp](#prerequisites).
   134  
   135  The STS authentication flow involves several components that facilitate secure communication between the lakeFS client, lakeFS server, the remote authenticator, and the IdP.
   136  
   137  ```mermaid
   138  sequenceDiagram
   139      participant A as lakeFS Client
   140      participant B as lakeFS Server
   141      participant C as Remote Authenticator
   142      participant D as IdP
   143      A->>B: Call STS login endpoint
   144      B->>C: POST idp code state and redirect uri
   145      C->>D: IdP request
   146      D->>C: IdP response
   147      C->>B: Auth response
   148      B->>A: auth JWT
   149  ```
   150  - lakeFS Client: Initiates the authentication process by providing IdP credentials.
   151  - lakeFS Server: Facilitates the authentication request between the client and the remote authenticator.
   152  - Remote Authenticator: Acts as a bridge between lakeFS and the IdP, handling credential validation.
   153  - IdP (Identity Provider): Validates the provided credentials and returns the authentication status.
   154