¶ 标准协议认证模块

更新时间: 2024-10-10 07:28:40

此模块包含 OIDC、OAuth 2.0、SAML、CAS 标准协议的认证、获取令牌、检查令牌、登出等方法。其中发起认证的方法需要在前端使用，获取令牌、检查令牌等方法需要在后端使用。

使用方法：

// 使用 AppId 和 Secret 进行初始化
authenticationClient := NewClient(AppId, Secret)

authenticationClient.BuildAuthorizeUrl; // 构造前端登录链接
authenticationClient.GetAccessTokenByCode; // Code 换 Token
authenticationClient.GetUserInfoByAccessToken; // Token 换用户信息
authenticationClient.GetNewAccessTokenByRefreshToken; // Refresh Token
authenticationClient.IntrospectToken; // 检验 Token 状态
authenticationClient.ValidateToken; // 检验 Token 合法性
authenticationClient.RevokeToken; // 撤回 Token
authenticationClient.GetAccessTokenByClientCredentials; // 机器间授权获取 Access Token

¶ OIDC

OpenID Connect 简称 OIDC，是 OAuth 2.0 的一个扩展，主要增加了语义化的用户信息字段。

¶ 初始化

初始化 AuthenticationClient 时的参数：

appId <String> 应用 ID，必填。
secret <String> 应用密钥，必填。
host <String> 应用完整地址，如 https://sample-app.authing.cn，不带最后的斜线 '/'。
redirectUri <String> 业务回调 URL，必填。详情请查看文档。
protocol <ProtocolEnum> 协议类型，可选值为 OIDC、OAUTH、SAML、CAS，默认为 OIDC。
tokenEndPointAuthMethod <AuthMethodEnum> 获取 token 端点验证方式，可选值为 CLIENT_SECRET_POST、CLIENT_SECRET_BASIC、NONE，默认为 CLIENT_SECRET_POST。
introspectionEndPointAuthMethod <AuthMethodEnum> 检验 token 端点验证方式，可选值为 CLIENT_SECRET_POST、CLIENT_SECRET_BASIC、NONE，默认为 CLIENT_SECRET_POST。
revocationEndPointAuthMethod <AuthMethodEnum> 撤回 token 端点验证方式，可选值为 CLIENT_SECRET_POST、CLIENT_SECRET_BASIC、NONE，默认为 CLIENT_SECRET_POST。

¶ 示例

// 使用 AppId 和 Secret 进行初始化
authenticationClient := NewClient(AppId, Secret)
authenticationClient.Host = "https://demo.authing.cn"
authenticationClient.Protocol = constant.OIDC
authenticationClient.TokenEndPointAuthMethod = constant.None
// 业务回调地址
authentication.RedirectUri=REDIRECT_URI

¶ 生成 OIDC 协议的用户登录链接

authenticationClient.BuildAuthorizeUrlByOidc(options)

生成 OIDC 协议的用户登录链接

¶ 参数

options <model.OidcParams> 发起授权登录时需要填写的参数。详情请见使用 OIDC 授权码模式。
OidcParams.Scope <String> 请求的权限项目，选填，OIDC 协议默认为 openid profile email phone address，OAuth 2.0 协议默认为 user。
OidcParams.Nonce <String> 随机字符串，选填，默认自动生成。
OidcParams.State <String> 随机字符串，选填，默认自动生成。
OidcParams.ResponseMode <String> 响应类型，选填，可选值为 query、fragment、form_post；默认为 query，即通过浏览器重定向发送 code 到回调地址。
OidcParams.ResponseType <String> 响应类型，选填，可选值为 code、code id_token token、code id_token、code id_token、code token、id_token token、id_token、none；默认为 code，授权码模式。
OidcParams.RedirectUri <String> 回调地址，必填，默认为 SDK 初始化时的 redirectUri 参数。

¶ 示例

// 拼接 OIDC 授权链接
    authenticationClient := NewClient(AppId, Secret)
	authenticationClient.Protocol = constant.OIDC
	authenticationClient.TokenEndPointAuthMethod = constant.None
	req := model.OidcParams{
		AppId:               AppId,
		RedirectUri:         "https://xxxxx.com/",
		Nonce:               "test",
	}
	resp, err := authenticationClient.BuildAuthorizeUrlByOidc(req)
	if err != nil {
		fmt.Println(err)
	} else {
		fmt.Println(resp)
	}

¶ 示例数据

https://oidcdemo.authing.cn/oidc/auth?client_id=60a6f980dd9a9a7642da768a&nonce=test&redirect_uri=https%3A%2F%2Fmvnrepository.com%2F&response_type=code&scope=openid+profile+email+phone+address&state=stcnehi8rt57

¶ Code 换 Token

// GetAccessTokenByCode
func (c *Client) GetAccessTokenByCode(code string) (string, error)

