본문 바로가기
WIKI 기술 지식 베이스

Single Sign On

원문 보기 위키 갱신

Single Sign On (SSO)

lakeFS Team과 lakeFS Enterprise에서 사용할 수 있어요. 무료 체험을 시작하거나 문의하세요.

출처: Single Sign On (SSO)

본문

lakeFS Cloud를 위한 SSO

lakeFS Cloud는 인증에 Auth0를 사용하기 때문에 Auth0가 지원하는 것과 동일한 아이덴티티 프로바이더를 지원해요. Active Directory/LDAP, ADFS, Azure Active Directory Native, Google Workspace, OpenID Connect, Okta, PingFederate, SAML, Azure Active Directory가 포함돼요.

Okta

Note

이 가이드는 Okta's Create OIDC app integrations guide를 기반으로 해요.

단계:

  • Okta 계정에 로그인해요

  • Applications > Applications를 선택한 다음 Create App Integration을 선택해요.

  • Create New App을 선택하고 다음을 입력해요:

  • Sign-in method에 대해 OIDC를 선택해요.

  • Application type 아래에서 Web app을 선택해요.

  • Next를 선택해요.

  • General Settings 아래에서:

  • App integration name에 애플리케이션의 이름을 입력해요. (예. lakeFS Cloud)

  • Sign-in redirect URIs 필드에 https://lakefs-cloud.us.auth0.com/login (미국) 또는 https://lakefs-cloud.eu.auth0.com/login (유럽)을 입력해요.

  • Sign-in redirect URIs 아래에서 Add URI를 클릭하고 https://lakefs-cloud.us.auth0.com/login/callback (미국) 또는 https://lakefs-cloud.eu.auth0.com/login/callback (유럽)을 입력해요.

  • Assignments 아래에서 원하는 Controlled access를 선택해요. (예. Allow everyone in your organization to access)

  • Enable immediate access with Federation Broker Mode의 체크를 해제해요.

  • Save를 선택해요.

Okta에 애플리케이션 등록을 마치면, Client ID, Client Secret, Okta Domain을 저장하고 Treeverse 팀에 보내 통합을 완료하세요.

Active Directory Federation Services (AD FS)

사전 요구 사항:

  • 클라이언트의 AD FS 서버가 공개적으로 또는 Auth0의 IP 범위로 노출되어야 해요(직접 또는 Web Application Proxy 사용).

단계:

  • AD FS 서버에 연결해요

  • 서버 관리자를 통해 AD FS의 PowerShell CLI를 Administrator로 열어요

  • 다음을 실행해요:

(new-object Net.WebClient -property @{Encoding = [Text.Encoding]::UTF8}).DownloadString("https://raw.github.com/auth0/adfs-auth0/master/adfs.ps1") | iex

AddRelyingParty "urn:auth0:lakefs-cloud" "https://lakefs-cloud.us.auth0.com/login/callback"

Note 조직 데이터가 유럽에 있다면 lakefs-cloud.us.auth0.com 대신 lakefs-cloud.eu.auth0.com을 사용하세요.

lakeFS Cloud의 AD FS 등록을 마치면 AD FS URL을 저장하고 Treeverse 팀에 보내 통합을 완료하세요.

Azure Active Directory (AD)

사전 요구 사항:

  • Azure Active Directory에서 애플리케이션을 관리할 권한이 있는 Azure 계정

Note

이미 Azure 계정으로 lakeFS Cloud를 설정했다면 아래의 Register lakeFS Cloud with Azure와 Add a secret 단계를 건너뛰고 바로 Add a redirect URI로 가도 돼요.

Register lakeFS Cloud with Azure

