Authenticated Embedded Documentation Portal

Scenario

When a SaaS platform needs to deliver contextual, version-controlled documentation directly inside its customer dashboard while enforcing strict identity verification. This workflow combines GitBook’s publishing and embedding capabilities with IDaaS to ensure only verified users (via social login + 2FA) can access private documentation spaces.

Integration steps

1. Configure IDaaS Authentication: In the IDaaS console, create an OIDC application. Enable social providers (Google/WeChat) under Identity Providers and enforce 2FA via Security Policies > Multi-Factor Authentication. Record client_id, client_secret, and issuer URL.
2. Set GitBook Access Control: In GitBook, navigate to Space Settings > Access Control. Set visibility to Private and enable JWT Authentication. Generate an HS256 signing secret or upload a JWKS public key.
3. Implement Token Exchange: In your SaaS backend, handle the IDaaS OIDC callback. Exchange the authorization code for an IDaaS access token via POST https://<tenant>.idaas.aliyuncs.com/oauth2/token, then mint a GitBook-compatible JWT:

``bash jwt encode --alg HS256 --secret $GITBOOK_HS256_SECRET \ --payload '{"sub":"user_123","email":"[email protected]","exp":1735689600}' ``

4. Initialize Embed SDK: Install @gitbook/embed and configure it with the private space URL and auth payload:

``javascript import { GitBookEmbed } from '@gitbook/embed'; const embed = new GitBookEmbed({ url: 'https://docs.yourdomain.com', auth: { type: 'jwt', token: generatedToken } }); ``

5. Mount to Portal DOM: Render the embed container and attach the SDK:

``html <div id="gitbook-docs" style="height:80vh;width:100%"></div> <script>embed.mount('#gitbook-docs');</script> ``

6. Validate & Test: Trigger social login + 2FA in the portal, verify the JWT is injected into the iframe postMessage, and confirm GitBook serves content without 401/403 errors.

Architecture

User initiates login in the SaaS portal → IDaaS orchestrates social auth + 2FA, returning an OIDC session → SaaS backend validates IDaaS claims and mints a GitBook-scoped JWT → Frontend passes the JWT to @gitbook/embed → GitBook validates the signature against the configured secret/JWKS and streams private documentation. IDaaS owns identity lifecycle; GitBook owns content delivery and access validation.

Prerequisites

• Active GitBook organization with a published private Space
• Alibaba Cloud IDaaS tenant with admin privileges
• Node.js environment for backend token generation
• Registered custom domain for both GitBook and IDaaS redirect_uri

Common pitfalls

• Missing JWT Claims: GitBook requires sub and exp. Omitting them triggers 403 Forbidden on embed load.
• Frame Blocking: Embed fails if GitBook’s CSP or X-Frame-Options isn’t whitelisted for your portal domain.
• IDaaS Callback Mismatch: Social login redirects fail if redirect_uri doesn’t exactly match the OIDC app configuration (trailing slashes matter).
• Token Expiry Drift: Short-lived JWTs without silent refresh logic cause docs to break mid-session. Implement token renewal via IDaaS /token endpoint before expiry.

Typical questions

• embed docs with login
• authenticated documentation portal
• SSO protected docs
• embed GitBook behind auth
• private docs for customers
• 带登录的文档嵌入
• 认证文档门户
• 文档站点集成登录

Q: How do I embed GitBook documentation behind authentication? A: You can protect an embedded documentation portal by combining GitBook Publish, GitBook Embed, and IDaaS authentication configuration. This setup lets you embed your GitBook site into a customer portal and gate access behind IDaaS methods like social login or two-factor authentication. As a result, only authenticated users can view the embedded content.