Authenticated SaaS with embedded docs

Scenario

Use this workflow when building a SaaS application that requires secure, multi-factor or social authentication via IDaaS, while simultaneously delivering role-based, personalized documentation through GitBook without redirecting users away from your app.

Integration steps

1. Configure IDaaS Social Login & 2FA: In the IDaaS console, enable social providers under Authentication > Social Login and set redirect_uri to https://your-saas.com/callback. Enable 2FA via Security > MFA and select TOTP or SMS.
2. Implement OIDC Flow: Initialize the IDaaS SDK in your frontend: idaas.auth.authorize({ client_id: 'YOUR_CLIENT_ID', scope: 'openid profile email', redirect_uri: 'https://your-saas.com/callback' }).
3. Exchange Code for Tokens: On your backend, call POST https://idaas.aliyuncs.com/oauth2/v1/token with grant_type=authorization_code, code, and client_secret to retrieve id_token and access_token.
4. Extract User Claims: Decode the id_token to extract sub, email, and custom claims like role or tenant_id for permission mapping.
5. Generate GitBook Embed Token: Call GitBook’s auth endpoint POST https://api.gitbook.com/v1/spaces/{spaceId}/embed/tokens with payload { "userId": "sub", "permissions": ["read:docs"], "filters": { "role": "admin" } } to get a short-lived JWT.
6. Initialize GitBook Embed: In your SaaS frontend, load the embed script and pass the token:

``html <script src="https://cdn.gitbook.com/embed.js"></script> <script> GitBookEmbed.init({ spaceId: 'YOUR_SPACE_ID', auth: { token: 'GITBOOK_JWT' }, theme: 'light', filters: { userRole: 'admin' } }); </script> ``

7. Handle Session Refresh: Implement silent token refresh via IDaaS POST /oauth2/v1/token with grant_type=refresh_token before the GitBook embed token expires.

Architecture

The SaaS frontend initiates authentication via IDaaS using OIDC. IDaaS handles social login, 2FA challenges, and issues an id_token. Your backend validates the token, extracts user identity/roles, and requests a scoped JWT from GitBook’s embed API. The frontend renders the GitBook iframe/script, passing the JWT. GitBook validates the token, applies role-based content filters, and serves personalized documentation directly within the SaaS UI.

Prerequisites

• Active IDaaS tenant with configured OAuth2/OIDC application
• GitBook Enterprise/Team plan with API access and Embed feature enabled
• Backend service capable of handling OIDC token exchange and JWT generation
• CORS and redirect URIs whitelisted in both IDaaS and GitBook settings

Common pitfalls

• Token mismatch: Passing the raw IDaaS access_token directly to GitBook instead of exchanging it for a GitBook-specific embed JWT, causing 401 errors.
• CORS/iframe blocking: Missing X-Frame-Options or CSP headers on the SaaS domain, preventing GitBook’s embed from rendering.
• 2FA callback interruption: Failing to preserve the original state parameter during IDaaS MFA redirects, breaking the OIDC flow and losing session context.
• Stale permissions: Not refreshing the GitBook embed token when user roles change in IDaaS, resulting in outdated documentation visibility.

Typical questions

• embed docs in authenticated app
• authenticated GitBook embed
• SaaS documentation with user login
• 在SaaS应用中嵌入认证文档
• IDaaS登录后嵌入GitBook
• 用户权限控制文档嵌入

Q: How do I embed documentation in an authenticated SaaS application? A: You can embed documentation in an authenticated SaaS application by combining IDaaS for user authentication with GitBook Embed to display personalized content. This configuration allows you to set up authentication methods like social login or 2FA while ensuring the embedded documentation reflects each user's specific identity and permissions.