단계:

  • Azure 포털에 로그인해요.

  • 여러 테넌트에 접근 권한이 있다면, 상단 메뉴의 Directories + subscriptions 필터를 사용해 애플리케이션을 등록하려는 테넌트로 전환해요.

  • Azure Active Directory를 검색하고 선택해요.

  • Manage 아래에서 App registrations > New registration을 선택해요.

  • 애플리케이션의 표시 이름(display Name)을 입력해요. 애플리케이션 사용자는 앱을 사용할 때(예: 로그인 중) 표시 이름을 볼 수 있어요. 표시 이름은 언제든 바꿀 수 있고 여러 앱 등록이 같은 이름을 공유할 수 있어요. 앱 등록이 자동 생성한 Application (client) ID가 표시 이름이 아니라 아이덴티티 플랫폼 내에서 앱을 고유하게 식별해요.

  • 누가 애플리케이션을 사용할 수 있는지 지정해요. 흔히 sign-in audience라고 불려요.

Note Redirect URI (optional)에는 아무 것도 입력하지 마세요. 다음 섹션에서 redirect URI를 설정하게 돼요.

  • 초기 앱 등록을 완료하려면 Register를 선택해요.

등록이 끝나면 Azure 포털이 앱 등록의 Overview 창을 보여줘요. Application (client) ID가 보이죠. client ID라고도 불리는 이 값은 Microsoft 아이덴티티 플랫폼에서 애플리케이션을 고유하게 식별해요.

Important: 새 앱 등록은 기본으로 사용자에게 숨겨져 있어요. 사용자가 My Apps 페이지에서 앱을 볼 준비가 되면 활성화할 수 있어요. 앱을 활성화하려면 Azure 포털에서 Azure Active Directory > Enterprise applications로 이동해 앱을 선택하세요. 그다음 Properties 페이지에서 Visible to users? 토글을 Yes로 바꿔요.

Add a secret

가끔 application password라고도 불리는 client secret은 애플리케이션이 인증서 대신 자신을 식별하기 위해 사용할 수 있는 문자열 값이에요.

단계:

  • Azure 포털의 App registrations에서 애플리케이션을 선택해요.

  • Certificates & secrets > Client secrets > New client secret을 선택해요.

  • client secret에 대한 설명을 추가해요.

  • 시크릿의 만료를 선택하거나 커스텀 수명을 지정해요.

  • client secret 수명은 2년(24개월) 이하로 제한돼요. 24개월보다 긴 커스텀 수명은 지정할 수 없어요.

  • Microsoft는 만료 값을 12개월 미만으로 설정할 것을 권장해요.

  • Add를 선택해요.

  • 클라이언트 애플리케이션 코드에서 사용할 시크릿 값을 기록해 두세요. 이 시크릿 값은 이 페이지를 벗어나면 다시는 표시되지 않아요.

Add a redirect URI redirect URI는 인증 후 Microsoft 아이덴티티 플랫폼이 사용자의 클라이언트를 리다이렉트하고 보안 토큰을 보내는 위치예요.

등록한 애플리케이션의 redirect URI는 플랫폼 설정을 구성해 추가하고 수정해요.

redirect URI로 https://lakefs-cloud.us.auth0.com/login/callback을 입력해요.

redirect URI를 포함한 각 애플리케이션 유형의 설정은 Azure 포털의 Platform configurations에서 구성돼요. Web과 Single-page 애플리케이션 같은 일부 플랫폼은 redirect URI를 수동으로 지정해야 해요. 모바일과 데스크톱 같은 다른 플랫폼은 다른 설정을 구성할 때 생성된 redirect URI에서 선택할 수 있어요.

단계:

  • Azure 포털의 App registrations에서 애플리케이션을 선택해요.

  • Manage 아래에서 Authentication을 선택해요.

  • Platform configurations 아래에서 Add a platform을 선택해요.

  • Configure platforms 아래에서 web 옵션을 선택해요.

  • 플랫폼 구성을 완료하려면 Configure를 선택해요.

lakeFS Cloud의 Azure AD 등록을 마치면 다음 항목들을 Treeverse 팀에 보내세요:

  • Client ID

  • Client Secret

  • Azure AD Domain

  • Identity API Version (Azure AD는 v1, Microsoft Identity Platform/Entra는 v2)

lakeFS Enterprise를 위한 SSO

