OAuth2c: 用户友好的OAuth命令行工具
oauth2c
是一个用于与OAuth 2.0授权服务器交互的命令行工具。它的目标是使用任何授权类型或客户端身份验证方法轻松获取访问令牌。它几乎兼容所有基本和高级的OAuth 2.0、OIDC、OIDF FAPI和JWT配置文件。
特性
- 支持授权码、混合、隐式、密码、客户端凭证、刷新令牌、JWT承载、令牌交换、设备授权流程
- 支持客户端密钥基本、客户端密钥发布、客户端密钥JWT、私钥JWT、TLS客户端认证客户端身份验证方法
- 以明文、签名和/或加密JWT形式传递请求参数
- 支持授权码交换证明密钥(PKCE)
- 支持JWT安全授权响应模式(JARM)
- 支持推送授权请求(PAR)
- 支持证明所有权演示(DPoP)
- 支持丰富授权请求(RAR)
安装
要安装oauth2c
,根据您的操作系统,有几种选择。
在Mac上安装
在Mac上,您可以使用brew
运行以下命令安装oauth2c
:
brew install cloudentity/tap/oauth2c
在Linux上安装
在Linux上,您可以运行以下命令使用安装脚本安装oauth2c
:
curl -sSfL https://raw.githubusercontent.com/cloudentity/oauth2c/master/install.sh | \
sudo sh -s -- -b /usr/local/bin latest
或者,您可以查看软件包页面获取使用包管理器安装oauth2c的具体说明。
从源代码编译
要使用go
从源代码编译oauth2c
。运行以下命令:
go install github.com/cloudentity/oauth2c@latest
您也可以从发布页面下载预编译的二进制文件。
使用方法
要使用oauth2c
,运行以下命令并按提示操作:
oauth2c [发行者URL] [标志]
可用的标志有:
--acr-values strings ACR值
--actor-token string 操作方令牌
--actor-token-type string 操作方令牌类型
--assertion string JWT承载断言的声明
--audience strings 请求的受众
--auth-method string 令牌端点认证方法
--authorization-endpoint string 服务器的授权端点
--browser-timeout duration 浏览器超时(默认10m0s)
--callback-tls-cert string 回调TLS证书PEM文件路径
--callback-tls-key string 回调TLS密钥PEM文件路径
--claims string 使用声明
--client-id string 客户端标识符
--client-secret string 客户端密钥
--device-authorization-endpoint string 服务器的设备授权端点
--dpop 使用DPoP
--encrypted-request-object 以加密JWT形式传递请求参数
--encryption-key string 加密密钥的JWKS格式路径或URL
--grant-type string 授权类型
-h, --help 帮助
--http-timeout duration HTTP客户端超时(默认1m0s)
--id-token-hint string ID令牌提示
--idp-hint string 身份提供者提示
--insecure 允许不安全连接
--login-hint string 用户标识符提示
--max-age string 最大认证年龄(秒)
--mtls-pushed-authorization-request-endpoint string 服务器的MTLS推送授权请求端点
--mtls-token-endpoint string 服务器的MTLS令牌端点
--no-prompt 禁用提示
--par 启用推送授权请求(PAR)
--password string 资源所有者密码凭证授权流程密码
--pkce 启用授权码交换证明密钥(PKCE)
--prompt strings 最终用户授权目的
--purpose string 描述获取最终用户授权目的的字符串
--pushed-authorization-request-endpoint string 服务器的推送授权请求端点
--rar string 使用丰富授权请求(RAR)
--redirect-url string 客户端重定向URL(默认"http://localhost:9876/callback")
--refresh-token string 刷新令牌
--request-object 以JWT形式传递请求参数
--response-mode string 响应模式
--response-types strings 响应类型
--scopes strings 请求的作用域
--signing-key string 签名密钥的JWKS格式路径或URL
-s, --silent 静默模式
--subject-token string 第三方令牌
--subject-token-type string 第三方令牌类型
--tls-cert string TLS证书PEM文件路径
--tls-key string TLS密钥PEM文件路径
--tls-root-ca string TLS根CA PEM文件路径
--token-endpoint string 服务器的令牌端点
--username string 资源所有者密码凭证授权流程用户名
oauth2c
会为授权码等流程打开浏览器,并启动一个HTTP服务器作为客户端应用程序等待回调。
注意:要使浏览器流程正常工作,请将
http://localhost:9876/callback
添加为客户端的重定向URL。
oauth2c
会打印获取访问令牌所做的所有请求。如果要将其集成到CI/CD管道中,请使用--silent
标志。
有关可用选项和参数的更多信息,请运行oauth2c --help
。
示例
以下是使用oauth2c与不同授权类型和客户端身份验证方法的一些示例:
授权类型
注意:授权码、隐式、混合和设备授权流程需要浏览器和用户认证。
授权码
此授权类型涉及两步过程,用户首先授予访问其数据的权限,然后客户端用授权码交换访问令牌。此授权类型通常用于服务器端应用程序。
oauth2c https://oauth2c.us.authz.cloudentity.io/oauth2c/demo \
--client-id cauktionbud6q8ftlqq0 \
--client-secret HCwQ5uuUWBRHd04ivjX5Kl0Rz8zxMOekeLtqzki0GPc \
--response-types code \
--response-mode query \
--grant-type authorization_code \
--auth-method client_secret_basic
隐式
此授权类型类似于授权码授权,但访问令牌直接返回给客户端,没有中间授权码。此授权类型通常用于单页或移动应用程序。
注意:不建议在现代OAuth2应用程序中使用隐式流程。相反,建议使用带PKCE(授权码交换证明密钥)的授权码流程以增加安全性。
oauth2c https://oauth2c.us.authz.cloudentity.io/oauth2c/demo \
--client-id cauktionbud6q8ftlqq0 \
--response-types token \
--response-mode form_post \
--grant-type implicit \
--scopes openid,email,offline_access
混合
要使用OAuth2混合流程获取授权码和ID令牌,客户端首先向OAuth2提供者发送授权请求。请求应包括code和id_token响应类型。
OAuth2提供者随后会向客户端返回授权码和ID令牌,可能在响应正文中或作为重定向URL中的片段参数,具体取决于请求中指定的响应模式。然后,客户端可以使用授权码向OAuth2提供者发送令牌请求以获取访问令牌。
ID令牌可用于验证已认证用户的身份,因为它包含诸如用户名和电子邮件地址等信息。ID令牌通常由OAuth2提供者签名,因此客户端可以使用提供者的公钥验证其真实性。
oauth2c https://oauth2c.us.authz.cloudentity.io/oauth2c/demo \
--client-id cauktionbud6q8ftlqq0 \
--client-secret HCwQ5uuUWBRHd04ivjX5Kl0Rz8zxMOekeLtqzki0GPc \
--response-types code,id_token \
--response-mode form_post \
--grant-type authorization_code \
--auth-method client_secret_basic \
--scopes openid,email,offline_access
客户端凭证
此授权类型涉及客户端向OAuth2服务器提供自己的凭证,然后服务器返回访问令牌。此授权类型通常用于服务器到服务器的通信,其中客户端是受信任的服务器而不是用户。
oauth2c https://oauth2c.us.authz.cloudentity.io/oauth2c/demo \
--client-id cauktionbud6q8ftlqq0 \
--client-secret HCwQ5uuUWBRHd04ivjX5Kl0Rz8zxMOekeLtqzki0GPc \
--grant-type client_credentials \
--auth-method client_secret_basic \
--scopes introspect_tokens,revoke_tokens
刷新令牌
此授权类型涉及客户端向OAuth2服务器提供刷新令牌,然后服务器返回新的访问令牌。
oauth2c https://oauth2c.us.authz.cloudentity.io/oauth2c/demo \
--client-id cauktionbud6q8ftlqq0 \
--client-secret HCwQ5uuUWBRHd04ivjX5Kl0Rz8zxMOekeLtqzki0GPc \
--grant-type refresh_token\
--auth-method client_secret_basic \
--refresh-token $REFRESH_TOKEN
注意 要使用此命令,您必须首先设置REFRESH_TOKEN环境变量
显示示例
export REFRESH_TOKEN=`oauth2c https://oauth2c.us.authz.cloudentity.io/oauth2c/demo \ --client-id cauktionbud6q8ftlqq0 \ --client-secret HCwQ5uuUWBRHd04ivjX5Kl0Rz8zxMOekeLtqzki0GPc \ --response-types code \ --response-mode query \ --grant-type authorization_code \ --auth-method client_secret_basic \ --scopes openid,email,offline_access \ --silent | jq -r .refresh_token`
密码
此授权类型涉
oauth2c https://oauth2c.us.authz.cloudentity.io/oauth2c/demo \
--client-id cauktionbud6q8ftlqq0 \
--client-secret HCwQ5uuUWBRHd04ivjX5Kl0Rz8zxMOekeLtqzki0GPc \
--grant-type password \
--username demo \
--password demo \
--auth-method client_secret_basic \
--scopes openid
设备
这种授权类型是一个两步流程,允许用户在不需要输入用户名和密码的情况下授予对其数据的访问权限。在第一步中,用户授予客户端访问其数据的权限。在第二步中,客户端用第一步中收到的授权码交换访问令牌。这种授权类型通常用于服务器端应用程序,例如从电视或其他非交互式设备访问设备时。
oauth2c https://oauth2c.us.authz.cloudentity.io/oauth2c/demo \
--client-id cauktionbud6q8ftlqq0 \
--client-secret HCwQ5uuUWBRHd04ivjX5Kl0Rz8zxMOekeLtqzki0GPc \
--grant-type urn:ietf:params:oauth:grant-type:device_code \
--auth-method client_secret_basic \
--scopes openid,email,offline_access
JWT Bearer
这种授权类型涉及客户端向OAuth2服务器提供JSON Web Token (JWT),然后服务器返回访问令牌。这种授权类型通常在客户端是受信任的第三方(如JWT发行者)时使用。
oauth2c https://oauth2c.us.authz.cloudentity.io/oauth2c/demo \
--client-id cauktionbud6q8ftlqq0 \
--client-secret HCwQ5uuUWBRHd04ivjX5Kl0Rz8zxMOekeLtqzki0GPc \
--grant-type urn:ietf:params:oauth:grant-type:jwt-bearer \
--auth-method client_secret_basic \
--scopes email \
--signing-key https://raw.githubusercontent.com/cloudentity/oauth2c/master/data/rsa/key.json \
--assertion '{"sub":"jdoe@example.com"}'
令牌交换
令牌交换OAuth2授权流程涉及客户端向OAuth2服务器提供访问令牌,然后服务器返回新的访问令牌。这种授权类型通常在客户端和OAuth2服务器之间存在预先建立的信任关系时使用,例如当客户端是受信任的第三方时。
oauth2c https://oauth2c.us.authz.cloudentity.io/oauth2c/demo \
--client-id cauktionbud6q8ftlqq0 \
--client-secret HCwQ5uuUWBRHd04ivjX5Kl0Rz8zxMOekeLtqzki0GPc \
--grant-type urn:ietf:params:oauth:grant-type:token-exchange \
--auth-method client_secret_basic \
--scopes email \
--subject-token $SUBJECT_TOKEN \
--subject-token-type urn:ietf:params:oauth:token-type:access_token \
--actor-token $ACTOR_TOKEN \
--actor-token-type urn:ietf:params:oauth:token-type:access_token
注意 要使用此命令,你必须首先设置SUBJECT_TOKEN和ACTOR_TOKEN环境变量
显示示例
export SUBJECT_TOKEN=`oauth2c https://oauth2c.us.authz.cloudentity.io/oauth2c/demo \ --client-id cauktionbud6q8ftlqq0 \ --client-secret HCwQ5uuUWBRHd04ivjX5Kl0Rz8zxMOekeLtqzki0GPc \ --response-types code \ --response-mode query \ --grant-type authorization_code \ --auth-method client_secret_basic \ --scopes openid,email,offline_access \ --silent | jq -r .access_token`
export ACTOR_TOKEN=`oauth2c https://oauth2c.us.authz.cloudentity.io/oauth2c/demo \ --client-id cauktionbud6q8ftlqq0 \ --client-secret HCwQ5uuUWBRHd04ivjX5Kl0Rz8zxMOekeLtqzki0GPc \ --grant-type client_credentials \ --auth-method client_secret_basic \ --scopes introspect_tokens,revoke_tokens \ --silent | jq -r .access_token`
认证方法
客户端密钥基本认证
这种客户端认证方法涉及客户端将其凭证作为HTTP基本认证头的一部分发送给OAuth2服务器的请求。这种方法简单且广泛支持,但比其他方法安全性较低,因为客户端密钥是明文发送的。
oauth2c https://oauth2c.us.authz.cloudentity.io/oauth2c/demo \
--client-id cauktionbud6q8ftlqq0 \
--client-secret HCwQ5uuUWBRHd04ivjX5Kl0Rz8zxMOekeLtqzki0GPc \
--grant-type client_credentials \
--auth-method client_secret_basic \
--scopes introspect_tokens,revoke_tokens
客户端密钥POST
这种客户端认证方法涉及客户端将其凭证作为请求体的一部分发送给OAuth2服务器的请求。这种方法比基本认证方法提供更高的安全性,但需要通过HTTPS发送请求以防止客户端密钥被截获。
oauth2c https://oauth2c.us.authz.cloudentity.io/oauth2c/demo \
--client-id cauosoo2omc4fr8ai1fg \
--client-secret ipFkA1lMomOMI_d2HcGGQ7j8oxeHFqKw3kli76g92VM \
--grant-type client_credentials \
--auth-method client_secret_post \
--scopes introspect_tokens,revoke_tokens
客户端密钥JWT
这种客户端认证方法涉及客户端使用其客户端密钥签署JSON Web Token (JWT),然后将JWT发送给OAuth2服务器。这种方法提供了比基本或POST方法更高的安全级别,因为客户端密钥从不明文发送。
oauth2c https://oauth2c.us.authz.cloudentity.io/oauth2c/demo \
--client-id ab966ce4f2ac4f4aa641582b099c32d3 \
--client-secret 578-WfFYfBheWb8gJpHYXMRRqR5HN0qv7d7xIolJnIE \
--grant-type client_credentials \
--auth-method client_secret_jwt \
--scopes introspect_tokens,revoke_tokens
私钥JWT
这种客户端认证方法涉及客户端使用其私钥签署JSON Web Token (JWT),然后将JWT发送给OAuth2服务器。这种方法提供了比使用客户端密钥的JWT方法更高的安全级别,因为私钥从不与OAuth2服务器共享。
oauth2c https://oauth2c.us.authz.cloudentity.io/oauth2c/demo \
--client-id 582af0afb0d74554aa7af47849edb222 \
--signing-key https://raw.githubusercontent.com/cloudentity/oauth2c/master/data/rsa/key.json \
--grant-type client_credentials \
--auth-method private_key_jwt \
--scopes introspect_tokens,revoke_tokens
TLS客户端认证
这种客户端认证方法涉及客户端在连接到OAuth2服务器时作为TLS握手的一部分提供自己的证书。这种方法提供了高级别的安全性,因为客户端的身份是使用受信任的证书颁发机构验证的。然而,它要求OAuth2服务器支持TLS客户端认证,这可能不被所有OAuth2提供商支持。
oauth2c https://oauth2c.us.authz.cloudentity.io/oauth2c/demo \
--client-id 3f07a8c2adea4c1ab353f3ca8e16b8fd \
--tls-cert https://raw.githubusercontent.com/cloudentity/oauth2c/master/data/cert.pem \
--tls-key https://raw.githubusercontent.com/cloudentity/oauth2c/master/data/key.pem \
--grant-type client_credentials \
--auth-method tls_client_auth \
--scopes introspect_tokens,revoke_tokens
无认证与PKCE
公开客户端,如移动应用,无法像机密客户端那样向授权服务器进行身份验证,因为它们没有客户端密钥。为了保护自己免受授权码被攻击者截获和使用,公开客户端可以在授权过程中使用PKCE(Proof Key for Code Exchange)。PKCE通过确保授权码只能由最初请求它的同一客户端交换为令牌,从而提供了额外的安全层。这有助于防止未经授权访问令牌。
oauth2c https://oauth2c.us.authz.cloudentity.io/oauth2c/demo \
--client-id db5e375e7b634095b24bbb683fcb955b \
--response-types code \
--response-mode query \
--grant-type authorization_code \
--auth-method none \
--scopes openid,email \
--pkce
扩展
请求对象
请求对象是一个包含授权请求参数的JWT。它允许请求作为单个、独立的参数传递,并且可以选择性地签名和/或加密以增加安全性。
oauth2c https://oauth2c.us.authz.cloudentity.io/oauth2c/demo \
--client-id cauktionbud6q8ftlqq0 \
--client-secret HCwQ5uuUWBRHd04ivjX5Kl0Rz8zxMOekeLtqzki0GPc \
--response-types code \
--response-mode query \
--grant-type authorization_code \
--auth-method client_secret_basic \
--scopes openid,email,offline_access \
--request-object
请求声明
使用"claims"请求参数请求声明使客户端能够在授权中请求特定的用户属性,从而提高效率和安全性。
oauth2c https://oauth2c.us.authz.cloudentity.io/oauth2c/demo \
--client-id cauktionbud6q8ftlqq0 \
--client-secret HCwQ5uuUWBRHd04ivjX5Kl0Rz8zxMOekeLtqzki0GPc \
--response-types code \
--response-mode query \
--grant-type authorization_code \
--auth-method client_secret_basic \
--scopes openid,offline_access \
--claims '{"id_token":{"email": {"essential": true}}}'
PKCE
Proof Key for Code Exchange (PKCE) 是OAuth2授权码授权流程的一个扩展,在与OAuth2提供商进行身份验证时提供额外的安全性。在PKCE流程中,客户端生成一个代码验证器和一个代码挑战,然后在授权请求期间将它们发送给OAuth2提供商。提供商返回一个授权码,然后客户端将其与代码验证器一起交换访问令牌。提供商验证代码验证器以确保请求来自启动授权请求的同一客户端。
这个额外的步骤有助于防止攻击者截获授权码并使用它来获取访问令牌。PKCE建议用于所有公开客户端,如单页或移动应用程序,因为客户端密钥无法安全存储。
oauth2c https://oauth2c.us.auth
[了解更多关于带PKCE的授权码流程](https://cloudentity.com/developers/basics/oauth-grant-types/authorization-code-with-pkce/)
#### JARM
JWT保护的OAuth 2.0授权响应,也称为JARM,是一种使用JSON Web令牌(JWT)在OAuth 2.0授权响应中安全传输授权信息的方法。这允许客户端验证授权响应,确保信息来自可信源且未被篡改。JWT使用授权服务器和客户端之间共享的密钥签名,允许客户端验证JWT的真实性。这为OAuth 2.0授权过程提供了额外的安全层。
**签名JWT**
```sh
oauth2c https://oauth2c.us.authz.cloudentity.io/oauth2c/demo \
--client-id cauktionbud6q8ftlqq0 \
--client-secret HCwQ5uuUWBRHd04ivjX5Kl0Rz8zxMOekeLtqzki0GPc \
--response-types code \
--response-mode query.jwt \
--grant-type authorization_code \
--auth-method client_secret_basic \
--scopes openid,email,offline_access
签名和加密JWT
oauth2c https://oauth2c.us.authz.cloudentity.io/oauth2c/demo \
--client-id cauosoo2omc4fr8ai1fg \
--client-secret ipFkA1lMomOMI_d2HcGGQ7j8oxeHFqKw3kli76g92VM \
--response-types code \
--response-mode query.jwt \
--grant-type authorization_code \
--auth-method client_secret_post \
--scopes openid,email,offline_access \
--encryption-key https://raw.githubusercontent.com/cloudentity/oauth2c/master/data/rsa/key.json
PAR
推送授权请求(PAR)是OAuth 2.0规范的扩展,使客户端应用程序能够通过PAR端点直接将授权请求的负载推送到授权服务器。这允许更高效和安全地处理授权请求。PAR对于需要高安全级别的客户端应用程序很有用,并可能是某些安全配置文件和法规遵从性所必需的。
oauth2c https://oauth2c.us.authz.cloudentity.io/oauth2c/demo \
--client-id cauktionbud6q8ftlqq0 \
--client-secret HCwQ5uuUWBRHd04ivjX5Kl0Rz8zxMOekeLtqzki0GPc \
--response-types code \
--response-mode query \
--grant-type authorization_code \
--auth-method client_secret_basic \
--scopes openid,email,offline_access \
--par
DPoP
DPoP,或称拥有证明演示,是一种扩展,描述了一种在发放访问令牌时将其加密绑定到特定客户端的技术。这是改善Bearer令牌安全性的众多尝试之一,要求使用令牌的应用程序对自身进行认证。
oauth2c https://oauth2c.us.authz.cloudentity.io/oauth2c/demo \
--client-id cauktionbud6q8ftlqq0 \
--client-secret HCwQ5uuUWBRHd04ivjX5Kl0Rz8zxMOekeLtqzki0GPc \
--response-types code \
--response-mode query \
--grant-type authorization_code \
--auth-method client_secret_basic \
--scopes openid,email,offline_access \
--signing-key https://raw.githubusercontent.com/cloudentity/oauth2c/master/data/ps/key.json \
--dpop
RAR
富授权请求(RAR)引入了一个新参数authorization_details
,允许客户端使用JSON数据结构的表达能力指定其细粒度授权要求。例如,信用转账的授权请求(在几个开放银行倡议中被指定为"支付发起")可以使用如下JSON对象表示:
{
"type": "payment_initiation",
"locations": [
"https://example.com/payments"
],
"instructedAmount": {
"currency": "EUR",
"amount": "123.50"
},
"creditorName": "Merchant A",
"creditorAccount": {
"bic":"ABCIDEFFXXX",
"iban": "DE02100100109307118603"
},
"remittanceInformationUnstructured": "Ref Number Merchant"
}
oauth2c https://oauth2c.us.authz.cloudentity.io/oauth2c/demo \
--client-id cauktionbud6q8ftlqq0 \
--client-secret HCwQ5uuUWBRHd04ivjX5Kl0Rz8zxMOekeLtqzki0GPc \
--response-types code \
--response-mode query \
--grant-type authorization_code \
--auth-method client_secret_basic \
--rar '[{"type":"payment_initiation","locations":["https://example.com/payments"],"instructedAmount":{"currency":"EUR","amount":"123.50"},"creditorName":"Merchant A","creditorAccount":{"bic":"ABCIDEFFXXX","iban":"DE02100100109307118603"},"remittanceInformationUnstructured":"Ref Number Merchant"}]'
其他
使用HTTPS回调URL
你可以使用--callback-tls-cert
和--callback-tls-key
标志为HTTPS回调重定向URL指定TLS证书和密钥。
oauth2c https://oauth2c.us.authz.cloudentity.io/oauth2c/demo \
--client-id cauktionbud6q8ftlqq0 \
--client-secret HCwQ5uuUWBRHd04ivjX5Kl0Rz8zxMOekeLtqzki0GPc \
--response-types code \
--response-mode query \
--grant-type authorization_code \
--auth-method client_secret_basic \
--redirect-url https://localhost:9876/callback \
--callback-tls-cert https://raw.githubusercontent.com/cloudentity/oauth2c/master/data/cert.pem \
--callback-tls-key https://raw.githubusercontent.com/cloudentity/oauth2c/master/data/key.pem
手动指定授权服务器的端点
如果你的授权服务器不支持OIDC,你可以使用标志手动指定端点。
oauth2c https://oauth2c.us.authz.cloudentity.io/oauth2c/demo \
--client-id cauktionbud6q8ftlqq0 \
--client-secret HCwQ5uuUWBRHd04ivjX5Kl0Rz8zxMOekeLtqzki0GPc \
--response-types code \
--response-mode query \
--grant-type authorization_code \
--auth-method client_secret_basic \
--token-endpoint https://oauth2c.us.authz.cloudentity.io/oauth2c/demo/oauth2/token \
--authorization-endpoint https://oauth2c.us.authz.cloudentity.io/oauth2c/demo/oauth2/authorize
许可
oauth2c
在Apache v2.0许可下发布。
贡献
我们欢迎贡献!如果你有新功能的想法或发现了bug,请在GitHub上开一个issue。