使用授权码 Code 获取用户的 Token 信息。

¶ 参数

code <String> 授权码 Code，用户在认证成功后，Authing 会将授权码 Code 发送到回调地址，详情请见使用 OIDC 授权码模式，每个 Code 只能使用一次。

¶ 示例

resp, err := authenticationClient.GetAccessTokenByCode('授权码 code')

¶ 示例数据

{
  "access_token": "eyJhbGciOiJSUzI1NiIsInR5cCI6IkpXVCIsImtpZCI6IlRmTE90M0xibjhfYThwUk11ZXNzYW1xai1vM0RCQ3MxLW93SExRLVZNcVEifQ.eyJqdGkiOiJsdzg0NW5zdGcwS3EtMTlodVpQOHYiLCJzdWIiOiI1ZmY3MDFkODQ2YjkyMDNlMmY2YWM2ZjMiLCJpYXQiOjE2MTU4ODM1ODYsImV4cCI6MTYxNTg4NzE4Niwic2NvcGUiOiJlbWFpbCBvcGVuaWQgcHJvZmlsZSBwaG9uZSIsImlzcyI6Imh0dHBzOi8vb2lkYzEuYXV0aGluZy5jbi9vaWRjIiwiYXVkIjoiNWYxN2E1MjlmNjRmYjAwOWI3OTRhMmZmIn0.VvYKBcWcr8iIi1b37ugWQ9hsvog4_7EqDQyFqwhIuvM0NHlHH3Bhw83EQIKSNfbWV4nv3ihfeNGPLMzslbQr-wwjnWZTLMYl1bcn7IdVtD_kTN3Zz10MwF5td-VQ7UndU28wJ0HE1mo6E8QH93kYGckS5FSZXmCBa0M5H59Jec_a1MHI1MZrr_V9cZ9EfeF97V-PcqU8JVAwDZclCJ3mWY_Mb65RnMR9yEVqUZzJStmaXGMuRIzjkm2pklqt0CtQQJfzECXq_4USpwRXDiYLWILYPUCcO6hGxDjhMEd8IcxdG51TQP-w1UM6LyIRn61uSJvDsz8zg5dStDKyocypiA",
  "expires_in": 3600,
  "id_token": "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJlbWFpbCI6InRlc3QzQDEyMy5jb20iLCJlbWFpbF92ZXJpZmllZCI6ZmFsc2UsInN1YiI6IjVmZjcwMWQ4NDZiOTIwM2UyZjZhYzZmMyIsImJpcnRoZGF0ZSI6bnVsbCwiZmFtaWx5X25hbWUiOm51bGwsImdlbmRlciI6IlUiLCJnaXZlbl9uYW1lIjpudWxsLCJsb2NhbGUiOm51bGwsIm1pZGRsZV9uYW1lIjpudWxsLCJuYW1lIjpudWxsLCJuaWNrbmFtZSI6bnVsbCwicGljdHVyZSI6Imh0dHBzOi8vZmlsZXMuYXV0aGluZy5jby9hdXRoaW5nLWNvbnNvbGUvZGVmYXVsdC11c2VyLWF2YXRhci5wbmciLCJwcmVmZXJyZWRfdXNlcm5hbWUiOm51bGwsInByb2ZpbGUiOm51bGwsInVwZGF0ZWRfYXQiOiIyMDIxLTAzLTE1VDA1OjU0OjU0LjY4NVoiLCJ3ZWJzaXRlIjpudWxsLCJ6b25laW5mbyI6bnVsbCwicGhvbmVfbnVtYmVyIjpudWxsLCJwaG9uZV9udW1iZXJfdmVyaWZpZWQiOmZhbHNlLCJub25jZSI6IjcwVEU3eW9NVFEiLCJhdF9oYXNoIjoiUFNnOGw5eDRldGxmLXA4UDdjYnVoQSIsImlzcyI6Imh0dHBzOi8vb2lkYzEuYXV0aGluZy5jbi9vaWRjIiwiaXNzMiI6Imh0dHBzOi8vYmFpZHUuY29tIiwiYXVkIjoiNWYxN2E1MjlmNjRmYjAwOWI3OTRhMmZmIiwiZXhwIjoxNjE1ODg3MTg3LCJpYXQiOjE2MTU4ODM1ODh9.OlX-FP7znIEqx0YpnOQ8kxadMe1toHDj1KPVm0dbEVc",
  "scope": "email openid profile phone",
  "token_type": "Bearer"
}

字段解释：

字段名	含义
token_type	Token 类型，固定值 Bearer
scope	授权范围，授权获取的用户权限项目
id_token	Id token，Authing 颁发的 Id token
expires_in	Access token 过期时间
access_token	Access token，Authing 颁发的 Access token

¶ Token 换用户信息

