Skip to content

OAuth2 服务器

目前文档内容对标 ballcat v0.2.0 以上版本

授权服务器

Ballcat 中的授权服务器是基于 spring-security-oauth2 项目实现的,该项目现已被 Spring 标记为弃用,但是新的授权服务器 Spring 团队还在孵化中,未达到生产可用状态,所以暂时无法更新。

新的授权服务器已经发布,使用相关请移步 Ballcat Spring Authorization Server

首先,根据 OAuth2 中的定义,授权服务器本身也可以是一个资源服务器

在使用 ballcat 构建的单体应用中,授权服务器和资源服务器肯定是在一起的,但是为了方便扩展,在代码层面,Ballcat 将授权服务器和资源服务的代码做了分离:

核心模块 ballcat-common-security 模块中,是对于 spring-security 使用的基本封装,OAuth2User 实体的定义等双方需要共享的部分,授权服务器和资源服务器都会使用。

由于资源服务器的配置较少,所以其相关代码也在 common-security 中,但默认是不开启的。

ballcat 中关于授权服务器的代码处理在以下模块中:

ballcat-auth
|-ballcat-auth-biz		 // 授权服务的相关配置、Token 增强、异常处理等
|-ballcat-auth-controller  // 登出接口

引入上述依赖后,通过在配置上添加 @EnableOauth2AuthorizationServer 注解以达到自动开启授权服务器相关配置的功能。

目前授权服务器强关联 ballcat-system 相关业务模块

验证码开关

授权服务器默认集成了基于 anji-captch 的登录验证码,用户可以通过以下配置关闭验证码的校验:

yaml
ballcat:
	security:
		oauth2:
			authorizationserver:
				login-captcha-enabled: false  # 登录验证码开关,默认开启

登录返回信息

spring-security-oauth2 的令牌端点地址为:”/oauth/token“,其默认的返回数据仅仅只有以几个:

json
{
    "access_token":"2YotnFZFEjr1zCsicMWpAA",
    "token_type":"example",
    "expires_in":3600,
    "refresh_token":"tGzv3JOkF0XG5Qx2TlKWIA",
    "scope": "server"
}

实际在业务开发中,我们还会有需要一些其他的信息,需要在登陆时返回,Ballcat 默认提供的 CustomTokenEnhancer 类中,额外添加了 用户的 权限,角色,以及用户自身的一些附属属性:

json
{
    "access_token":"2YotnFZFEjr1zCsicMWpAA",
    "token_type":"example",
    "expires_in":3600,
    "refresh_token":"tGzv3JOkF0XG5Qx2TlKWIA",
    "scope": "server",
    "attributes": {    // 用户附加属性
        "permissions": [  // 权限
            "system:role:grant",
            "notify:announcement:edit",
            "notify:announcement:read",
        ],
        "roles": [   // 角色
            "ROLE_ADMIN",
        ]
    },
    "info": {		// 用户信息
        "userId": 1,
        "username": "admin",
        "nickname": "超管牛逼",
        "avatar": "sysuser/1/avatar/20200226/ab6bd5221afe4238ae4987f278758113.jpg",
        "organizationId": 11,
        "type": 1
    }
}

用户可以通过自定义 TokenEnhancer 类,来覆盖 Ballcat 的默认行为,对登录的返回信息进行增删处理。

自省返回信息

spring-security-oauth2 的令牌自省端点地址为:”/oauth/check_token“

其返回信息也可以通过自定义 AccessTokenConverter 来进行定制处理,Ballcat 默认提供的CustomAccessTokenConverter 中,主要是针对客户端的权限,来控制是否将用户的所有 attributes 返回。

资源服务器

授权服务器是基于 spring-security 5.x 实现的,理论上来说,可以对接任何遵守 OAuth2 协议的资源服务器,Ballcat 在 security 之上针对自己的授权服务器和业务做了一些调整。

资源服务器的配置仅仅依赖于 ballcat-common-security ,引入此依赖后,通过 @EnableOauth2ResourceServer 即可开启授权服务器相关配置。

自定义配置

资源服务器提供了以下配置文件:

yaml
ballcat:
  security:
    oauth2:
      resourceserver:
      	## 是否禁止嵌入 iframe
      	iframe-deny: true
      	## 是否与资源服务器,共享token存储环境
      	shared-stored-token: true
      	## 不共享 token 存储环境时,需要远程鉴权
      	opaque-token:
      		# 客户端id
      		client-id:
            # 客户端密钥
      		client-secret:
      		# 令牌自省端点:授权服务器暴露出来的一个 url, 用于获取指定 token 的信息
      		introspection-uri: 
        ## 忽略鉴权的 url 列表,即允许匿名访问
        ignore-urls:
          - /public/**
  • ballcat.security.oauth2.resourceserver.shared-stored-token

    在单体应用,或者某些微服务架构下,授权服务器和资源服务器是共享 token 存储的。

    也就是说授权服务器将登录的 token 存储在数据库或者 redis 中,而资源服务器使用的是相同的数据库或者 redis,资源服务器又是知道授权服务器的存储格式的,这时为了减少资源服务器和授权服务器的交互开销,资源服务器可以不向授权服务器发起请求,而是自己直接去存储环境中读取对应的 token 信息。

  • ballcat.security.oauth2.resourceserver.opaque-token

    • client-id
    • client-secret
    • introspection-uri

    在授权服务器和资源服务器环境隔离的情况下,当用户携带 token 向资源服务器请求受保护的资源,资源服务器为了验证 token 的有效性,以及获取到 token 对应的一些用户信息,就需要向授权服务器发起 token 的自省请求。

    资源服务器本身也是一个客户端,配置的 client-id 和 client-secret 确定了其在 OAuth2 中的身份,资源服务器接收自省请求前会校验 client-id 和 client-secret 的有效性。

    introspection-uri 即是授权服务器的自省端点地址,ballcat 的授权服务器是基于 spring-security-oauth2 的,其默认的自省端点为 ”/oauth/check_token“

注意,仅当 ballcat.oauth2.resourceserver.shared-stored-token 为 false 时,自省端点的配置才会生效

Token 解析器

共享 Token 解析

在共享 token 存储时,ballcat 将会默认注册 SharedStoredOpaqueTokenIntrospector 解析器,其内部利用 spring-security-oauth2 提供的 TokenStroe ,调用 TokenStore#readAccessToken 方法直接进行 token 信息的解析。

自省端点解析

当配置为自省端点时,ballcat 将会注册 RemoteOpaqueTokenIntrospector,其内部会根据 check_token 端点的返回值,进行 token 信息的构建

自定义解析

用户可以根据自己的需要定制自己的解析器,只需实现 OpaqueTokenIntrospector, 并注册到 spring 中即可