在

系统运维

一、简介

MaxKey概述

MaxKey单点登录认证系统是业界领先的IAM-IDaas身份管理和认证产品，谐音为马克思的钥匙，寓意它能够像一把万能钥匙(最大钥匙)一样，解锁复杂的企业安全需求，提供简洁而高效的解决方案。产品支持OAuth 2.x/OpenID Connect、SAML 2.0、JWT、CAS、SCIM等标准协议，提供安全、标准和开放的用户身份管理(IDM)、身份认证(AM)、单点登录(SSO)、RBAC权限管理和资源管理等。

官方QQ：1054466084

邮箱EMAIL: support@maxsso.net

代码托管 GitHub | 码云(Gitee)

什么是单点登录

单点登录(Single Sign On)*简称为*SSO

用户只需要登录认证中心一次就可以访问所有相互信任的应用系统，无需再次登录，主要功能：

1.所有应用系统共享一个身份认证系统

2.所有应用系统能够识别和提取ticket信息

标准协议

序号	协议	支持
1	OAuth 2.x/OpenID Connect	高
2	SAML 2.0	高
3	JWT	高
4	CAS	高
5	FormBased	中
6	TokenBased(Post/Cookie)	中
7	ExtendApi	低
8	EXT	低

登录支持

序号	登录方式	类型
1	图片验证码	字母/数字/算术
2	双因素认证	短信或者邮件动态验证码
3	短信认证	腾讯云短信/阿里云短信/网易云信
4	TOTP或者HOTP动态口令	Google/Microsoft Authenticator/FreeOTP/支持TOTP或者HOTP
5	Windows域认证	Kerberos/SPNEGO/AD域
6	LDAP认证	OpenLDAP/ActiveDirectory/标准LDAP服务器
7	社交账号	微信/QQ/微博/钉钉/Google/Facebook/其他
8	扫码登录	企业微信/钉钉/飞书扫码登录

产品优势

提供标准的认证接口以便于其他应用集成SSO，安全的移动接入，安全的API、第三方认证和互联网认证的整合。
提供用户生命周期管理，支持SCIM 2协议；开箱即用的连接器(Connector)实现身份供给同步。
简化微软Active Directory域控、标准LDAP服务器机构和账号管理，密码自助服务重置密码。
认证多租户功能，支持集团下多企业独立管理或企业下不同部门数据隔离的，降低运维成本。
认证中心具有平台无关性、环境多样性，支持Web、手机、移动设备等, 如Apple iOS，Andriod等，将认证能力从B/S到移动应用全面覆盖。
基于Java EE平台，微服务架构，采用Spring、MySQL、Tomcat、Redis、MQ等开源技术，扩展性强。
开源、安全、合规、自主可控，许可证 Apache 2.0 License 。

二、部署步骤

参照：https://www.maxkey.top/doc/docs/install/deploy_docker_compose

1、上传配置文件

   # 在你的服务器中，进入根目录（根据需求更改，此处按照官方文档）
   cd /root
   # 从官方仓库拉取 docker 配置目录
   git clone https://github.com/dromara/MaxKey.git

   # 附：网页路径——
   # https://gitee.com/dromara/MaxKey/tree/main/docker
   # 或者
   # https://github.com/dromara/MaxKey/tree/main/docker

   # 进入docker目录
   cd /root/MaxKey/docker/
   # 注意看里面有docker-compose.yml文件

2、启动服务

   # 构建并启动所有服务，以后台运行
   docker-compose up --build -d

三、应用访问

序号	名称	访问地址
1	用户端前端	http://192.168.201.202:80/maxkey/
2	管理端前端	http://192.168.201.202:80/maxkey-mgt/
3	账户	admin
4	密码	maxkey

首页 / 导航页（官方配置的 /）：

http://192.168.201.202:80/

显示 Nginx 提供的首页（index.html），可以放导航按钮。

核心认证接口（Sign）：

http://192.168.201.202:80/sign/

访问时会由 Nginx 转发到 maxkey:9527/sign/

用户端前端：

http://192.168.201.202:80/maxkey/

访问时 Nginx 代理到 maxkey-frontend:8527/maxkey/
浏览器地址栏显示 /maxkey/，用户访问统一入口

管理端前端：

http://192.168.201.202:80/maxkey-mgt/

Nginx 代理到 maxkey-mgt-frontend:8526/maxkey-mgt/

管理端 API：

http://192.168.201.202:80/maxkey-mgt-api/

用于后台接口调用，通常前端页面自动访问即可，不需要用户直接打开