// GetUserInfoByAccessToken
// accessToken 换取用户信息
func (c *Client) GetUserInfoByAccessToken(accessToken string) (string, error)

使用 Access token 获取用户信息。

¶ 参数

accessToken <String> Access token，使用授权码 Code 换取的 Access token 的内容。详情请见使用 OIDC 授权码模式。

¶ 示例

resp, err := authenticationClient.GetUserInfoByAccessToken('Access token')

¶ 示例数据

{
  "address": {
    "country": null,
    "postal_code": null,
    "region": null,
    "formatted": null
  },
  "birthdate": null,
  "family_name": null,
  "gender": "U",
  "given_name": null,
  "locale": null,
  "middle_name": null,
  "name": null,
  "nickname": null,
  "picture": "https://files.authing.co/authing-console/default-user-avatar.png",
  "preferred_username": null,
  "profile": null,
  "updated_at": "2021-03-03T06:17:14.485Z",
  "website": null,
  "zoneinfo": null,
  "email": "test1@authing.cn",
  "email_verified": false,
  "sub": "603f184cec4505e2868431fc", // subject 的缩写，为用户 ID
  "phone_number": null,
  "phone_number_verified": false
}

字段解释：

字段名	翻译
sub	subject 的缩写，唯一标识，一般为用户 ID
name	姓名
given_name	名字
family_name	姓氏
middle_name	中间名
nickname	昵称
preferred_username	希望被称呼的名字
profile	基础资料
picture	头像
website	网站链接
email	电子邮箱
email_verified	邮箱是否被认证
gender	性别
birthdate	生日
zoneinfo	时区
locale	区域
phone_number	手机号
phone_number_verified	认证手机号
address	地址对象
address.formatted	详细地址
address.street_address	街道地址
address.locality	城市
address.region	省
address.postal_code	邮编
address.country	国家
updated_at	信息更新时间

¶ 刷新 Access Token

// GetNewAccessTokenByRefreshToken
// 使用 Refresh token 获取新的 Access token
func (c *Client) GetNewAccessTokenByRefreshToken(refreshToken string) (string, error)

使用 Refresh token 获取新的 Access token。

¶ 参数

refreshToken <String> Refresh token，可以从 authenticationClient.getAccessTokenByCode 方法的返回值中的 refresh_token 获得。详情请见刷新 Access token。

¶ 示例

resp, err := authenticationClient.GetNewAccessTokenByRefreshToken('Access token')

¶ 示例数据

{
  "access_token": "eyJhbGciOiJSUzI1NiIsInR5cCI6IkpXVCIsImtpZCI6IlRmTE90M0xibjhfYThwUk11ZXNzYW1xai1vM0RCQ3MxLW93SExRLVZNcVEifQ.eyJqdGkiOiJZUHB4NUVEWGlQWVJvNUFQWXAzci0iLCJzdWIiOiI1ZmY3MDFkODQ2YjkyMDNlMmY2YWM2ZjMiLCJpYXQiOjE2MTQwOTE0OTksImV4cCI6MTYxNDA5NTA5OSwic2NvcGUiOiJvZmZsaW5lX2FjY2VzcyBwcm9maWxlIG9wZW5pZCIsImlzcyI6Imh0dHBzOi8vb2lkYzEuYXV0aGluZy5jbi9vaWRjIiwiYXVkIjoiNWYxN2E1MjlmNjRmYjAwOWI3OTRhMmZmIn0.ZN_SlfVg1oNMz7uAK-5K84dqqqmlZehmAPOLytOR9HnLHImKJ9VO5u1hRsAjGCob0kMUV5wVxQhX3EFks7FtMamiX2Jvn-NYh4V_5T6l3LFf4uoKF6AykAg483nG3EEENuGgQo15bBszsoCGqFnNmUd0T4Cgxx0zbxXPxMdp_dcE14KzmNz1w-Qg3yVeYmSTZFdcLtZA2BYnVEa7LYA2yA3DgawwAcRmrlyEfnvCO3uY2TcsTKEAfQ-QgVIGRWOfyUE5f-_X3TolliO1fXnwZBdxEKMXLGW5E2bPVcePyiV0upYbUnQ079UxBlEiWlgeW_rpkTPXDxHAgiE488gtlg",
  "expires_in": 3600,
  "id_token": "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJzdWIiOiI1ZmY3MDFkODQ2YjkyMDNlMmY2YWM2ZjMiLCJiaXJ0aGRhdGUiOm51bGwsImZhbWlseV9uYW1lIjpudWxsLCJnZW5kZXIiOiJVIiwiZ2l2ZW5fbmFtZSI6bnVsbCwibG9jYWxlIjpudWxsLCJtaWRkbGVfbmFtZSI6bnVsbCwibmFtZSI6bnVsbCwibmlja25hbWUiOm51bGwsInBpY3R1cmUiOiJodHRwczovL2ZpbGVzLmF1dGhpbmcuY28vYXV0aGluZy1jb25zb2xlL2RlZmF1bHQtdXNlci1hdmF0YXIucG5nIiwicHJlZmVycmVkX3VzZXJuYW1lIjpudWxsLCJwcm9maWxlIjpudWxsLCJ1cGRhdGVkX2F0IjoiMjAyMS0wMi0yM1QxNDo0NDoxOC4wODVaIiwid2Vic2l0ZSI6bnVsbCwiem9uZWluZm8iOm51bGwsImF0X2hhc2giOiIxaWRJSUxaWExpZkRscXJMY3ZNeV9BIiwiS0VZIjoiVkFMVUUiLCJhdWQiOiI1ZjE3YTUyOWY2NGZiMDA5Yjc5NGEyZmYiLCJleHAiOjE2MTQwOTUwOTgsImlhdCI6MTYxNDA5MTQ5OSwiaXNzIjoiaHR0cHM6Ly9vaWRjMS5hdXRoaW5nLmNuL29pZGMifQ._H59237sqpsY0OgyY_RM7CvuG6cFo1x03y-DBhd5hik",
  "refresh_token": "3T49f4Y48szoMmwBXragjqLwQZC4QhgnsM5Oy2WfmU-",
  "scope": "openid offline_access profile",
  "token_type": "Bearer"
}

