穆音muvocal auth 登录系统接入文档

概述

本文档旨在帮助第三方系统接入muvocal Auth登录系统,实现统一身份认证。接入后,用户只需在 SSO 系统登录一次,即可访问所有集成的应用系统。


系统架构

用户浏览器
    │
    ├──> 第三方系统 (如高考志愿系统)
    │       │
    │       └──> SSO 登录页面
    │
    └──> SSO 回调处理
            │
            └──> SSO 令牌验证

接入步骤

1. 注册客户端应用

联系 SSO 管理员注册您的应用,提供以下信息:

  • 应用名称:您的系统名称
  • 回调地址:接收 SSO token 的 URL(如 https://yourdomain.com/sso_callback

您将获得:

  • client_id – 客户端唯一标识符
  • client_secret – 客户端密钥(用于安全验证)

2. 配置 SSO 参数

在您的应用中添加以下配置:

3. 实现登录路由

在您的应用中添加登录路由:

4. 实现回调处理

添加回调路由处理 SSO 返回的 token:

5. 添加登录检查

保护需要登录的路由:

6. 实现退出功能

添加退出路由:


认证流程说明

登录流程

  1. 用户访问您的系统
  2. 点击登录按钮 → 重定向到 SSO 登录页面
  3. 用户在 SSO 系统输入凭据登录
  4. SSO 验证凭据,生成 JWT token
  5. SSO 重定向回您的回调地址(附带 token)
  6. 您的系统验证 token 并建立本地会话
  7. 用户登录成功,访问您的系统

登出流程

  1. 用户点击退出按钮
  2. 您的系统清除本地会话
  3. (可选)重定向到 SSO 全局登出页面

安全配置要求

1. 会话密钥

在您的 Flask 应用中设置强密钥:

2. HTTPS 要求

  • 生产环境必须启用 HTTPS
  • 所有回调 URL 必须使用 HTTPS
  • 设置安全 Cookie:
  app.config.update(
      SESSION_COOKIE_SECURE=True,
      SESSION_COOKIE_HTTPONLY=True,
      SESSION_COOKIE_SAMESITE='Lax'
  )

3. 令牌验证

  • 验证 token 有效期(默认 30 分钟)
  • 检查 token 签名
  • 处理可能的错误情况:
  • Token 过期
  • 无效签名
  • 用户不存在

用户信息结构

SSO 系统返回的用户信息包含以下字段:


错误处理

常见错误及解决方案

错误代码描述解决方案
401无效 token重新登录
400缺少参数检查回调 URL
500服务器错误检查日志并重试
403访问被拒绝检查客户端权限

日志记录建议

import logging

logging.basicConfig(
    level=logging.INFO,
    format='%(asctime)s - %(name)s - %(levelname)s - %(message)s',
    handlers=[
        logging.FileHandler('app.log'),
        logging.StreamHandler()
    ]
)

最佳实践

  1. 会话管理
  • 设置会话超时(建议 8 小时)
   app.config['PERMANENT_SESSION_LIFETIME'] = timedelta(hours=8)
  1. 错误页面
  • 自定义 401、404、500 错误页面
   @app.errorhandler(401)
   def unauthorized(e):
       return render_template('401.html'), 401
  1. 性能优化
  • 缓存用户信息(避免每次请求都验证 token)
  • 使用连接池管理 HTTP 请求
  1. 用户界面
  • 添加登录状态显示
  • 提供清晰的登录/退出入口
  • 显示用户名和退出选项

示例代码

完整接入示例


技术支持

如需帮助,请联系:

版本历史

版本日期描述
1.02023-10-15初始版本
1.12023-11-01增加错误处理指南
1.22025-5-20更新安全配置要求

通过遵循本文档,您的系统可以快速、安全地接入 SSO 单点登录系统,为用户提供无缝的登录体验。


已发布

分类

, ,

来自

标签:

评论

发表回复

您的邮箱地址不会被公开。 必填项已用 * 标注