1、Nginx 配置

MaxKey 默认 Nginx 配置会自动转发请求到前端服务（8527、8526等）。

官方安装后默认配置

位置在宿主机的 ./docker-nginx 目录——映射到容器内 /etc/nginx/conf.d

 #MaxKey nginx Proxy Server
 
 server {
     listen       80;
 
     server_name  localhost;
     
     proxy_set_header host $host; # 转发请求时将请求的域名一起转发
 
     location / {
         root   /usr/share/nginx/html;
         index  index.html index.htm;
         try_files $uri $uri/ /index.html;
     }
     
     #服务器集群路径
     #认证后端
     location /sign/ {
         proxy_pass http://maxkey:9527/sign/;
     }
     
     #认证前端
     location /maxkey/ {
         proxy_pass http://maxkey-frontend:8527/maxkey/;
     }
     
     #管理后端
     location /maxkey-mgt-api/ {
         proxy_pass http://maxkey-mgt:9526/maxkey-mgt-api/;
     }
     
     #管理前端
     location /maxkey-mgt/ {
         proxy_pass http://maxkey-mgt-frontend:8526/maxkey-mgt/;
     }
 
     error_page   500 502 503 504  /50x.html;
     location = /50x.html {
         root   /usr/share/nginx/html;
     }
 }

2、docker结构说明

容器名	镜像	端口	功能说明
maxkey-mysql	mysql:8.4.2	3306	数据库容器，用来存储用户、应用、认证记录等数据。初始化时自动建表。
maxkey	maxkeytop/maxkey:latest	9527	核心认证服务（SSO核心），负责OAuth2、CAS、SAML、OIDC等协议认证与令牌颁发。
maxkey-frontend	maxkeytop/maxkey-frontend:latest	8527	对应用户的登录门户界面（相当于企业登录首页）。
maxkey-mgt	maxkeytop/maxkey-mgt:latest	9526	管理后台后端 API 服务（管理员操作逻辑）。
maxkey-mgt-frontend	maxkeytop/maxkey-mgt-frontend:latest	8526	管理后台前端界面（管理员访问用）。
maxkey-nginx	nginx:latest	80	Web 反向代理入口，可统一访问 `http://IP:80/`。内部代理到前后端服务。

四、使用说明

1、Ldap配置

——1——

2、组织

——2——

3、用户

——3——

4、用户组

——4——

5、用户组成员

——5——

6、访问控制

——6——

7、同步器控制

——7——

8、应用管理

MaxKey与常用应用集成参照：https://www.maxkey.org/zh/am/inteapps【版本较老，接口可能发生变化，注意关注新版本文档】

最新版本应用集成地址参照：https://www.maxkey.top/doc/docs/am/integration/gitlab【已测试成功】

GitLab集成指南

配置Gitlab

编辑 gitlab.rb

 vim /etc/gitlab/gitlab.rb

增加 Oauth 配置：

 gitlab_rails['omniauth_enabled'] = true
 gitlab_rails['omniauth_allow_single_sign_on'] = ['oauth2_generic'] #跟下⾯的 name 对应，不建议修改
 gitlab_rails['omniauth_block_auto_created_users'] = false # 是否⾃动创建账号
 gitlab_rails['omniauth_providers'] = [
     {
         'name' => 'oauth2_generic', #此处跟maxke配置的回调地址有关系
         'label': 'SSO', # 此处显示在 SSO 授权登录的名称
         'app_id' => '820990393884606464',
         'app_secret' => 'F3QOMTUwMzIwMjExMTMyMTAzNDknMW',
         'args' => {
             client_options: {
                 'site' => 'http://192.168.201.202:80/maxkey', # maxkey 认证端的域名
                 'authorize_url'=>'/sign/authz/oauth/v20/authorize',
                 'token_url'=>'/sign/authz/oauth/v20/token',
                 'user_info_url' => '/sign/api/oauth/v20/me'
             },
             user_response_structure: {
                 root_path: [],
                 id_path: ['username'],
                 attributes: { name: 'realname', email: 'username'}
             },
             #name: 'maxkey',
             strategy_class: "OmniAuth::Strategies::OAuth2Generic"
         }
     }
 ]

重新启动 gitliab

 docker restart gitlab

等待gitlab启动完成

确保有一个Gitlab账号和一个maxkey账号

关联 Gitlab 账号

⽤户登录 gitlab 之后，在 setting-Account 中点击 Connect 进⾏账户关联。

——8-1——

——8-2——

关联成功后，即可使⽤登录⻚的 Oauth2 登录。

