如何在Antora生成的所有页面中集成OKTA SSO？

方法一：自定义Antora UI模板注入认证代码 #

Antora的页面渲染依赖Handlebars模板，通过修改默认UI可以在所有页面统一注入OKTA逻辑：

• 初始化本地UI目录：执行 antora ui:init 生成自定义UI基础文件
• 编辑 src/layouts/partials/head.hbs，在</head>标签前插入OKTA的加载与初始化脚本：

  <!-- OKTA 认证脚本 -->
  <script src="https://global.oktacdn.com/okta-signin-widget/6.15.0/js/okta-sign-in.min.js" type="text/javascript"></script>
  <link href="https://global.oktacdn.com/okta-signin-widget/6.15.0/css/okta-sign-in.min.css" rel="stylesheet"/>
  <script>
    // 初始化OKTA登录组件
    const oktaSignIn = new OktaSignIn({
      baseUrl: 'https://你的OKTA域名.com',
      clientId: '你的SPA客户端ID',
      redirectUri: 'https://你的文档站点域名/callback',
      authParams: {
        issuer: 'https://你的OKTA域名.com/oauth2/default',
        responseType: ['token', 'id_token'],
        scopes: ['openid', 'email', 'profile']
      }
    });
  
    // 检查用户会话，未登录则渲染登录组件
    oktaSignIn.authClient.session.get()
      .then(session => {
        if (!session) {
          oktaSignIn.renderEl({ el: '#okta-login-container' }, () => {}, err => {
            console.error('登录初始化失败', err);
          });
        }
      });
  </script>
  

• 在页面布局的合适位置（比如src/layouts/partials/header.hbs）添加登录组件容器：

  <div id="okta-login-container"></div>
  

• 构建并应用自定义UI：执行 antora ui:build 生成UI包，然后在Antora的playbook.yml中配置：

  ui:
    dir: ./ui
  

方法二：通过Antora扩展动态注入代码 #

如果不想修改UI模板，可编写轻量扩展在页面生成时自动注入OKTA逻辑：

• 创建本地扩展文件okta-extension.js：

  module.exports = function () {
    return {
      afterDocumentRender({ content, document }) {
        // 仅处理HTML格式的文档
        if (document.out.format !== 'html') return;
        
        // 在body开头插入登录容器
        let modifiedContent = content.replace('<body>', `<body><div id="okta-login"></div>`);
        // 在head末尾插入OKTA脚本
        modifiedContent = modifiedContent.replace('</head>', `
          <script src="https://global.oktacdn.com/okta-signin-widget/6.15.0/js/okta-sign-in.min.js"></script>
          <link href="https://global.oktacdn.com/okta-signin-widget/6.15.0/css/okta-sign-in.min.css" rel="stylesheet"/>
          <script>
            const oktaSignIn = new OktaSignIn({
              baseUrl: 'https://你的OKTA域名.com',
              clientId: '你的SPA客户端ID',
              redirectUri: window.location.origin + '/callback',
              authParams: {
                issuer: 'https://你的OKTA域名.com/oauth2/default',
                responseType: ['token', 'id_token'],
                scopes: ['openid', 'email', 'profile']
              }
            });
  
            oktaSignIn.authClient.session.get().then(session => {
              if (!session) {
                oktaSignIn.renderEl({ el: '#okta-login' }, () => {}, err => console.error(err));
              }
            });
          </script>
        </head>`);
        
        return modifiedContent;
      }
    };
  };
  

• 在playbook.yml中配置启用该扩展：

  extensions:
    - ./okta-extension.js
  

关键注意事项 #

• 确保OKTA后台的SPA应用配置正确：回调地址、注销地址需与文档站点域名完全匹配
• 配置OKTA的CORS规则，允许文档站点域名访问OKTA接口
• 可根据Antora的UI风格，自定义OKTA登录组件的CSS样式

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