Umi Max 项目集成 Keycloak 认证的完整指南

前言

在现代前端开发中，认证授权是每个应用都需要考虑的重要环节。本文将详细介绍如何在 Umi Max 项目中集成 Keycloak 认证系统，实现单点登录(SSO)功能。Keycloak 是一个开源的身份和访问管理解决方案，提供了强大的认证授权功能。

准备工作

在开始集成前，请确保你已经具备以下条件：

1. 已经部署好 Keycloak 服务
2. 在 Keycloak 中创建了相应的 realm 和 client
3. 熟悉 Umi Max 项目的基本结构

配置 Keycloak 参数

首先，我们需要创建一个配置文件来存储 Keycloak 的基本信息：

// utils/keycloak.ts
export const keycloakConfig = {
  url: 'https://your-keycloak-domain.com/auth/', // Keycloak 服务地址
  realm: 'sso', // 领域名称
  clientId: 'mydemo_client' // 客户端ID
};

实现 SSO 登录页面

接下来，我们创建一个专门的 SSO 登录页面来处理 Keycloak 认证流程：

// pages/sso.tsx
import { keycloakConfig } from '@/utils/keycloak';
import { history } from '@umijs/max';
import Keycloak from 'keycloak-js';
import React, { useEffect, useState } from 'react';

const authInstance = new Keycloak(keycloakConfig);

const SSO: React.FC = () => {
  const [kcInitialized, setKcInitialized] = useState(false);

  useEffect(() => {
    if (kcInitialized) {
      history.push('/home');
    } else {
      authInstance
        .init({ onLoad: 'login-required' }) // 强制登录
        .then((authenticated: any) => {
          if (authenticated) {
            setKcInitialized(true);
            // 存储认证信息
            localStorage.setItem('token', authInstance.token || '');
            localStorage.setItem('user_type', 'sso');
            // 加载用户信息
            authInstance.loadUserInfo().then((data: any) => {
              localStorage.setItem('user', data.preferred_username);
              history.push('/home');
              window.location.reload();
            });
          }
        })
        .catch(() => {
          window.location.reload();
        });
    }
  }, []);

  return <>重定向...</>;
};

export default SSO;

修改登录页面

在原有的登录页面中添加 SSO 登录选项：

<LoginForm
  title="xxx demo"
  onFinish={async (values: any) => {
    await handleSubmit(values);
  }}
  actions={
    <Space>
      其他登录方式:{' '}
      <a
        onClick={async () => {
          history.push('/sso');
        }}
      >
        sso 统一登录
      </a>
    </Space>
  }
>

纯 SSO 认证方案

如果项目不需要本地登录，可以完全依赖 Keycloak 认证，可以在 app.tsx 中直接初始化 Keycloak：

import Keycloak from "keycloak-js";
import {keycloakConfig} from "@/utils/keycloak";

const authInstance = new Keycloak(keycloakConfig);

const fetchUserInfo = async () => {
  await authInstance
    .init({ onLoad: 'login-required' })
    .then((authenticated: any) => {
      if (authenticated) {
        localStorage.setItem('token', authInstance.token || '');
        localStorage.setItem('user_type', 'sso');
        authInstance.loadUserInfo().then((data: any) => {
          localStorage.setItem('user', data.preferred_username);
        });
      } else {
        history.push('/login');
        window.location.reload();
      }
    })
    .catch(() => {
      history.push('/login');
      window.location.reload();
    });
  return undefined;
};

export async function getInitialState(): Promise<{ token: string | null }> {
  await fetchUserInfo()
  const token = localStorage.getItem('token');
  return { token: token};
}

关键点解析

1. Keycloak 初始化：使用 keycloak-js 库初始化 Keycloak 客户端，配置认证参数。

2. 认证流程：通过 init 方法启动认证流程，onLoad: 'login-required' 参数确保用户必须登录。

3. 用户信息处理：认证成功后，使用 loadUserInfo 方法获取用户信息并存储在本地。

4. 状态管理：将认证令牌和用户信息存储在 localStorage 中，方便应用其他部分使用。

5. 错误处理：添加了认证失败的处理逻辑，确保用户体验。

最佳实践建议

1. 令牌刷新：Keycloak 令牌有过期时间，建议实现自动刷新逻辑。

2. 安全存储：考虑使用更安全的存储方式替代 localStorage。

3. 用户信息管理：可以封装用户信息获取逻辑，提供统一的接口。

4. 多环境配置：为不同环境(开发、测试、生产)配置不同的 Keycloak 参数。

5. 错误监控：添加认证错误的监控和日志记录。

总结

通过本文的介绍，我们了解了如何在 Umi Max 项目中集成 Keycloak 认证系统。无论是作为辅助登录方式还是作为主要认证手段，Keycloak 都能提供强大而灵活的身份验证解决方案。根据项目需求，可以选择合适的集成方式，并在此基础上进行扩展和优化。