@mehdad67/apitogo 0.1.24

package/docs/configuration/authentication-azure-ad.md

@@ -0,0 +1,238 @@
+---
+title: Azure AD Setup
+sidebar_label: Azure AD
+description:
+  Learn how to set up Azure Active Directory (Microsoft Entra ID) authentication for APIToGo,
+  enabling secure single sign-on for your organization.
+---
+
+Azure Active Directory (now Microsoft Entra ID) provides enterprise-grade authentication and
+authorization for organizations using Microsoft's cloud identity platform. This guide shows you how
+to integrate Azure AD with your APIToGo documentation site.
+
+## Prerequisites
+
+- An Azure subscription with Azure Active Directory
+- Administrative access to register applications in Azure AD
+- Your Azure AD tenant ID
+
+## Setup Steps
+
+<Stepper>
+
+1. **Register an Application in Azure AD**
+
+   In the [Azure Portal](https://portal.azure.com):
+   - Navigate to **Azure Active Directory** → **App registrations**
+   - Click **New registration**
+   - Configure your application:
+     - **Name**: Enter a descriptive name (e.g., "APIToGo Documentation")
+     - **Supported account types**: Choose based on your needs:
+       - Single tenant (your organization only)
+       - Multitenant (any Azure AD directory)
+       - Multitenant + personal Microsoft accounts
+     - **Redirect URI**:
+       - Platform: **Single-page application (SPA)**
+       - URI: `https://your-site.com/oauth/callback`
+   - Click **Register**
+
+2. **Configure Authentication Settings**
+
+   In your newly registered application:
+   - Go to **Authentication** in the left menu
+   - Under **Single-page application**, add redirect URIs:
+     - Production: `https://your-site.com/oauth/callback`
+     - Preview (wildcard): `https://*.your-domain.com/oauth/callback`
+     - Local Development: `http://localhost:3000/oauth/callback`
+   - Under **Implicit grant and hybrid flows**:
+     - Enable **ID tokens**
+     - Enable **Access tokens**
+   - Configure **Supported account types** if needed
+   - Save your changes
+
+3. **Configure API Permissions (Optional)**
+
+   If you need specific permissions:
+   - Go to **API permissions**
+   - Click **Add a permission**
+   - Select **Microsoft Graph** → **Delegated permissions**
+   - Add permissions like `User.Read`, `email`, `profile`, `openid`
+   - Grant admin consent if required by your organization
+
+4. **Configure APIToGo**
+
+   Get your application details from the Azure Portal:
+   - Go to **Overview** page of your app registration
+   - Copy the **Application (client) ID**
+   - Copy the **Directory (tenant) ID**
+
+   Add the configuration to your [APIToGo configuration file](./overview.md):
+
+   ```typescript
+   // apitogo.config.ts
+   export default {
+     // ... other configuration
+     authentication: {
+       type: "openid",
+       clientId: "<your-application-client-id>",
+       issuer: "https://login.microsoftonline.com/<your-tenant-id>/v2.0",
+       scopes: ["openid", "profile", "email"], // Optional: customize scopes
+     },
+     // ... other configuration
+   };
+   ```
+
+5. **Install Azure AD Dependencies**
+
+   Add `@azure/msal-browser` to your project dependencies:
+
+   ```bash
+   npm install @azure/msal-browser
+   ```
+
+</Stepper>
+
+## Configuration Options
+
+### Single Tenant vs Multitenant
+
+For single tenant (organization-only access):
+
+```typescript
+authentication: {
+  type: "openid",
+  clientId: "<your-application-client-id>",
+  issuer: "https://login.microsoftonline.com/<your-tenant-id>/v2.0",
+  scopes: ["openid", "profile", "email"],
+}
+```
+
+For multitenant (any Azure AD organization):
+
+```typescript
+authentication: {
+  type: "openid",
+  clientId: "<your-application-client-id>",
+  issuer: "https://login.microsoftonline.com/common/v2.0",
+  scopes: ["openid", "profile", "email"],
+}
+```
+
+### Custom Scopes and Permissions
+
+Request additional Microsoft Graph API scopes:
+
+```typescript
+authentication: {
+  type: "openid",
+  clientId: "<your-application-client-id>",
+  issuer: "https://login.microsoftonline.com/<your-tenant-id>/v2.0",
+  scopes: [
+    "openid",
+    "profile",
+    "email",
+    "User.Read",
+    "GroupMember.Read.All" // For group-based access control
+  ],
+}
+```
+
+### Protected Routes
+
+Protect specific documentation routes using the `protectedRoutes` configuration:
+
+```typescript
+{
+  // ... other configuration
+  authentication: {
+    type: "openid",
+    // ... Azure AD config
+  },
+  protectedRoutes: [
+    "/api/*",        // Protect all API documentation
+    "/internal/*",   // Protect internal documentation
+    "/admin/*"       // Protect admin sections
+  ],
+}
+```
+
+## Advanced Configuration
+
+### Conditional Access Policies
+
+Azure AD supports conditional access policies that can:
+
+- Require multi-factor authentication
+- Restrict access by location
+- Enforce device compliance
+- Control session lifetime
+
+Configure these in Azure AD Portal under **Security** → **Conditional Access**.
+
+### App Roles and Groups
+
+To implement role-based access control:
+
+1. In your app registration, go to **App roles**
+2. Create custom roles (e.g., "Documentation.Read", "Documentation.Admin")
+3. Assign roles to users or groups in **Enterprise applications**
+4. Access role claims in your application
+
+### B2B Guest Access
+
+To allow external partners access:
+
+1. Enable B2B collaboration in Azure AD
+2. Configure external collaboration settings
+3. Invite guest users to your directory
+4. Grant appropriate permissions to your application
+
+## User Data
+
+Azure AD provides rich user profile data through OpenID Connect:
+
+- `name` - User's display name
+- `email` - User's email address
+- `picture` - Profile picture URL (when available)
+- `email_verified` - Email verification status
+- `preferred_username` - User's UPN (User Principal Name)
+- Additional claims based on your API permissions
+
+## Troubleshooting
+
+### Common Issues
+
+1. **Invalid Client Error**: Ensure the client ID is correct and the application is properly
+   registered.
+
+2. **Redirect URI Mismatch**: The redirect URI must exactly match one configured in Azure AD,
+   including protocol and path.
+
+3. **Tenant Access Issues**: For single-tenant apps, ensure users are from the correct tenant. For
+   multi-tenant, verify the issuer URL uses "common" or "organizations".
+
+4. **Missing User Information**: Check that required API permissions are granted and admin consent
+   is provided if needed.
+
+5. **Token Validation Errors**: Ensure your issuer URL is correct and includes the `/v2.0` endpoint
+   for the Microsoft identity platform.
+
+6. **Authentication Not Working**: Make sure you have installed `@azure/msal-browser` to your
+   project.
+
+## Security Best Practices
+
+- Use single-tenant configuration unless multi-tenant is specifically required
+- Implement conditional access policies for sensitive documentation
+- Regularly review and audit app permissions
+- Monitor sign-in logs in Azure AD for suspicious activity
+- Use app roles for fine-grained access control
+
+## Next Steps
+
+- Explore
+  [Microsoft identity platform documentation](https://docs.microsoft.com/en-us/azure/active-directory/develop/)
+- Learn about [protecting routes](./authentication.md#protected-routes) in your documentation
+- Implement
+  [app roles](https://docs.microsoft.com/en-us/azure/active-directory/develop/howto-add-app-roles-in-azure-ad-apps)
+  for advanced authorization

package/docs/configuration/authentication-clerk.md

@@ -0,0 +1,110 @@
+---
+title: Clerk Setup
+sidebar_label: Clerk
+description:
+  Learn how to set up Clerk authentication for APIToGo, providing a seamless authentication
+  experience with modern UI components and extensive customization options.
+---
+
+Clerk is a modern authentication platform that provides beautiful, customizable UI components and a
+developer-friendly experience. This guide walks you through integrating Clerk authentication with
+your APIToGo documentation site.
+
+## Prerequisites
+
+If you don't have a Clerk account, you can sign up for a [free Clerk account](https://clerk.com/)
+that provides 10,000 monthly active users.
+
+## Setup Steps
+
+<Stepper>
+
+1. **Create a Clerk Application**
+
+   In the [Clerk Dashboard](https://dashboard.clerk.com/):
+   - Click **Create Application**
+   - Enter your application name
+   - Select your preferred authentication methods (email, social providers, etc.)
+   - Click **Create Application**
+
+2. **Create a Clerk JWT Template** You need to create a JWT Template so your JWTs include name,
+   email and email_verified information.
+
+- Navigate to **JWT templates** in the [Clerk Dashboard](https://dashboard.clerk.com/)
+- Create a new template by clicking **Add new template**
+- Pick a name for the template
+- Add the following claims
+  ```json
+  {
+    "name": "{{user.full_name}}",
+    "email": "{{user.primary_email_address}}",
+    "email_verified": "{{user.email_verified}}"
+  }
+  ```
+- Save
+
+3. **Configure APIToGo**
+
+   Get your publishable key from the Clerk dashboard:
+   - Navigate to **API Keys** in your Clerk dashboard
+   - Copy the **Publishable key**
+
+   Use the JWT template name defined in the previous section
+
+   Add the Clerk configuration to your [APIToGo configuration file](./overview.md):
+
+   ```typescript
+   // apitogo.config.ts
+   export default {
+     // ... other configuration
+     authentication: {
+       type: "clerk",
+       clerkPubKey: "<your-clerk-publishable-key>",
+       jwtTemplateName: "<your-clerk-jwt-template-name>",
+     },
+     // ... other configuration
+   };
+   ```
+
+4. **Configure Redirect URLs (Optional)**
+
+   If you need custom redirect behavior, configure the allowed redirect URLs in Clerk:
+   - Go to **Paths** in your Clerk dashboard
+   - Add your production, preview, and local development URLs to the allowed redirect URLs
+   - Common patterns:
+     - Production: `https://your-site.com/oauth/callback`
+     - Preview (wildcard): `https://*.your-domain.com/oauth/callback`
+     - Local Development: `http://localhost:3000/oauth/callback`
+
+5. **Install Clerk Dependencies**
+
+   Add `@clerk/clerk-js` to your project dependencies:
+
+   ```bash
+   npm install @clerk/clerk-js
+   ```
+
+   </Stepper>
+
+## Troubleshooting
+
+### Common Issues
+
+1. **Invalid Publishable Key**: Ensure you're using the publishable key (starts with `pk_`) and not
+   the secret key.
+
+2. **Authentication Not Working**: Verify that your Clerk application is active and not in
+   development mode when deploying to production.
+
+3. **Redirect Issues**: Check that your domain is added to the allowed redirect URLs in Clerk if
+   using custom redirects.
+
+4. **ReferenceError: can't access lexical declaration 'xxx' before initialization**: Make sure you
+   have installed Clerk to your project.
+
+## Next Steps
+
+- Explore [Clerk's documentation](https://clerk.com/docs) for advanced features
+- Learn about [protecting routes](./authentication.md#protected-routes) in your documentation
+- Configure [user roles and permissions](https://clerk.com/docs/organizations/roles-permissions) in
+  Clerk

package/docs/configuration/authentication-firebase.md

@@ -0,0 +1,62 @@
+---
+title: Firebase Setup
+sidebar_label: Firebase
+description:
+  Learn how to set up Firebase Authentication for APIToGo, leveraging Google's secure authentication
+  infrastructure with multiple sign-in providers.
+---
+
+Firebase Authentication provides a comprehensive identity solution from Google, supporting
+email/password authentication and federated identity providers like Google, Facebook, Twitter, and
+more. This guide shows you how to integrate Firebase Authentication with your APIToGo documentation
+site.
+
+## Prerequisites
+
+- A Google account to access Firebase Console
+- A Firebase project (free tier available)
+- Basic knowledge of Firebase configuration
+
+## Setup Firebase
+
+1. Go to the [Firebase Console](https://console.firebase.google.com/):
+2. Click **Create a project** (or select an existing project)
+3. Make sure authentication is enabled. Choose your preferred authentication providers.
+4. Configure Authorized Domains, add your domains where the authentication will be used.
+5. **Get Your Firebase Configuration**
+   - Go to **Project settings**
+   - Scroll to **Your apps** section
+   - Click **Add app** → **Web** if you haven't already
+   - Register your app with a nickname
+   - Copy the Firebase configuration object
+
+## Configure APIToGo
+
+Add the Firebase configuration to your [APIToGo configuration file](./overview.md):
+
+```typescript title="apitogo.config.ts"
+export default {
+  authentication: {
+    type: "firebase",
+    // Replace these with your Firebase project configuration
+    // Get these values from Firebase Console > Project Settings
+    apiKey: "<insert your API key here>",
+    authDomain: "your-domain.firebaseapp.com",
+    projectId: "your-project-id",
+    appId: "1:296819355813:web:91d29f11cac6f073595d4c",
+    // Optional fields
+    storageBucket: "your-project.firebasestorage.app",
+    messagingSenderId: "296819355813",
+    measurementId: "G-12W6TTNR75",
+    // Optional: specify which providers to show in the sign-in UI
+    // Available providers: "google", "github", "facebook", "twitter",
+    // "microsoft", "apple", "yahoo", "password", "phone"
+    // If not specified, all enabled providers in Firebase will be available
+    providers: ["google", "github", "password"],
+    // Optional: configure redirect URLs after authentication
+    redirectToAfterSignIn: "/docs",
+    redirectToAfterSignUp: "/getting-started",
+    redirectToAfterSignOut: "/",
+  },
+};
+```

package/docs/configuration/authentication-pingfederate.md

@@ -0,0 +1,136 @@
+---
+title: PingFederate Setup
+sidebar_label: PingFederate
+description:
+  Learn how to set up PingFederate authentication for APIToGo using OpenID Connect for
+  enterprise-grade single sign-on.
+---
+
+PingFederate is an enterprise federation server that enables secure single sign-on (SSO) and API
+security for organizations. This guide walks you through integrating PingFederate with APIToGo using
+OpenID Connect.
+
+## Prerequisites
+
+- Access to a PingFederate server (version 9.0 or later recommended)
+- Administrative access to configure OAuth clients in PingFederate
+- Your PingFederate server's base URL
+
+## Setup Steps
+
+<Stepper>
+
+1. **Create an OAuth Client in PingFederate**
+
+   In the PingFederate administrative console:
+   - Navigate to **Applications** → **OAuth** → **Clients**
+   - Click **Add Client**
+   - Configure the client:
+     - **Client ID**: Choose a unique identifier (e.g., `apitogo-docs`)
+     - **Client Authentication**: Select **None (Public Client)**
+     - **Grant Types**: Enable **Authorization Code** and **Refresh Token**
+     - **Redirect URIs**:
+       - Production: `https://your-site.com/oauth/callback`
+       - Preview (wildcard): `https://*.your-domain.com/oauth/callback`
+       - Local Development: `http://localhost:3000/oauth/callback`
+
+2. **Configure OpenID Connect Settings**
+
+   Still in the OAuth client configuration:
+   - Enable **OpenID Connect**
+   - Configure scopes:
+     - Enable `openid`, `profile`, and `email` (minimum required)
+     - Add any custom scopes your organization requires
+   - **ID Token Signing Algorithm**: RS256 (recommended)
+   - **Access Token Manager**: Select or create an appropriate token manager
+   - Save the configuration
+
+3. **Configure APIToGo**
+
+   Add the PingFederate configuration to your [APIToGo configuration file](./overview.md):
+
+   ```typescript
+   // apitogo.config.ts
+   export default {
+     // ... other configuration
+     authentication: {
+       type: "openid",
+       clientId: "apitogo-docs", // Your OAuth client ID
+       issuer: "https://pingfederate.your-domain.com", // Your PingFederate base URL
+       scopes: ["openid", "profile", "email"], // Optional: add custom scopes
+     },
+     // ... other configuration
+   };
+   ```
+
+</Stepper>
+
+## Configuration Options
+
+### Custom Scopes
+
+If your organization uses custom scopes for authorization, include them in the configuration:
+
+```typescript
+authentication: {
+  type: "openid",
+  clientId: "apitogo-docs",
+  issuer: "https://pingfederate.your-domain.com",
+  scopes: ["openid", "profile", "email", "groups", "roles", "api:read"],
+}
+```
+
+## Advanced Configuration
+
+### CORS Configuration
+
+Configure CORS in PingFederate for your documentation site:
+
+1. Navigate to **System** → **Server Configuration** → **Cross-Origin Resource Sharing**
+2. Add your site's domain to the allowed origins:
+   - `https://your-site.com`
+   - `http://localhost:3000` (for local development)
+
+### Attribute Mapping
+
+PingFederate can map user attributes from various sources. Ensure these standard claims are mapped:
+
+1. Go to **OAuth** → **Access Token Management** → **Your Token Manager**
+2. Configure attribute mappings:
+   - `sub` → User's unique identifier
+   - `name` → User's display name
+   - `email` → User's email address
+   - `picture` → User's profile picture URL (if available)
+
+## Troubleshooting
+
+### Common Issues
+
+1. **Discovery Endpoint Not Found**: Ensure your issuer URL is correct and accessible. The OpenID
+   Connect discovery endpoint should be available at
+   `https://your-pingfederate-server/.well-known/openid-configuration`.
+
+2. **Invalid Client Configuration**: Verify that the client ID matches exactly and that the redirect
+   URIs are properly configured in PingFederate.
+
+3. **CORS Errors**: Check that your site's domain is added to PingFederate's CORS configuration.
+
+4. **Missing User Attributes**: Ensure attribute mappings are configured in your Access Token
+   Manager.
+
+5. **Token Validation Errors**: Verify that your PingFederate server's certificates are valid and
+   that clock synchronization is accurate.
+
+## Security Considerations
+
+- Always use HTTPS for production deployments
+- Regularly rotate signing certificates in PingFederate
+- Configure appropriate session timeouts
+- Review and audit OAuth client configurations periodically
+
+## Next Steps
+
+- Review [PingFederate documentation](https://docs.pingidentity.com/pingfederate/) for advanced
+  features
+- Learn about [protecting routes](./authentication.md#protected-routes) in your documentation
+- Configure group-based access control using PingFederate claims