¶ 检查 Access Token

// IntrospectToken
// 检查 Access token 或 Refresh token 的状态
func (c *Client) IntrospectToken(token string) (string, error)

检查 Access token 或 Refresh token 的状态。

¶ 参数

token <String> Access token 或 Refresh token，可以从 authenticationClient.getAccessTokenByCode 方法的返回值中的 access_token、refresh_token 获得。

¶ 示例

resp, err := authenticationClient.IntrospectToken('Access token 或 Refresh token')

¶ 示例数据

Token 合法时返回：

{
  "active": true,
  "sub": "60097f4d5bc08f75da104d18", // subject 的缩写，为用户 ID
  "client_id": "60097391b1358c17c5fb0f4e",
  "exp": 1612445888,
  "iat": 1611236288,
  "iss": "https://core.littleimp.cn/oidc",
  "jti": "TV4J0gAbe4KR4-8CtYcOa",
  "scope": "openid profile email phone offline_access",
  "token_type": "Bearer"
}

Token 不合法时返回：

{
  "active": false
}

检验过程失败会抛出错误。

¶ 检验 Id Token 合法性

// ValidateToken
// 效验Token合法性
func (c *Client) ValidateToken(req model.ValidateTokenRequest) (string, error)

通过 Authing 提供的在线接口验证 Id token 或 Access token。会产生网络请求。

¶ 参数

req <ValidateTokenParams>
ValidateTokenParams.IdToken <String> Access token 或 Refresh token，可以从 authenticationClient.getAccessTokenByCode 方法的返回值中的 id_token 获得。
ValidateTokenParams.AccessToken <String> Access token，可以从 authenticationClient.getAccessTokenByCode 方法的返回值中的 access_token 获得。

¶ 示例

    req := model.ValidateTokenRequest{
		AccessToken: "token",
		IdToken:     "",
	}
	resp, err := authenticationClient.ValidateToken(req)

¶ 示例数据

id_token 验证合法时返回：

{
  "sub": "5f64afd1ad501364e3b43c1e", // subject 的缩写，为用户 ID
  "birthdate": null,
  "family_name": null,
  "gender": "U",
  "given_name": null,
  "locale": null,
  "middle_name": null,
  "name": null,
  "nickname": null,
  "picture": "https://usercontents.authing.cn/authing-avatar.png",
  "preferred_username": "test1",
  "profile": null,
  "updated_at": "2020-09-27T06:06:29.853Z",
  "website": null,
  "zoneinfo": null,
  "email": "test1@123.com",
  "email_verified": false,
  "phone_number": null,
  "phone_number_verified": false,
  "nonce": "CQsguqUdl7",
  "at_hash": "10iOtwuTNtyQLzlNYXAHeg",
  "aud": "5f17a529f64fb009b794a2ff",
  "exp": 1601460494,
  "iat": 1601456894,
  "iss": "https://oidc1.authing.cn/oidc"
}

Id token 验证非法时返回：

{ "code": 400, "message": "id_token 格式有误" }

{ "code": 400, "message": "id_token 不合法" }

Access token 验证合法时返回：

{
  "jti": "K5TYewNhvdGBdHiRifMyW",
  "sub": "5f64afd1ad501364e3b43c1e", // subject 的缩写，为用户 ID
  "iat": 1601456894,
  "exp": 1601460494,
  "scope": "openid profile email phone",
  "iss": "https://oidc1.authing.cn/oidc",
  "aud": "5f17a529f64fb009b794a2ff"
}