注意事项

Gitlab 必须要⼿动关联后，才可单点登录。 https 需要配置 omiauth 的 provider_ignores_state:true，同时需要把 maxkey 的证书放到 gitlab 的 trusted-certs 下，然后重新配置 gitlab-ctl reconfigure 就好了。

MaxKey 配置及登录验证

应⽤配置

进⼊后台”应⽤管理” ，编辑应⽤

——8-3——

——8-4——

——8-5——

应⽤访问赋权

如果不在该列表内，可以“新增成员”

单点登录验证

重新登录 MaxKey，点击”Gitlab”图标单点登录

五、常见问题

1、MySQL一直重启——CPU 指令集不兼容

 [root@localhost docker]# docker logs -f maxkey-mysql
 Fatal glibc error: CPU does not support x86-64-v2

🚨 问题原因

这是 CPU 指令集不兼容 导致的。

MySQL 官方最新版（8.4.2）是为 x86-64-v2 或更高架构 编译的。

✅ 解决方案

Proxmox上把虚拟机 CPU 类型从 kvm64 改为 host，重启，就可以解决这个 “CPU does not support x86-64-v2” 的问题。

2、开源版 MaxKey 与 LDAP 的同步方向

默认情况下，MaxKey 开源版的 LDAP 同步是单向的，即：

只从 LDAP → MaxKey 同步

不会把 MaxKey 里的变更（如修改密码、添加用户）反向写入到 LDAP。

六、附加方案

1、实现统一入口 + 跳转页

步骤 1️⃣：在宿主机 `./docker-nginx/html` 下创建文件

 mkdir -p /root/MaxKey/docker/docker-nginx/html
 cd /root/MaxKey/docker/docker-nginx/html
 nano index.html

