数据工程数据湖大数据对象存储后端【免费下载链接】lakeFSlakeFS - Data version control for your data lake | Git for data项目地址https://gitcode.com/gh_mirrors/la/lakeFS点击查看免费下载导读本文以 lakeFS 官方 Java SDKio.lakefs.clients.sdk中ExternalApi的接口文档为骨架完整讲解外部主体External Principal管理的五个 REST 端点为用户挂接/解除外部主体、查询外部主体、分页列举用户的外部主体以及通过外部认证器执行登录。你将掌握这些接口的 HTTP 语义、Java 调用方式、鉴权要求与响应状态码并了解其在 lakeFS 源码中的实现现状与扩展方向。读完本文你可以在自己的 Java 数据平台项目中直接接入 lakeFS 外部身份体系把 AWS 等外部身份映射为 lakeFS 用户。ExternalApi 概览五个端点一张表ExternalApi的全部接口以/api/v1为统一前缀SDK 中通过defaultClient.setBasePath(/api/v1)指定覆盖了外部主体的“挂接、解除、查询、列举、登录”五个操作方法HTTP 请求描述createUserExternalPrincipalPOST/auth/users/{userId}/external/principals为用户挂接外部主体deleteUserExternalPrincipalDELETE/auth/users/{userId}/external/principals从用户解除外部主体externalPrincipalLoginPOST/auth/external/principal/login使用外部认证器执行登录getExternalPrincipalGET/auth/external/principals按 id 描述外部主体listUserExternalPrincipalsGET/auth/users/{userId}/external/principals/ls分页列举用户已挂接的外部主体在 OpenAPI 契约api/swagger.yml中这五个操作都同时带有auth、external、experimental三个 tag说明该能力目前处于experimental实验性阶段生成出的 Java 类位于 ExternalApi.java。什么是外部主体External Principal从契约的模型定义api/swagger.yml看外部主体是在 lakeFS 之外已经存在的身份例如 AWS IAM 角色id外部主体的唯一标识官方示例即为aws:sts::123:assumed-role/role-nameuserId与之关联的 lakeFS 用户 IDsettings一组键值对ExternalPrincipalSettings注释明确说明是“供远程认证器消费的附加设置”Additional settings to be consumed by the remote authenticator。这套设计使 lakeFS 能够把外部身份体系如云厂商身份、企业 IdP中的主体映射到内部的 lakeFS 用户从而复用 lakeFS 已有的 RBAC 权限模型相关权限动作在 pkg/permissions/actions.go 中定义为auth:CreateUserExternalPrincipal、auth:DeleteUserExternalPrincipal、auth:ReadExternalPrincipal。环境准备把 SDK 引入 Java 工程ExternalApi是 OpenAPI 代码生成器为 lakeFS 生成的 Java SDK 的一部分。按 clients/java/README.md 的说明可先在本机构建并安装mvn clean installMaven 工程随后声明依赖即可使用dependency groupIdio.lakefs/groupId artifactIdsdk/artifactId version0.0.0/version scopecompile/scope /dependencySDK 内部使用 OkHttp 完成 HTTP 通信所有调用均可同步execute()或异步executeAsync()。创建客户端与配置鉴权除externalPrincipalLogin外其余四个端点都需要鉴权SDK 支持三种认证方式定义见 api/swagger.ymlbasic_authHTTP Basic适用于服务端到服务端的密钥对调用cookie_authCookie 名internal_auth_session适用于浏览器会话jwt_tokenHTTP Bearer JWT适用于拿到登录令牌后的调用。标准初始化代码如下// Import classes: import io.lakefs.clients.sdk.ApiClient; import io.lakefs.clients.sdk.ApiException; import io.lakefs.clients.sdk.Configuration; import io.lakefs.clients.sdk.auth.*; import io.lakefs.clients.sdk.models.*; import io.lakefs.clients.sdk.ExternalApi; public class Example { public static void main(String[] args) { ApiClient defaultClient Configuration.getDefaultApiClient(); defaultClient.setBasePath(/api/v1); // Configure HTTP basic authorization: basic_auth HttpBasicAuth basic_auth (HttpBasicAuth) defaultClient.getAuthentication(basic_auth); basic_auth.setUsername(YOUR USERNAME); basic_auth.setPassword(YOUR PASSWORD); // Configure API key authorization: cookie_auth ApiKeyAuth cookie_auth (ApiKeyAuth) defaultClient.getAuthentication(cookie_auth); cookie_auth.setApiKey(YOUR API KEY); // Uncomment the following line to set a prefix for the API key, e.g. Token (defaults to null) //cookie_auth.setApiKeyPrefix(Token); // Configure HTTP bearer authorization: jwt_token HttpBearerAuth jwt_token (HttpBearerAuth) defaultClient.getAuthentication(jwt_token); jwt_token.setBearerToken(BEARER TOKEN); ExternalApi apiInstance new ExternalApi(defaultClient); // ... 后续调用 } }在 ExternalApi.java 的底层实现中可以看到除登录外的每个调用都会同时声明basic_auth、cookie_auth、jwt_token三种认证名由ApiClient按已配置的凭据自动带上只要配置其一即可通过鉴权。为用户挂接外部主体createUserExternalPrincipal该操作向POST /auth/users/{userId}/external/principals发起请求把外部主体principalId挂接到 lakeFS 用户userId上。String userId userId_example; // String String principalId principalId_example; // String ExternalPrincipalCreation externalPrincipalCreation new ExternalPrincipalCreation(); // ExternalPrincipalCreation try { apiInstance.createUserExternalPrincipal(userId, principalId) .externalPrincipalCreation(externalPrincipalCreation) .execute(); } catch (ApiException e) { System.err.println(Exception when calling ExternalApi#createUserExternalPrincipal); System.err.println(Status code: e.getCode()); System.err.println(Reason: e.getResponseBody()); System.err.println(Response headers: e.getResponseHeaders()); e.printStackTrace(); }参数说明NameTypeDescriptionNotesuserIdStringlakeFS 用户 ID必填pathprincipalIdString外部主体唯一标识必填queryexternalPrincipalCreationExternalPrincipalCreation创建信息可选request body请求体模型ExternalPrincipalCreation只有一个可选字段settingsListMapString, String对应契约中供远程认证器消费的附加设置。返回与状态码返回类型为null空响应体。完整状态码语义如下Status codeDescription201external principal attached successfully挂接成功400Bad Request401Unauthorized404Resource Not Found用户或主体不存在409Resource Conflicts With Target主体已被占用等冲突429too many requests0Internal Server Error请求头Content-Type: application/json、Accept: application/json。值得注意调用参数userId与principalId在 SDK 中被硬校验为必填见 ExternalApi.java任一为null都会抛出ApiException(Missing the required parameter ...)而externalPrincipalCreation请求体为可选。解除外部主体deleteUserExternalPrincipal向DELETE /auth/users/{userId}/external/principals发起请求将外部主体从用户上解除。String userId userId_example; // String String principalId principalId_example; // String try { apiInstance.deleteUserExternalPrincipal(userId, principalId) .execute(); } catch (ApiException e) { System.err.println(Exception when calling ExternalApi#deleteUserExternalPrincipal); System.err.println(Status code: e.getCode()); System.err.println(Reason: e.getResponseBody()); System.err.println(Response headers: e.getResponseHeaders()); e.printStackTrace(); }NameTypeDescriptionNotesuserIdStringlakeFS 用户 ID必填pathprincipalIdString外部主体唯一标识必填queryStatus codeDescription204external principal detached successfully解除成功400Bad Request401Unauthorized404Resource Not Found429too many requests0Internal Server Error该请求无需请求体Content-Type: Not defined仅接受application/json响应。外部登录externalPrincipalLogin这是五个端点中唯一无需任何鉴权No authorization required的接口向POST /auth/external/principal/login发起请求通过外部认证器完成登录并换取 lakeFS 的 JWT 令牌。它也是整个 External Principal 流程的入口外部身份先登录拿到令牌后续请求再以jwt_token方式携带该令牌访问其他 API。ExternalApi apiInstance new ExternalApi(defaultClient); ExternalLoginInformation externalLoginInformation new ExternalLoginInformation(); // ExternalLoginInformation try { AuthenticationToken result apiInstance.externalPrincipalLogin() .externalLoginInformation(externalLoginInformation) .execute(); System.out.println(result); } catch (ApiException e) { System.err.println(Exception when calling ExternalApi#externalPrincipalLogin); System.err.println(Status code: e.getCode()); System.err.println(Reason: e.getResponseBody()); System.err.println(Response headers: e.getResponseHeaders()); e.printStackTrace(); }NameTypeDescriptionNotesexternalLoginInformationExternalLoginInformation登录信息可选request body请求体模型ExternalLoginInformation有两个字段契约定义见 api/swagger.ymlidentityRequest必填Object透传给外部认证器的身份请求内容tokenExpirationDuration可选Integer生成的令牌有效期用于控制令牌的 TTL。返回类型与状态码返回类型为AuthenticationToken该模型在契约中定义api/swagger.ymltoken必填可用来认证后续请求的 JWTtoken_expirationUnix 时间戳秒令牌过期时刻。Status codeDescription200successful external login登录成功返回令牌400Bad Request401Unauthorized403Forbidden404Resource Not Found429too many requests0Internal Server Error查询与列举外部主体按 id 查询getExternalPrincipal向GET /auth/external/principals?principalId...发起请求返回单个外部主体的详情。String principalId principalId_example; // String try { ExternalPrincipal result apiInstance.getExternalPrincipal(principalId) .execute(); System.out.println(result); } catch (ApiException e) { System.err.println(Exception when calling ExternalApi#getExternalPrincipal); System.err.println(Status code: e.getCode()); System.err.println(Reason: e.getResponseBody()); System.err.println(Response headers: e.getResponseHeaders()); e.printStackTrace(); }NameTypeDescriptionNotesprincipalIdString外部主体唯一标识必填query返回ExternalPrincipalid外部主体标识、userId关联的 lakeFS 用户 ID、settings可选设置。查询成功后可据此判断该外部主体已映射到哪个 lakeFS 用户。Status codeDescription200external principal查询成功400Bad Request401Unauthorized404Resource Not Found429too many requests0Internal Server Error分页列举listUserExternalPrincipals向GET /auth/users/{userId}/external/principals/ls发起请求分页返回用户已挂接的全部外部主体。它支持三个分页参数与 lakeFS 全站统一的分页参数定义一致api/swagger.yml。String userId userId_example; // String String prefix prefix_example; // String | return items prefixed with this value String after after_example; // String | return items after this value Integer amount 100; // Integer | how many items to return try { ExternalPrincipalList result apiInstance.listUserExternalPrincipals(userId) .prefix(prefix) .after(after) .amount(amount) .execute(); System.out.println(result); } catch (ApiException e) { System.err.println(Exception when calling ExternalApi#listUserExternalPrincipals); System.err.println(Status code: e.getCode()); System.err.println(Reason: e.getResponseBody()); System.err.println(Response headers: e.getResponseHeaders()); e.printStackTrace(); }NameTypeDescriptionNotesuserIdStringlakeFS 用户 ID必填pathprefixString只返回以此值开头的条目可选afterString返回该值之后的条目可选amountInteger返回多少条可选默认 100关于amount的取值范围api/swagger.yml 中明确规定最小值为-1表示返回全部、最大值为1000超出该范围的取值会被服务端判定为 Bad Request。返回ExternalPrincipalList包含pagination分页游标信息与resultsExternalPrincipal数组两个必填字段。分页游标与 lakeFS 其他列表接口一致可将返回的pagination.next_offset作为下一次请求的after继续翻页。Status codeDescription200external principals list列举成功400Bad Request401Unauthorized404Resource Not Found429too many requests0Internal Server Error源码视角实现现状与注意事项从当前仓库的 Go 实现看这组接口仍处于实验性/未落地阶段使用前需要明确预期服务端目前返回 501 Not Implemented在 pkg/api/controller.go 与 pkg/api/controller.go 中ExternalPrincipalLogin、CreateUserExternalPrincipal、DeleteUserExternalPrincipal、GetExternalPrincipal、ListUserExternalPrincipals五个处理器均为占位桩直接writeError(w, r, http.StatusNotImplemented, ...)。也就是说SDK 客户端可以完整构造并发送请求但当前版本的服务端尚不提供实际业务实现。OpenAPI 契约先行接口路径、参数、模型与状态码的权威定义都在 api/swagger.yml 与 api/swagger.yml 中Java SDK 由代码生成器自动生成因此本文所有调用方式、模型结构与契约完全一致后续服务端实现落地时客户端无需改动即可对接。权限模型已预留与这三个外部主体操作对应的权限动作auth:CreateUserExternalPrincipal、auth:DeleteUserExternalPrincipal、auth:ReadExternalPrincipal已在 pkg/permissions/actions.go 中定义说明 RBAC 侧已为这套接口预留好授权点。配置项已定义但标记为废弃在 pkg/config/config.go 与 pkg/config/config.go 中auth.authentication_api.external_principals_enabled与auth.cookie_auth_verification.external_user_id_claim_name等旧配置字段仍存在完整示例见 deprecated_auth.yaml但注释已明确标注Deprecated: Value ignored——这表明早期设计中的外部认证器/认证 API 配置已被弃用当前 External Principal 能力的最终形态以上述/api/v1契约为准。小结ExternalApi为 Java 开发者提供了完整的“外部主体”编程接口挂接、解除、查询、分页列举与外部登录五个操作全部以ExternalApi类的链式调用方式暴露统一使用basic_auth/cookie_auth/jwt_token三种鉴权登录接口除外分页遵循 lakeFS 的prefix/after/amount惯例。模型层面ExternalPrincipal用id如aws:sts::123:assumed-role/role-name唯一标识外部身份并通过userId与 lakeFS 内部用户建立映射ExternalLoginInformation.identityRequest则承担了向远程认证器传递身份请求的职责。需要特别留意的是截至当前仓库版本这五个服务端处理器仍返回501 Not Implemented属于契约先行、实现待落地的实验性能力对于要在生产环境使用外部身份映射的团队建议关注 lakeFS 官方后续版本对该接口的实现进度。赞分享数据工程数据湖大数据对象存储后端【免费下载链接】lakeFSlakeFS - Data version control for your data lake | Git for data项目地址https://gitcode.com/gh_mirrors/la/lakeFS点击查看免费下载相关推荐lakeFS Java SDK AuthApi 完整指南用户、组、策略、凭证与外部主体的认证授权管理lakeFS Java SDK AuthApi 完整指南用户、组、策略、凭证与外部主体的认证授权管理 本篇技术指南以 lakeFS 官方 Java SDK数据工程数据湖大数据对象存储后端Elsa Studio 外部认证External AuthenticationUI 契约解析Broker 登录、SSO 连接管理与双宿主实现Elsa Studio 外部认证External AuthenticationUI 契约解析Broker 登录、SSO 连接管理与双宿主实现 本篇文章围绕后端工作流自动化流程编排低代码StarRocks 外部目录External Catalog全解CREATE EXTERNAL CATALOG 语法、参数与源码级实战指南StarRocks 外部目录External Catalog全解CREATE EXTERNAL CATALOG 语法、参数与源码级实战指南 本文是一份关于数据库OLAP数据仓库大数据湖仓一体数据分析上一篇Vercel React 最佳实践useRef 存储事件处理器实现稳定的 Effect 订阅下一篇CodeGuide 手写 ORM 框架实现从 JDBC 到 MyBatis 风格中间件第 7 章实战创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考