Access token 验证非法时返回：

{ "code": 400, "message": "access_token 格式有误" }

{ "code": 400, "message": "access_token 不合法" }

¶ Client Credentials 模式获取 Access Token

// GetAccessTokenByClientCredentials
// Client Credentials 模式获取 Access Token
func (c *Client) GetAccessTokenByClientCredentials(req model.GetAccessTokenByClientCredentialsRequest) (string, error)

使用编程访问账号获取具备权限的 Access Token。

¶ 参数

req <GetAccessTokenByClientCredentialsRequest> 编程访问账号 AccessKey。
GetAccessTokenByClientCredentialsRequest.Scope <String> 权限项目，空格分隔的字符串，每一项代表一个权限。详情请见机器间（M2M）授权。
GetAccessTokenByClientCredentialsRequest.ClientCredentialInput <ClientCredentialInput> 编程访问账号的 AK 与 SK 信息。
ClientCredentialInput.AccessKey <String> 编程访问账号 AccessKey。
ClientCredentialInput.SecretKey <String> 编程访问账号 SecretKey。

¶ 示例

    input := model.ClientCredentialInput{
		AccessKey: "60519949a70e7dda12785693",
		SecretKey: "be1a5596b3185d88c097ae310e3184ed",
	}
	req := model.GetAccessTokenByClientCredentialsRequest{
		Scope:                 "openid",
		ClientCredentialInput: &input,
	}
	resp, err := authenticationClient.GetAccessTokenByClientCredentials(req)
	if err != nil {
		fmt.Println(err)
	} else {
		fmt.Println(resp)
	}

¶ 示例数据

{
  "access_token": "eyJhbGciOiJSUzI1NiIsInR5cCI6IkpXVCIsImtpZCI6IlRmTE90M0xibjhfYThwUk11ZXNzYW1xai1vM0RCQ3MxLW93SExRLVZNcVEifQ.eyJqdGkiOiJsdzg0NW5zdGcwS3EtMTlodVpQOHYiLCJzdWIiOiI1ZmY3MDFkODQ2YjkyMDNlMmY2YWM2ZjMiLCJpYXQiOjE2MTU4ODM1ODYsImV4cCI6MTYxNTg4NzE4Niwic2NvcGUiOiJlbWFpbCBvcGVuaWQgcHJvZmlsZSBwaG9uZSIsImlzcyI6Imh0dHBzOi8vb2lkYzEuYXV0aGluZy5jbi9vaWRjIiwiYXVkIjoiNWYxN2E1MjlmNjRmYjAwOWI3OTRhMmZmIn0.VvYKBcWcr8iIi1b37ugWQ9hsvog4_7EqDQyFqwhIuvM0NHlHH3Bhw83EQIKSNfbWV4nv3ihfeNGPLMzslbQr-wwjnWZTLMYl1bcn7IdVtD_kTN3Zz10MwF5td-VQ7UndU28wJ0HE1mo6E8QH93kYGckS5FSZXmCBa0M5H59Jec_a1MHI1MZrr_V9cZ9EfeF97V-PcqU8JVAwDZclCJ3mWY_Mb65RnMR9yEVqUZzJStmaXGMuRIzjkm2pklqt0CtQQJfzECXq_4USpwRXDiYLWILYPUCcO6hGxDjhMEd8IcxdG51TQP-w1UM6LyIRn61uSJvDsz8zg5dStDKyocypiA",
  "expires_in": 3600,
  "scope": "email openid profile phone",
  "token_type": "Bearer"
}

¶ 撤回 Access Token 或 Refresh token

// RevokeToken
// 撤回 Access token 或 Refresh token
func (c *Client) RevokeToken(token string) (string, error)

撤回 Access token 或 Refresh token。Access token 或 Refresh token 的持有者可以通知 Authing 已经不再需要令牌，希望 Authing 将其吊销。

¶ 参数

token <string> Access token 或 Refresh token，可以从 authenticationClient.GetAccessTokenByCode 方法的返回值中的 access_token、refresh_token 获得。

¶ 示例

    resp, err := authenticationClient.RevokeToken("Access token 或 Refresh token")
	if err != nil {
		fmt.Println(err)
	} else {
		fmt.Println(resp)
	}

¶ 示例数据

撤回成功时返回 true。

撤回失败时抛出错误。

¶ OAuth 2.0

OAuth 是一个关于授权（Authorization）的开放网络标准，目前的版本是 2.0 版。

初始化 AuthenticationClient 时的参数：