index.html

 <!DOCTYPE html>
 <html lang="zh-CN">
 <head>
   <meta charset="UTF-8">
   <title>MaxKey 登录入口</title>
   <style>
     /* 全局样式 */
     * { margin: 0; padding: 0; box-sizing: border-box; }
     body {
       font-family: "Microsoft Yahei", sans-serif;
       display: flex;
       justify-content: center;
       align-items: center;
       height: 100vh;
       background: linear-gradient(135deg, #4facfe 0%, #00f2fe 100%);
       color: #333;
     }
 
     /* 容器 */
     .container {
       background: white;
       padding: 40px 60px;
       border-radius: 16px;
       box-shadow: 0 15px 35px rgba(0,0,0,0.2);
       text-align: center;
       max-width: 400px;
       width: 100%;
       animation: fadeIn 1s ease-in-out;
     }
 
     /* 动画效果 */
     @keyframes fadeIn {
       from { opacity: 0; transform: translateY(-20px); }
       to { opacity: 1; transform: translateY(0); }
     }
 
     h1 {
       font-size: 26px;
       margin-bottom: 30px;
       color: #222;
     }
 
     /* 按钮样式 */
     .btn {
       display: block;
       margin: 15px auto;
       padding: 14px 0;
       width: 100%;
       background: #007bff;
       color: white;
       font-size: 16px;
       font-weight: 500;
       text-decoration: none;
       border-radius: 10px;
       box-shadow: 0 5px 15px rgba(0,0,0,0.1);
       transition: all 0.3s ease;
     }
 
     .btn:hover {
       background: #0056b3;
       transform: translateY(-3px);
       box-shadow: 0 10px 20px rgba(0,0,0,0.2);
     }
 
     /* 页脚小提示 */
     .footer {
       margin-top: 25px;
       font-size: 12px;
       color: #777;
     }
   </style>
 </head>
 <body>
   <div class="container">
     <h1>欢迎使用 MaxKey 统一认证系统</h1>
     <a class="btn" href="http://192.168.201.202:8080/maxkey/" target="_blank">👥 用户登录门户</a>
     <a class="btn" href="http://192.168.201.202:8080/maxkey-mgt/" target="_blank">🛠 管理后台</a>
     <div class="footer">© 2025 MaxKey</div>
   </div>
 </body>
 </html>

步骤 2️⃣：保持-不修改Nginx 配置文件

保持和官方一致，只需确保 / 根路径指向刚才的 index 页面：

步骤 3️⃣：将导航页挂载进 Nginx 容器

编辑 docker-compose.yml：

 maxkey-nginx:
   image: nginx:latest
   container_name: maxkey-nginx
   hostname: maxkey-nginx
   volumes:
     - ./docker-nginx:/etc/nginx/conf.d
     - ./docker-nginx/html:/usr/share/nginx/html     # ✅ 新增这一行
   ports:
     - "8080:80"
   networks:
     - maxkey.top
   restart: always

步骤 4️⃣：重新加载

 docker compose down
 docker compose up -d

访问： 👉 http://192.168.201.202:8080

你就能看到一个简洁的菜单页点击按钮即可跳转用户门户 / 管理后台🎯

七、附：MaxKey与Gitlab 单点登录认证流程

✅ 一、完整 URL

 http://192.168.201.202/maxkey/#/passport/login?redirect_uri=aHR0cDovLzE5Mi4xNjguMjAxLjIwMi9zaWduL2F1dGh6L29hdXRoL3YyMC9hdXRob3JpemU_Y2xpZW50X2lkPTgyMDk5MDM5Mzg4NDYwNjQ2NCZyZWRpcmVjdF91cmk9aHR0cCUzQSUyRiUyRjE5Mi4xNjguMjIuMjAwJTJGdXNlcnMlMkZhdXRoJTJGb2F1dGgyX2dlbmVyaWMlMkZjYWxsYmFjayZyZXNwb25zZV90eXBlPWNvZGUmc3RhdGU9OTc0YTk5ZWI3NWRlNWY4MDhmZmJkOGI2MjY0NDNjNjM3OTM2ZTU4NmQ3Mjc3OTlm

✅ 二、从 URL 看出什么？

这是 MaxKey 登录页面 路径：/maxkey/#/passport/login 后面带了一个参数 redirect_uri=... 这个参数经过 Base64 编码。

我们先解码。

✅ 三、解码后的 redirect_uri

Base64 解码后得到：

 http://192.168.201.202/sign/authz/oauth/v20/authorize?client_id=820990393884606464&redirect_uri=http%3A%2F%2F192.168.22.200%2Fusers%2Fauth%2Foauth2_generic%2Fcallback&response_type=code&state=974a99eb75de5f808ffbd8b626443c637936e586d727799f

✅ 四、解释这一串真正的 OAuth2 逻辑

部分	含义
`http://192.168.201.202/sign/authz/oauth/v20/authorize`	MaxKey OAuth 授权接口（服务端）
`client_id=820990393884606464`	GitLab 在 MaxKey 注册的应用 ID
`redirect_uri=http://192.168.22.200/users/auth/oauth2_generic/callback`	GitLab 等待 MaxKey 回调的地址
`response_type=code`	OAuth2 授权码模式（Authorization Code Flow）
`state=974a99eb75de5f808ffbd8b626443c637936e586d727799f`	防 CSRF 验证参数

✅ 五、整个交互过程

以下是你现在系统中的认证流程：

🧩 Step 1. 用户访问 GitLab

你点击 “用 MaxKey 登录” 按钮。

GitLab 作为 OAuth 客户端 向 MaxKey 发起请求：

 http://192.168.201.202/sign/authz/oauth/v20/authorize?client_id=820990393884606464&redirect_uri=http://192.168.22.200/users/auth/oauth2_generic/callback...

GitLab 告诉 MaxKey：

“我想要一个授权码 (code)，授权成功后，请把我跳回 redirect_uri。”

🧩 Step 2. MaxKey 检查用户是否已登录

如果没登录，就先跳转到：

 http://192.168.201.202/maxkey/#/passport/login

这就是你看到的页面。参数 redirect_uri= 告诉 MaxKey：

“用户登录成功后，请带着授权信息回到我刚才的 /sign/authz/oauth/v20/authorize?... 请求。”

🧩 Step 3. 用户在 MaxKey 登录成功

MaxKey 知道你的身份后，会执行：

生成一个临时授权码 code；
把用户带回 GitLab 的回调地址：

 http://192.168.22.200/users/auth/oauth2_generic/callback?code=xxxxxx&state=xxxxx

🧩 Step 4. GitLab 用 code 换 token

GitLab 发送 POST 请求到：

 http://192.168.201.202/sign/authz/oauth/v20/token

带上：

client_id
client_secret
code

MaxKey 返回 access_token。

🧩 Step 5. GitLab 用 token 获取用户信息

GitLab 访问：

 http://192.168.201.202/sign/api/oauth/v20/me

拿到你的用户名、邮箱等信息，自动登录。

✅ 六、所以总结：

你看到的 URL 表示：

GitLab → MaxKey 登录页 → 登录后回跳授权接口 → 再跳回 GitLab 完成登录

这是 标准的 OAuth2 授权码模式流程，一切行为都在协议设计内。