v1.63.0부터 lakeFS Enterprise의 인증은 lakeFS Enterprise 서비스가 직접 처리해요. lakeFS Enterprise는 다음 아이덴티티 프로바이더를 지원해요:

  • Active Directory Federation Services (AD FS) (SAML 사용)

  • OpenID Connect

  • LDAP

  • External AWS Authentication (IAM 사용)

나열되지 않은 인증 프로바이더를 사용 중이라면 추가 지원을 위해 문의하세요.

Allowing only SSO

SSO를 유일한 인증 방법으로 만들려면 - access key를 비활성화하려면 - auth.allowed_authentication_methods로 허용 방식을 제한하세요.

Populating user email from a claim

SAML과 OIDC 모두에서 lakeFS Enterprise는 사용자 생성 시점에 IdP 클레임에서 사용자 이메일을 채울 수 있어요. email_claim_name을 설정하면 돼요(SAML은 cookie_auth_verification 아래, OIDC는 oidc 아래). lakeFS는 클레임이 토큰에 있을 때만 읽을 수 있으니 IdP가 제공하는지 확인하세요 - OIDC라면 auth.providers.oidc.additional_scope_claims에 email을 추가해 관련 scope를 요청하세요. 이메일은 사용자가 처음 만들어질 때만 설정되고, 클레임이 없거나 비어 있으면 설정되지 않으며 기존 사용자는 현재 이메일을 유지해요.

Active Directory Federation Services (AD FS) (SAML 사용)

Note

AD FS 통합은 lakeFS Enterprise가 내보내는 요청에 서명·암호화하고 AD FS 서버로부터 들어오는 요청을 복호화하는 데 인증서를 사용해요.

OpenSSL로 자체 서명 인증서를 생성하고 싶다면:

openssl req -x509 -newkey rsa:2048 -keyout myservice.key -out myservice.cert -days 365 -nodes -subj "/CN=lakefs.company.com"

SAML 인증이 동작하려면 chart의 values.yaml 파일에 다음 값을 설정해요:

ingress:
  enabled: true
  ingressClassName: <class-name>
  hosts:
    - host: <lakefs.ingress.domain>
      paths:
        - /

enterprise:
  enabled: true
  auth:
    saml:
      enabled: true
      createCertificateSecret: true  # NEW: Auto-creates secret
      certificate:
        samlRsaPublicCert: |           # RENAMED: from saml_rsa_public_cert
          -----BEGIN CERTIFICATE-----
          ...
          -----END CERTIFICATE-----
        samlRsaPrivateKey: |           # RENAMED: from saml_rsa_private_key
          [REDACTED PRIVATE KEY]

image:
  privateRegistry:
    enabled: true
    secretToken: <dockerhub-token>

lakefsConfig: |
  blockstore:
    type: local
  auth:
    logout_redirect_url: https://<lakefs.ingress.domain>
    cookie_auth_verification:
      auth_source: saml
      # claim name to display user in the UI
      friendly_name_claim_name: displayName
      # claim name to use as the user's email when the user is first created
      email_claim_name: email
      # claim name from IDP to use as the unique user name
      external_user_id_claim_name: samName
      default_initial_groups:
        - "Developers"
    providers:
      saml:
        post_login_redirect_url: https://<lakefs.ingress.domain>
        sp_root_url: https://<lakefs.ingress.domain>
        sp_sign_request: true
        # depends on IDP
        sp_signature_method: "http://www.w3.org/2001/04/xmldsig-more#rsa-sha256"
        # url to the metadata of the IDP
        idp_metadata_url: "https://<adfs-auth.company.com>/federationmetadata/2007-06/federationmetadata.xml"
        # IDP SAML claims format default unspecified
        idp_authn_name_id_format: "urn:oasis:names:tc:SAML:1.1:nameid-format:unspecified"
        # depending on IDP setup, if CA certs are self signed and not trusted by a known CA
        #idp_skip_verify_tls_cert: true

OpenID Connect

OIDC가 동작하려면 chart의 values.yaml 파일에 다음 값을 설정해요:

ingress:
  enabled: true
  ingressClassName: <class-name>
  hosts:
    - host: <lakefs.ingress.domain>
      paths:
        - /

enterprise:
  enabled: true
  auth:
    oidc:
      enabled: true
      # secret given by the OIDC provider (e.g auth0, Okta, etc)
      client_secret: <oidc-client-secret>

image:
  privateRegistry:
    enabled: true
    secretToken: <dockerhub-token>

lakefsConfig: |
  blockstore:
    type: local
  auth:
    logout_redirect_url: https://oidc-provider-url.com/logout/example
    oidc:
      friendly_name_claim_name: <some-oidc-provider-claim-name>
      # claim name to use as the user's email when the user is first created
      email_claim_name: email
      default_initial_groups: ["Developers"]
    providers:
      oidc:
        post_login_redirect_url: /
        url: https://oidc-provider-url.com/
        client_id: <oidc-client-id>
        callback_base_url: https://<lakefs.ingress.domain>
        # the claim name that represents the client identifier in the OIDC provider (e.g Okta)
        logout_client_id_query_parameter: client_id
        # query parameters used to redirect the user to the OIDC provider (e.g., Okta) after logout.
        # If you are using `auth.ui_config.login_url_method: select` and want to redirect
        # back to the login selection page, set the return address to lakeFS:
        # ["returnTo", "https://<lakefs.ingress.domain>/"]
        logout_endpoint_query_parameters:
          - returnTo
          - https://<lakefs.ingress.domain>/oidc/login

LDAP

lakeFS Enterprise는 LDAP 서버에서 사용자 정보를 쿼리하고 제공된 자격 증명으로 사용자를 인증해 직접 LDAP 인증을 제공해요.

중요: 관리 bind 사용자를 설정해야 해요. LDAP 서버에 대한 검색 권한이 있어야 해요.

ingress:
  enabled: true
  ingressClassName: <class-name>
  hosts:
    - host: <lakefs.ingress.domain>
      paths:
        - /

enterprise:
  enabled: true
  auth:
    ldap:
      enabled: true
      bindPassword: <ldap bind password>

image:
  privateRegistry:
    enabled: true
    secretToken: <dockerhub-token>

lakefsConfig: |
  blockstore:
    type: local
  auth:
    providers:
      ldap:
        server_endpoint: ldaps://ldap.company.com:636
        bind_dn: uid=<bind-user-name>,ou=Users,o=<org-id>,dc=<company>,dc=com
        username_attribute: uid
        user_base_dn: ou=Users,o=<org-id>,dc=<company>,dc=com
        user_filter: (objectClass=inetOrgPerson)
        connection_timeout_seconds: 15
        request_timeout_seconds: 7
        # RBAC group for first time users
        default_user_group: "Developers"

LDAP 문제 트러블슈팅

로그 검사하기

LDAP 연결 오류가 발생하면 lakeFS 컨테이너 로그를 검사해 더 많은 정보를 얻으세요.

인증 문제

인증 문제(예: 사용자를 찾을 수 없음, 유효하지 않은 자격 증명)는 ldapwhoami CLI 도구로 디버깅할 수 있어요.

예제는 위 설정을 기반으로 해요:

메인 bind 사용자가 연결할 수 있는지 확인하려면:

ldapwhoami -H ldaps://ldap.company.com:636 -D "uid=bind-user-name,ou=Users,o=org-id,dc=company,dc=com" -x -W

특정 lakeFS 사용자 dev-user가 연결할 수 있는지 확인하려면:

ldapwhoami -H ldaps://ldap.company.com:636 -D "uid=dev-user,ou=Users,o=org-id,dc=company,dc=com" -x -W

사용자를 찾을 수 없는 문제

로그인 요청이 오면 bind 사용자가 LDAP 서버에서 사용자를 검색해요. 사용자를 찾지 못하면 로그에 표시돼요.

ldapsearch CLI 도구로 사용자를 검색할 수 있어요.

base DN의 모든(ALL) 사용자 검색(필터 없음):

Note

-b는 lakeFS 설정의 user_base_dn, -D는 bind_dn, -w는 bind_password예요.