appId <String> 应用 ID，必填。
secret <String> 应用密钥，必填。
host <String> 应用完整地址，如 https://sample-app.authing.cn，不带最后的斜线 '/'。
redirectUri <String> 业务回调 URL，必填。详情请查看文档。
protocol <ProtocolEnum> 协议类型，可选值为 OIDC、OAUTH、SAML、CAS，默认为 OIDC。
tokenEndPointAuthMethod <AuthMethodEnum> 获取 token 端点验证方式，可选值为 CLIENT_SECRET_POST、CLIENT_SECRET_BASIC、NONE，默认为 CLIENT_SECRET_POST。
introspectionEndPointAuthMethod <AuthMethodEnum> 检验 token 端点验证方式，可选值为 CLIENT_SECRET_POST、CLIENT_SECRET_BASIC、NONE，默认为 CLIENT_SECRET_POST。
revocationEndPointAuthMethod <AuthMethodEnum> 撤回 token 端点验证方式，可选值为 CLIENT_SECRET_POST、CLIENT_SECRET_BASIC、NONE，默认为 CLIENT_SECRET_POST。

¶ 示例

 
// 使用 AppId 和 Secret 进行初始化
authenticationClient := NewClient(AppId, Secret)
authenticationClient.Host = "https://demo.authing.cn"
authenticationClient.Protocol = constant.OAUTH
authenticationClient.TokenEndPointAuthMethod = constant.None
// 业务回调地址
authentication.RedirectUri=REDIRECT_URI

¶ 生成 OAuth 2.0 协议的用户登录链接

func (c *Client) BuildAuthorizeUrlByOauth(scope, redirectUri, state, responseType string) (string, error)

生成 OAuth 2.0 协议的用户登录链接，用户可以通过此链接访问 Authing 的在线登录页面。

¶ 参数

发起授权登录时需要填写的参数。详情请见使用 OAuth2.0 授权码模式。

scope <string> 请求的权限项目，选填，OAuth 2.0 协议默认为 user。
state <string> 随机字符串，选填，默认自动生成。
responseType <string> 响应类型，选填，可选值为 code、token 默认为 code，授权码模式。
redirectUri <string> 回调地址，必填，默认为 SDK 初始化时的 redirect_uri 参数。

¶ 示例

    authenticationClient := NewClient(AppId, Secret)
	authenticationClient.userPoolId = UserPool
	authenticationClient.Protocol = constant.OAUTH
	resp, ee := authenticationClient.BuildAuthorizeUrlByOauth("email", "qq", "ww", "cc")

¶ 示例数据

 https://core.authing.cn/oauth/auth?client_id=6168f95e81d5e20f9cb72f22&redirect_uri=qq&response_type=cc&scope=email&state=ww

¶ Code 换 Token

// GetAccessTokenByCode
func (c *Client) GetAccessTokenByCode(code string) (string, error)

使用授权码 Code 获取用户的 Token 信息。

¶ 参数

code <string> 授权码 Code，用户在认证成功后，Authing 会将授权码 Code 发送到回调地址，详情请见使用 OAuth 2.0 授权码模式，每个 Code 只能使用一次。

¶ 示例

初始化 AuthenticationClient 的时候，需要将 protocol 设置为 oauth。

    authenticationClient := NewClient(AppId, Secret)
	authenticationClient.userPoolId = UserPool
	authenticationClient.Protocol = constant.OAUTH
    resp, err := authenticationClient.GetAccessTokenByCode("vj-c-khElsrlEZRGm")

¶ 示例数据

{
  "access_token": "fa9d2bdd914ea01aa4e434c12d4f919d749fc75c",
  "token_type": "Bearer",
  "expires_in": 1209599,
  "refresh_token": "b5e0e1afe793c6634495434afc262b88ddee9af3",
  "scope": "user"
}

字段解释：

字段名	含义
token_type	Token 类型，固定值 Bearer
scope	授权范围，授权获取的用户权限项目
expires_in	Access token 过期时间
access_token	Access token，Authing 颁发的 Access token

¶ Token 换用户信息

// GetUserInfoByAccessToken
// accessToken 换取用户信息
func (c *Client) GetUserInfoByAccessToken(accessToken string) (string, error)

使用 Access token 获取用户信息。

¶ 参数

access_token <string> Access token，使用授权码 Code 换取的 Access token 的内容。详情请见使用 OIDC 授权码模式。

¶ 示例

authenticationClient.GetUserInfoByAccessToken('access_token')

¶ 示例数据

{
  "address": {
    "country": null,
    "postal_code": null,
    "region": null,
    "formatted": null
  },
  "birthdate": null,
  "family_name": null,
  "gender": "U",
  "given_name": null,
  "locale": null,
  "middle_name": null,
  "name": null,
  "nickname": null,
  "picture": "https://files.authing.co/authing-console/default-user-avatar.png",
  "preferred_username": null,
  "profile": null,
  "updated_at": "2021-03-03T06:17:14.485Z",
  "website": null,
  "zoneinfo": null,
  "email": "test1@authing.cn",
  "email_verified": false,
  "sub": "603f184cec4505e2868431fc", // subject 的缩写，为用户 ID
  "phone_number": null,
  "phone_number_verified": false
}

