<!-- Space: qifu -->
<!-- Parent: 后端技术&知识&规范 -->
<!-- Parent: 技术方案 -->
<!-- Parent: 基建 -->
<!-- Parent: 00-基础组件 -->
<!-- Title: 20250109-内部程序企微登入接入指南 -->

<!-- Macro: :anchor\((.*)\):
     Template: ac:anchor
     Anchor: ${1} -->
<!-- Macro: \!\[.*\]\((.+)\)\<\!\-\- width=(.*) \-\-\>
     Template: ac:image
     Url: ${1}
     Width: ${2} -->
<!-- Macro: \<\!\-\- :toc: \-\-\>
     Template: ac:toc
     Printable: 'false'
     MinLevel: 2 
     MaxLevel: 4 -->
<!-- Include: 杂项/声明文件.md -->

<!-- :toc: -->

# 单点登录使用说明

## 快速使用

### 引入依赖
```xml

<dependency>
    <groupId>com.yuanmeng.starter</groupId>
    <artifactId>starter-sso</artifactId>
    <version>1.0.12-SNAPSHOT</version>
</dependency>
```

### 开放授权登录端点
需要开放的端点列表：
- `/oauth/authorize/{client}`
- `/oauth/login/{client}`

- 其中 `{client}` 为变量，所以 需要匹配开放 `/oauth/authorize` 及 `/oauth/login` 下的所有路径
- 或者如果可以确定 `{client}`, 则开放替换 `{client}` 后的链接

### 编写 OauthLoginHandler 实现
- 编写 `OauthLoginHandler` 实现登录流程，并注入 `Bean`
- 示例：

```java
import com.alibaba.fastjson.JSONObject;

public class DefaultOauthLoginHandler implements OauthLoginHandler {

    @Override
    public Serializable loginSuccessHandle(AuthUser authUser,
                                           YuanMengOauthProperties.OauthProperties oauthProperties) {
        // TODO 获取用户名
        String username = authUser.getUsername();
        // TODO 查询用户
        User user = xxxDao.selectUserByUsername(username);
        // TODO 业务登录逻辑
        String token = xxxLoginService.login(user);
        // TODO 组装登录结果
        JSONObject loginResult = new JSONObject();
        loginResult.put("token", token);
        // 返回结果
        return loginResult;
    }

}
```

### 配置文件配置
```yaml
yuanmeng:
  starter:
    oauth:
      config-map:
        #- 自定义 {client}
        customClient:
          #- idp 类型
          auth-source: KEYCLOAK
          #- Keycloak 客户端ID 
          client-id: "xxx"
          #- Keycloak 客户端Secret
          client-secret: "secret"
          scopes:
            - openid
            - profile
            - email
          #- 某个界面或者直接请求该服务后端接口：http://xxx/oauth/login/{client}
          #- 这边的 {client} 为 customClient
          redirect-uri: "某个界面或者直接：http://xxx/oauth/login/customClient"
          #- 当 redirect-uri 配置为后端接口时需要配置，
          #- 登录成功后会把登录结果拼接到这个链接后面进行跳转
          #- 配置后请求 login 接口会根据这个链接做跳转，如果 redirect-uri 有页面承接这边就不需要配置
          login-after-redirect-uri: ""
```

### 前端处理
#### 方案一：授权承接界面（建议）
##### 第一步：
- 登录界面添加企业微信登录按钮，按钮跳转链接：`http://test-pmsystem.qifu.com/oauth/authorize/pm-client`
- 域名需要根据环境变更

##### 第二步：
- 添加一个空白界面做跳转和登录。下面简称 `跳转界面`
- `跳转界面` 请求路径需要给后端，后端配置到 `redirect-uri` 上
- 点击企业微信登录按钮后会授权及跳转到 `跳转界面` 并再连接后携带上授权参数
- `跳转界面` 使用接收到的参数请求登录接口。使用 `GET` 请求。例如 `GET http://test-pmsystem.qifu.com/oauth/login/pm-client?code=xxxx&state=xxx`
- 请求结果为登录信息，根据请求结果做对应处理就行

#### 方案二：登录成功处理界面
- 后端直接把 `redirect-uri` 配置为登录接口 `http://xxx/oauth/login/{client}`
- 前端给一个可以承接登录成功信息处理的界面
- 后端将页面链接配置到 `login-after-redirect-uri` 中
- 前端在页面中解析对应登录信息进行处理