如何为Go搭建的MKDocs静态站点添加Azure SSO认证？

核心思路是利用**中间件（Middleware）**实现全局认证拦截，不用逐个配置路由。下面用新手友好的Gin框架给出可落地的解决方案，避免复杂配置和报错：

前置准备 #

1. 在Azure AD中注册应用，获取以下参数：
   • 客户端ID（Client ID）
   • 客户端密钥（Client Secret）
   • 租户ID（Tenant ID）
   • 回调URL（比如http://localhost:8080/callback，需在Azure应用中配置一致）
2. 确保MKDocs已生成静态文件，存放在本地./site目录（可自行修改路径）

步骤1：安装依赖 #

go get github.com/gin-gonic/gin
go get golang.org/x/oauth2
go get golang.org/x/oauth2/microsoft
go get github.com/gin-contrib/sessions
go get github.com/gin-contrib/sessions/cookie

步骤2：完整代码实现 #

package main

import (
	"context"
	"net/http"

	"github.com/gin-contrib/sessions"
	"github.com/gin-contrib/sessions/cookie"
	"github.com/gin-gonic/gin"
	"golang.org/x/oauth2"
	"golang.org/x/oauth2/microsoft"
)

// 替换成你的Azure AD配置参数
var oauthConfig = &oauth2.Config{
	ClientID:     "你的客户端ID",
	ClientSecret: "你的客户端密钥",
	RedirectURL:  "http://localhost:8080/callback",
	Scopes: []string{
		"user.read", // 获取用户基础信息的权限
	},
	Endpoint: microsoft.AzureADEndpoint("你的租户ID"),
}

// 全局认证中间件：拦截所有静态页面请求，未认证则跳转到Azure登录
func authMiddleware() gin.HandlerFunc {
	return func(c *gin.Context) {
		session := sessions.Default(c)
		// 检查session中是否存在已认证的用户标记
		if session.Get("authenticated") == nil {
			// 生成Azure登录授权URL，state用于防CSRF（生产环境建议用随机值）
			authURL := oauthConfig.AuthCodeURL("static_csrf_state")
			c.Redirect(http.StatusTemporaryRedirect, authURL)
			c.Abort()
			return
		}
		c.Next()
	}
}

func main() {
	r := gin.Default()

	// 配置Session存储（生产环境建议用Redis替代cookie，避免敏感信息泄露）
	store := cookie.NewStore([]byte("your_secure_session_secret")) // 替换成随机强密钥
	r.Use(sessions.Sessions("mkdocs_auth_session", store))

	// Azure登录回调路由：处理授权码，完成认证
	r.GET("/callback", func(c *gin.Context) {
		code := c.Query("code")
		// 用授权码交换Access Token
		token, err := oauthConfig.Exchange(context.Background(), code)
		if err != nil {
			c.String(http.StatusBadRequest, "登录失败：%v", err)
			return
		}

		// （可选）调用Microsoft Graph API获取用户详细信息，比如邮箱、姓名
		// client := oauthConfig.Client(context.Background(), token)
		// var user struct{ DisplayName string; Mail string }
		// client.Get("https://graph.microsoft.com/v1.0/me")
		// 解析后可将用户信息存入Session

		// 标记用户已认证
		session := sessions.Default(c)
		session.Set("authenticated", true)
		session.Save()

		// 认证成功后跳转到MKDocs首页
		c.Redirect(http.StatusTemporaryRedirect, "/")
	})

	// 托管所有静态文件，并应用全局认证中间件
	r.GET("/*any", authMiddleware(), func(c *gin.Context) {
		// 指向MKDocs生成的静态文件目录
		c.FileFromFS(c.Request.URL.Path, http.Dir("./site"))
	})

	// 启动服务
	r.Run(":8080")
}

关键说明 #

1. 全局拦截：通过authMiddleware拦截所有静态页面请求（/*any路由匹配所有路径），未认证用户自动跳转Azure登录
2. Session管理：用cookie存储认证状态（生产环境务必换成Redis等安全存储），确保用户登录状态在会话中保持
3. 回调处理：/callback路由负责与Azure交互完成授权码交换，标记用户认证状态后跳回首页

常见问题排查 #

• 如果之前用GoFiber报错，大概率是依赖版本冲突或Session配置错误，Gin的生态更稳定，新手调试成本更低
• Azure回调URL必须与代码中RedirectURL完全一致，否则会触发认证失败
• Session密钥要使用随机生成的强字符串，避免被破解

内容的提问来源于stack exchange，提问作者OdiumPura