字段解释：

字段名	翻译
sub	subject 的缩写，唯一标识，一般为用户 ID
name	姓名
given_name	名字
family_name	姓氏
middle_name	中间名
nickname	昵称
preferred_username	希望被称呼的名字
profile	基础资料
picture	头像
website	网站链接
email	电子邮箱
email_verified	邮箱是否被认证
gender	性别
birthdate	生日
zoneinfo	时区
locale	区域
phone_number	手机号
phone_number_verified	认证手机号
address	地址对象
address.formatted	详细地址
address.street_address	街道地址
address.locality	城市
address.region	省
address.postal_code	邮编
address.country	国家
updated_at	信息更新时间

¶ 刷新 Access Token

// GetNewAccessTokenByRefreshToken
//   使用 Refresh token 获取新的 Access token
func (c *Client) GetNewAccessTokenByRefreshToken(refreshToken string) (string, error)

使用 Refresh token 获取新的 Access token。

¶ 参数

refreshToken <string> Refresh token，可以从 GetAccessTokenByCode 方法的返回值中的 refresh_token 获得。

¶ 示例

resp, err := authenticationClient.GetNewAccessTokenByRefreshToken("refreshToken")

¶ 示例数据

{
  "access_token": "fa9d2bdd914ea01aa4e434c12d4f919d749fc75c",
  "token_type": "Bearer",
  "expires_in": 1209599,
  "refresh_token": "b5e0e1afe793c6634495434afc262b88ddee9af3",
  "scope": "user"
}

¶ 检查 Access token 或 Refresh Token

// IntrospectToken
// 检查 Access token 或 Refresh token 的状态
func (c *Client) IntrospectToken(token string) (string, error)

检查 Access Token 或 Refresh Token 的状态。

¶ 参数

token <string> Access token 或 Refresh token，可以从 GetAccessTokenByCode 方法的返回值中的 access_token、refresh_token 获得。

¶ 示例

    authenticationClient := NewClient("appid", "sec")
	authenticationClient.Host = "host"
	authenticationClient.RedirectUri = "https://redirectUrl.com/"
	authenticationClient.Protocol = constant.OAUTH
	authenticationClient.TokenEndPointAuthMethod = constant.None

	resp, err := authenticationClient.IntrospectToken("token")

¶ 示例数据

Token 合法时返回：

{
  "active": true,
  "sub": "5f719946524ee1099229496b", // subject 的缩写，为用户 ID
  "client_id": "5f17a529f64fb009b794a2ff",
  "exp": 1619083024,
  "iat": 1617873424,
  "iss": "https://core.authing.cn/oauth",
  "jti": "qbovGK-HZL0O_20wY7uXj",
  "scope": "user",
  "token_type": "Bearer"
}

Token 不合法时返回：

{
  "active": false
}

检验过程失败会抛出错误。

¶ 撤回 Access Token 或 Refresh token

// RevokeToken
// 撤回 Access token 或 Refresh token
func (c *Client) RevokeToken(token string) (string, error)

撤回 Access token 或 Refresh token。Access token 或 Refresh token 的持有者可以通知 Authing 已经不再需要令牌，希望 Authing 将其吊销。

¶ 参数

token <string> Access token 或 Refresh token，可以从 get_access_token_by_code 方法的返回值中的 access_token、refresh_token 获得。

¶ 示例

    authenticationClient := NewClient("appid", "sec")
	authenticationClient.Host = "https://demo.authing.cn"
	authenticationClient.RedirectUri = "https://mvnrepository.com/"
	authenticationClient.Protocol = constant.OAUTH
	authenticationClient.TokenEndPointAuthMethod = constant.None
	resp, err := authenticationClient.RevokeToken("token")

¶ 示例数据

撤回成功时返回 true。

撤回失败时抛出错误。

¶ 拼接登出 URL

//BuildLogoutUrl
//拼接登出 URL
func (c *Client) BuildLogoutUrl(expert, redirectUri, idToken *string) string

拼接登出 URL，用户可以通过此链接退出登录。

¶ 参数

expert <string> 忽视即可
redirectUri <string> 登出后的重定向地址。
idToken <string> 忽视即可

¶ 示例

url = authentication_client.BuildLogoutUrl(nil,"http://localhost:3000",nil)

¶ SAML2

安全断言标记语言（英语：Security Assertion Markup Language，简称 SAML，发音 sam-el）是一个基于 XML 的开源标准数据格式，它在当事方之间交换身份验证和授权数据，尤其是在身份提供者和服务提供者之间交换。

¶ 初始化

