身份验证钩子

为了定制OIDC身份认证流程，飞布提供了3种类型的钩子：认证钩子、重校验钩子、登出钩子。

认证钩子

首先，我们学习登录过程中，需要用到的钩子——认证钩子。

它在用户完成OIDC供应商授权后触发，若想重复触发，需要先退出客户端和飞布服务的登录态，无需退出客户端和oidc供应商的登录态！

认证钩子有2个，先执行postAuth，在执行mutatingpost。

postAuth

postAuthentication 钩子又名认证前置钩子，在身份验证已经验证并且用户已经通过身份验证之后执行。

主要用例：

• 同步OIDC用户至自己的数据库

http://{serverAddress}/authentication/postAuthentication

Example:: http://localhost:9992/authentication/postAuthenthication

Content-Type: application/json
X-Request-Id: "83821325-9638-e1af-f27d-234624aa1824"

# JSON request
{
  "__wg": {
    "clientRequest": {},
    "user": {
      "access_token": "<secret>", // 访问令牌
      "id_token": "<secret>" // ID令牌
    }
  }
}

# JSON response
no response

golang

func PostAuthentication(hook *base.AuthenticationHookRequest) error {
	user := hook.User
	// 将用户同步到数据库
	upsertRes, err := plugins.ExecuteInternalRequestMutations[generated.Lesson0305__UpsertUserInput, generated.Lesson0305__UpsertUserResponseData](hook.InternalClient, generated.Lesson0305__UpsertUser, generated.Lesson0305__UpsertUserInput{
		UserId: user.UserId,
		Create: &generated.Todo_UserCreateInput{
			ProviderId: user.ProviderId,
			UserId:     user.UserId,
			Name:       user.Name,
			Nickname:   user.NickName,
			Email:      "E" + user.Email,
		},
		Update: &generated.Todo_UserUpdateInput{
			Name: &generated.Todo_StringFieldUpdateOperationsInput{
				Set: user.Name,
			},
			Nickname: &generated.Todo_StringFieldUpdateOperationsInput{
				Set: user.NickName,
			},
			Email: &generated.Todo_StringFieldUpdateOperationsInput{
				Set: "E" + user.Email,
			},
		},
	})
	if err != nil {
		return err
	}
	fmt.Println(upsertRes)
	return nil
}

mutatingPostAuth

mutatingPostAuthentication 钩子又名认证后置钩子，钩子在用户登录并验证身份后执行，可以用来在用户对象返回给客户端之前改变它。

主要用例：

• 为用户绑定角色

• 中断认证流程

http://{serverAddress}/authentication/mutatingPostAuthentication

Example:: http://localhost:9992/authentication/mutatingPostAuthentication

Content-Type: application/json
X-Request-Id: "83821325-9638-e1af-f27d-234624aa1824"

# JSON request
{
  "__wg": {
    "clientRequest": {},
    "user": {
      "access_token": "<secret>", // 访问令牌
      "id_token": "<secret>" // ID令牌
    }
  }
}

# JSON response
{
  "hook": "mutatingPostAuthentication",
  "response": {
    "status": "ok", // 枚举值，ok或deny， deny表示拒绝登录
    "message": "not ok message", // 可选，为deny时填写
    "user": { // 可选，为ok时填写
      "userID": "1",
      "roles":["admin"] // 为用户修改角色
    }
  }
}

golang

func MutatingPostAuthentication(hook *base.AuthenticationHookRequest) (*plugins.AuthenticationResponse, error) {
	user := hook.User
	user.Roles = []string{"user", "asssitent"}
	// 修改用户的角色
	return &plugins.AuthenticationResponse{User: user, Status: "ok"}, nil
}

两者的区别是，前者无法修改user对象，后者可以修改user或终止流程。其返回参数包含，user\status\以及message。

值得注意的是，这两个钩子的user，是从oidc拿到的原始user。而其他钩子的user，可能经由mutatingpost修改过了。详情可以参考时序图！

隐式模式

除了授权码模式，隐式模式也支持认证钩子。下面是其时序图。

当用户使用access_token访问任意OPERATION生成的接口时，都会走该流程。

第一次使用时，先去authing上获取用户信息，然后执行post钩子，接着执行mutatingpost钩子，并缓存用户信息。后续使用时，直接用缓存，不走钩子。

此外，若请求OPERATION 接口时，加上了revalidate后缀，则不用缓存，必走钩子。

总结下，第一次访问时，认为是登录，后续有了登录态，就不走登录流程了。

重校验钩子

revalidateAuthentication 钩子又名重校验钩子，引擎重新验证用户身份时执行。

主要用例：

• 在不退出登录的情况下，更新用户的信息，如角色等

OIDC 授权码模式和隐式模式调用该构造的方式不同。

• token模式（隐式模式）：携带access token请求任意OPERATION接口且携带revalidate字段，例如：operations/op?revalidate=true，同时调用3个钩子，包括revalidate

• cookie模式（授权码模式）：携带cookie，请求auth/user端点且携带revalidate字段，例如：/auth/user?revalidate=true

详情请参考：授权码模式->登录流程

http://{serverAddress}/authentication/revalidateAuthentication

Example:: http://localhost:9992/authentication/revalidateAuthentication

Content-Type: application/json
X-Request-Id: "83821325-9638-e1af-f27d-234624aa1824"

# JSON request
{
  "__wg": {
    "clientRequest": {},
    "user": {
      "access_token": "<secret>", // 访问令牌
      "id_token": "<secret>" // ID令牌
    }
  }
}

# JSON response
{
  "hook": "mutatingPostAuthentication",
  "response": {
    "status": "ok", // 枚举值，ok或deny， deny表示拒绝登录
    "message": "not ok message", // 可选，为deny时填写
    "user": { // 可选，为ok时填写
      "userID": "1",
      "roles":["admin"] // 为用户修改角色
    }
  }
}

golang

func Revalidate(hook *base.AuthenticationHookRequest) (*plugins.AuthenticationResponse, error) {
	fmt.Println("Revalidate", hook.User.UserId)
	user := hook.User
	user.Roles = []string{"system"}

	return &plugins.AuthenticationResponse{
		Status: "ok",
		User:   user,
	}, nil
}

登出钩子

postLogout 钩子又名登出钩子，在用户注销后执行。该钩子处于身份验证生命周期的最后一环，主要用于做些收尾操作。

主要用例：

• 记录用户登出时间

客户端请求退出登录端点时，会触发退出登录钩子。

http://{serverAddress}/authentication/postLogout

Example:: http://localhost:9992/authentication/postLogout

Content-Type: application/json
X-Request-Id: "83821325-9638-e1af-f27d-234624aa1824"

# JSON request
{
  "__wg": {
    "clientRequest": {},
    "user": {
      "access_token": "<secret>", // 访问令牌
      "id_token": "<secret>" // ID令牌
    }
  }
}

# JSON response
no response

golang

func PostLogout(hook *base.AuthenticationHookRequest) error {

	fmt.Println(hook.User)
	return nil
}