Argo Workflows OAuth2EndpointParam 深入解析为 HTTP Artifact 的 OAuth2 令牌请求注入附加端点参数【免费下载链接】argo-workflowsWorkflow Engine for Kubernetes项目地址: https://gitcode.com/gh_mirrors/ar/argo-workflows导读OAuth2EndpointParam是 Argo Workflows 中用于 HTTP ArtifactHTTP 制品OAuth2 客户端认证的类型它允许你在向 OAuth2 令牌端点发起令牌请求时附加额外的键值对参数例如自定义的audience、resource、租户 ID 等。本文将以 Java SDK 文档 IoArgoprojWorkflowV1alpha1OAuth2EndpointParam 为骨架结合仓库内的 Go 类型定义、HTTP 制品驱动源码与真实示例讲解该类型的字段语义、底层实现机制及实际配置方法读完即可在 Workflow 中正确使用endpointParams完成自定义 OAuth2 令牌请求。类型总览字段定义与语义该类型在 Argo Workflows 的 Go API 中定义如下pkg/apis/workflow/v1alpha1/workflow_types.go#L3201-L3208// OAuth2EndpointParam is an optional field that should be sent in the OAuth request. type OAuth2EndpointParam struct { // Name is the header name Key string json:key protobuf:bytes,1,opt,namekey // Value is the literal value to use for the header Value string json:value,omitempty protobuf:bytes,2,opt,namevalue }对应的 OpenAPI 规范同样收录于 api/openapi-spec/swagger.json#L10608-L10612Java SDK 的文档表格给出了与 Go 结构体一致的属性清单属性名类型说明必填keyStringName is the header name参数名称必填valueStringValue is the literal value to use for the header要使用的字面量值可选两点值得注意key是必填字段在 OpenAPI 定义的required列表中它是令牌请求中追加的表单参数名value使用omitempty标记可选为空时该参数会以空字符串形式追加文档注释将key描述为 “header name”但结合底层实现见下文它实际会被放入令牌请求的body/form 参数中而非 HTTP 请求头。类型归属OAuth2Auth 中的 endpointParamsOAuth2EndpointParam不是独立存在的顶级类型它是OAuth2AuthOAuth2 客户端认证配置的一个字段用于收集令牌请求的附加参数。相关结构体同样位于 pkg/apis/workflow/v1alpha1/workflow_types.go#L3192-L3199// OAuth2Auth holds all information for client authentication via OAuth2 tokens type OAuth2Auth struct { ClientIDSecret *apiv1.SecretKeySelector json:clientIDSecret,omitempty protobuf:bytes,1,opt,nameclientIDSecret ClientSecretSecret *apiv1.SecretKeySelector json:clientSecretSecret,omitempty protobuf:bytes,2,opt,nameclientSecretSecret TokenURLSecret *apiv1.SecretKeySelector json:tokenURLSecret,omitempty protobuf:bytes,3,opt,nametokenURLSecret Scopes []string json:scopes,omitempty protobuf:bytes,5,rep,namescopes EndpointParams []OAuth2EndpointParam json:endpointParams,omitempty protobuf:bytes,6,rep,nameendpointParams }OAuth2Auth属于HTTPAuth的三种认证方式之一另外两种是ClientCertAuth客户端证书认证与BasicAuth基础认证完整层级为HTTPArtifact.http └── auth ├── oauth2 (OAuth2Auth) │ ├── clientIDSecret (SecretKeySelector) │ ├── clientSecretSecret (SecretKeySelector) │ ├── tokenURLSecret (SecretKeySelector) │ ├── scopes ([]string) │ └── endpointParams ([]OAuth2EndpointParam) ├── clientCert (ClientCertAuth) └── basicAuth (BasicAuth)Java SDK 中对应类型为 IoArgoprojWorkflowV1alpha1OAuth2Auth其endpointParams字段类型正是ListIoArgoprojWorkflowV1alpha1OAuth2EndpointParam。底层实现endpointParams 如何进入令牌请求要理解OAuth2EndpointParam的真实行为需要看 HTTP Artifact 驱动在运行时如何消费它。核心逻辑在 workflow/artifacts/http/clients.go#L27-L40func CreateOauth2Client(ctx context.Context, clientID, clientSecret, tokenURL string, scopes []string, endpointParams []wfv1.OAuth2EndpointParam) *http.Client { values : url.Values{} for _, endpointParam : range endpointParams { values.Add(endpointParam.Key, endpointParam.Value) } conf : cc.Config{ ClientID: clientID, ClientSecret: clientSecret, TokenURL: tokenURL, EndpointParams: values, Scopes: scopes, } return conf.Client(ctx) }实现要点遍历endpointParams将每个(key, value)通过url.Values.Add收集到表单值集合中将其塞入golang.org/x/oauth2/clientcredentials.Config的EndpointParams字段由该配置构造出携带 OAuth2 令牌能力的http.Client。从源码结构可以推断这些参数最终会作为application/x-www-form-urlencoded表单字段随令牌请求Token Request发送到tokenURL这与 OAuth2.0 规范中“附加端点参数Additional Endpoint Parameters”的扩展点一致常用于传递audience、resource、tenant等 OAuth2 授权服务器要求的自定义参数。需要留意的是文档注释中的 “header name” 表述与实现存在差异——它在实现中并非请求头而是请求体的表单字段。驱动在workflow/artifacts/artifacts.go#L131-L145中完成密钥解析与客户端创建当OAuth2.ClientIDSecret、ClientSecretSecret、TokenURLSecret三者都非空时先从 Kubernetes Secret 中读取clientID、clientSecret、tokenURL再连同Scopes与EndpointParams一并传给CreateOauth2Client。对应的单元测试 workflow/artifacts/http/clients_test.go#L13-L19 验证了带OAuth2EndpointParam{Key: key, Value: value}的场景能够成功构造非空的 HTTP 客户端func TestCreateOauth2Client(t *testing.T) { endpointParams : []wfv1.OAuth2EndpointParam{{Key: key, Value: value}} scopes : []string{some, scopes} client : CreateOauth2Client(logging.TestContext(t.Context()), clientID, clientSecret, tokenURL, scopes, endpointParams) assert.NotNil(t, client) }实战配置在 Workflow 中使用 endpointParamsendpointParams是 HTTP Artifact 认证配置的可选字段典型应用场景是通过 webHDFS如 Azure Data Lake等 OAuth2 受保护的文件系统获取输入制品。仓库中的完整示例见 examples/webhdfs-input-output-artifacts.yaml#L15-L49其 OAuth2 输入制品的配置如下apiVersion: argoproj.io/v1alpha1 kind: Workflow metadata: generateName: input-output-artifact-webhdfs- spec: entrypoint: input-output-artifact-webhdfs-example templates: - name: input-output-artifact-webhdfs-example inputs: artifacts: - name: my-art path: /my-artifact http: # webHDFS artifacts are accessed via an HTTP artifact # url 需包含完整的 webhdfs URL含 operation 与所需 query 参数 url: https://mywebhdfsprovider.com/webhdfs/v1/file.txt?opOPEN auth: oauth2: clientIDSecret: name: oauth-sec key: clientID clientSecretSecret: name: oauth-sec key: clientSecret tokenURLSecret: name: oauth-sec key: tokenURL scopes: - some - scopes # endpointParams 可携带 OAuth2 请求所需的附加字段 endpointParams: - key: customkey value: customvalue # 可选HTTP 请求中携带的请求头 headers: - name: CustomHeader value: CustomValue container: image: debian:latest command: [sh, -c] args: [cat /my-artifact]配置要点clientIDSecret、clientSecretSecret、tokenURLSecret均指向 Kubernetes Secret上例中为同一个名为oauth-sec的 Secret 的三个不同 data key令牌端点 URL 同样从 Secret 读取避免在 Workflow 中明文暴露scopes是字符串数组声明令牌所需权限范围endpointParams为OAuth2EndpointParam数组每条由key必填与value可选组成例如- key: customkey与value: customvalue用于传递授权服务器要求的附加参数上例的输出制品部分展示了同一http.auth结构下的clientCert证书认证方式说明三种认证机制在HTTPArtifact中是并列可选的详见 examples/webhdfs-input-output-artifacts.yaml#L50-L71。关于适用范围docs/webhdfs.md#L40-L53 明确指出HTTP Artifact 支持 HTTP Basic Auth、OAuth2 与客户端证书三种认证方式具体支持情况取决于 webHDFS 提供商例如 Azure Data Lake 走 OAuth2SAP Hana Data Lake 走客户端证书而 Hadoop 原生仅支持 Kerberos SPNEGO 与 delegation token——HTTP Artifact 目前不支持 SPNEGOdelegation token 可通过delegationquery 参数使用。在 Java SDK 中编程使用Java 开发者可通过 Argo Workflows Java 客户端以类型安全的方式构建携带endpointParams的 HTTP 制品。参考 sdks/java/client/docs/IoArgoprojWorkflowV1alpha1OAuth2Auth.mdOAuth2Auth的endpointParams字段类型为ListIoArgoprojWorkflowV1alpha1OAuth2EndpointParamJava 侧对应模型IoArgoprojWorkflowV1alpha1OAuth2EndpointParam暴露getKey()/setKey(String)与getValue()/setValue(String)访问器典型用法如下IoArgoprojWorkflowV1alpha1OAuth2EndpointParam param new IoArgoprojWorkflowV1alpha1OAuth2EndpointParam(); param.setKey(audience); param.setValue(my-api-audience); IoArgoprojWorkflowV1alpha1OAuth2Auth oauth2 new IoArgoprojWorkflowV1alpha1OAuth2Auth() .clientIDSecret(clientIDSecret) .clientSecretSecret(clientSecretSecret) .tokenURLSecret(tokenURLSecret) .addScopesItem(read) .addEndpointParamsItem(param);需要说明的是当前仓库的 Java SDK 目录sdks/java仅包含生成的 API 文档未包含可编译的模型源码文件实际生成的 Java 模型类位于独立发布的 Java SDK 客户端库中此处用法基于 SDK 文档中的属性约定推断具体以你所用版本的 SDK API 为准。小结OAuth2EndpointParam虽是一个只有两个字段的小类型却是 HTTP Artifact 对接各类 OAuth2 授权服务器的关键扩展点key必填令牌请求中追加的表单参数名value可选该参数的字面量值底层行为由 workflow/artifacts/http/clients.go 中的CreateOauth2Client收集为url.Values并注入x/oauth2/clientcredentials.Config.EndpointParams随令牌请求发送触发条件仅当clientIDSecret、clientSecretSecret、tokenURLSecret三者齐备时OAuth2 路径才会生效见 workflow/artifacts/artifacts.go。需要额外参数才能完成令牌获取的 OAuth2 服务如要求audience、resource、tenant的授权服务器都可以通过 Workflow YAML 中的endpointParams或 Java SDK 中对应的ListOAuth2EndpointParam来实现无需修改任何控制器代码。【免费下载链接】argo-workflowsWorkflow Engine for Kubernetes项目地址: https://gitcode.com/gh_mirrors/ar/argo-workflows创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考