appId <string> 应用 ID，必填。
appHost <string> 应用完整地址，如 https://sample-app.authing.cn，不带最后的斜线 '/'。
protocol <string> 协议类型，可选值为 oidc、oauth、saml、cas，此处填写 saml。

¶ 示例

    authenticationClient := NewClient("appid", "sec")
	authenticationClient.Host = "https://demo.authing.cn"
	authenticationClient.RedirectUri = "https://mvnrepository.com/"
	authenticationClient.Protocol = constant.SAML

¶ 生成 SAML2 协议的用户登录链接

func (c *Client) BuildAuthorizeUrlBySaml() string

生成 SAML2 协议的用户登录链接。

¶ 参数

无

¶ 示例

url = authenticationClient.BuildAuthorizeUrlBySaml()

¶ 示例数据

https://oidc1.authing.cn/api/v2/saml-idp/5f17a529f64fb009b794a2ff

¶ 拼接登出 URL

//BuildLogoutUrl
//拼接登出 URL
func (c *Client) BuildLogoutUrl(expert, redirectUri, idToken *string) string

拼接登出 URL，用户可以通过此链接退出登录。

¶ 参数

expert <string> 忽视即可。
redirectUri <string> 登出后的重定向地址。
idToken <string> 忽视即可。

¶ 示例

    authenticationClient := NewClient("appid", "sec")
	authenticationClient.Host = "https://demo.authing.cn"
	authenticationClient.RedirectUri = "https://mvnrepository.com/"
	authenticationClient.Protocol = constant.SAML
    url = authenticationClient.BuildLogoutUrl("http://localhost:3000")

¶ 示例数据

https://oidc1.authing.cn/login/profile/logout?redirect_uri=https://authing.cn

¶ CAS

CAS 是 Central Authentication Service 的缩写，中央认证服务，一种独立开放指令协议。

¶ 初始化

appId <string> 应用 ID，必填。
appHost <string> 应用完整地址，如 https://sample-app.authing.cn，不带最后的斜线 '/'。
protocol <string> 协议类型，可选值为 oidc、oauth、saml、cas，此处填写 cas。

¶ 示例

    authenticationClient := NewClient("appid", "sec")
	authenticationClient.Host = "https://demo.authing.cn"
	authenticationClient.RedirectUri = "https://mvnrepository.com/"
	authenticationClient.Protocol = constant.CAS

¶ 生成 CAS 协议的用户登录链接

func (c *Client) BuildAuthorizeUrlByCas(service *string) string

生成 CAS 协议的用户登录链接。

¶ 参数

无

¶ 示例

    authenticationClient := NewClient(AppId, Secret)
	authenticationClient.userPoolId = UserPool
	authenticationClient.Protocol = constant.CAS
	resp, ee := authenticationClient.BuildAuthorizeUrlByCas("service")

¶ 示例数据

https://oidc1.authing.cn/cas-idp/5f17a529f64fb009b794a2ff/login?service=https://example.com

¶ 检验 CAS 1.0 Ticket 合法性

// ValidateTicketV1
// 检验 CAS 1.0 Ticket 合法性
func (c *Client) ValidateTicketV1(ticket, service string) (*struct {
	Valid    bool   `json:"code"`
	Message  string `json:"message"`
	Username string `json:"username"`
}, error)

检验 CAS 1.0 Ticket 合法性。

¶ 参数

ticket <string> CAS 认证成功后，Authing 颁发的 ticket。
service <string> CAS 回调地址。

¶ 示例

    authenticationClient := NewClient(AppId, Secret)
	authenticationClient.userPoolId = UserPool
	authenticationClient.Protocol = constant.CAS
	resp, ee := authenticationClient.ValidateTicketV1("ticket 内容","service 地址")

¶ 示例数据

ticket 合法时返回：

{
  "valid": true,
  "username": "user1"
}

ticket 不合法时返回：

{
  "valid": false,
  "message": "ticket 不合法"
}

¶ 拼接登出 URL

//BuildLogoutUrl
//拼接登出 URL
func (c *Client) BuildLogoutUrl(expert, redirectUri, idToken *string) string

拼接登出 URL，用户可以通过此链接退出登录。

¶ 参数

expert <string> 忽视即可。
redirectUri <string> 登出后的重定向地址。
idToken <string> 忽视即可。

¶ 示例

    authenticationClient := NewClient("appid", "sec")
	authenticationClient.Host = "https://demo.authing.cn"
	authenticationClient.RedirectUri = "https://mvnrepository.com/"
	authenticationClient.Protocol = constant.CAS
    url = authenticationClient.BuildLogoutUrl("http://localhost:3000")

¶ 示例数据

https://oidc1.authing.cn/cas-idp/5f17a529f64fb009b794a2ff/logout?service=https://example.com

上一篇: 认证核心模块下一篇: 多因素认证模块