ldapsearch -H ldaps://ldap.company.com:636 -x -b "ou=Users,o=org-id,dc=company,dc=com" -D "uid=bind-user-name,ou=Users,o=org-id,dc=company,dc=com" -w 'bind_user_pwd'

사용자가 발견되면, 이제 lakeFS가 하는 것과 같은 방식으로 특정 사용자에 필터를 적용해 그 사용자가 보이는지 확인해 보세요.

예를 들어 lakeFS와 같은 검색을 재현하려면:

  • LDAP의 uid 속성에서 설정된 사용자 dev-user
  • 설정 값: user_filter: (objectClass=inetOrgPerson)과 username_attribute: uid
ldapsearch -H ldaps://ldap.company.com:636 -x -b "ou=Users,o=org-id,dc=company,dc=com" -D "uid=bind-user-name,ou=Users,o=org-id,dc=company,dc=com" -w 'bind_user_pwd' "(&(uid=dev-user)(objectClass=inetOrgPerson))"

External AWS Authentication

lakeFS Enterprise는 AWS IAM 자격 증명을 사용한 인증을 지원해요. 이를 통해 사용자는 GetCallerIdentity를 통해 AWS 자격 증명으로 인증할 수 있어요.

ingress:
  enabled: true
  ingressClassName: <class-name>
  hosts:
    - host: <lakefs.ingress.domain>
      paths:
        - /

lakefsConfig: |
  auth:
    external_aws_auth:
      enabled: true
      # the maximum age in seconds for the GetCallerIdentity request
      #get_caller_identity_max_age: 60
      # headers that must be present by the client when doing login request
      required_headers:
        # same host as the lakeFS server ingress
        X-LakeFS-Server-ID: <lakefs.ingress.domain>

공통 설정

모든 인증 방식은 몇 가지 공통 설정 옵션을 공유해요:

# Enable enterprise features
enterprise:
  enabled: true

# Common lakeFS configuration
lakefsConfig: |
  # Basic auth configuration
  auth:
    encrypt:
      secret_key: <your-encryption-secret>  # Set via secrets.authEncryptSecretKey
    login_duration: 24h                      # Session duration
    login_max_duration: 168h                 # Maximum session duration

시크릿 관리

Helm chart는 민감한 값들을 위한 Kubernetes 시크릿을 자동 생성해요:

secrets:
  # Required: encryption key for auth cookies
  authEncryptSecretKey: <your-random-secret-string>

  # For database connection (if using external DB)
  databaseConnectionString: <postgres-connection-string>

# Or use existing secrets
secrets:
  existingSecret: my-lakefs-secrets
  # Define the keys in your secret:
  authEncryptSecretKeyName: authEncryptSecretKey
  databaseConnectionStringKeyName: databaseConnectionString

인증 프로바이더 시크릿은 enterprise.auth.* 설정으로 별도 관리돼요.

환경 변수

모든 설정은 환경 변수로도 설정할 수 있어요:

# SAML
LAKEFS_AUTH_PROVIDERS_SAML_SP_ROOT_URL=https://lakefs.company.com
LAKEFS_AUTH_COOKIE_AUTH_VERIFICATION_EXTERNAL_USER_ID_CLAIM_NAME=samName

# OIDC
LAKEFS_AUTH_PROVIDERS_OIDC_CLIENT_ID=your-client-id
LAKEFS_AUTH_OIDC_FRIENDLY_NAME_CLAIM_NAME=name

# LDAP
LAKEFS_AUTH_PROVIDERS_LDAP_SERVER_ENDPOINT=ldaps://ldap.company.com:636
LAKEFS_AUTH_PROVIDERS_LDAP_BIND_DN=uid=bind-user,ou=Users,o=org,dc=company,dc=com

# External AWS Auth
LAKEFS_AUTH_EXTERNAL_AWS_AUTH_ENABLED=true

더 알아보기 (Learn more)

공식 문서의 원문은 https://docs.lakefs.io/security/sso/ 에서 확인할 수 있어요.