SSO Configuration

Forjinn supports enterprise Single Sign-On (SSO), allowing your organization to authenticate users through existing identity providers such as Okta, Microsoft Azure AD, Google Workspace, and other SAML or OIDC-compatible services.

Accessing SSO Configuration

1. Navigate to Admin or Settings from the left-hand sidebar.
2. Click on SSO Config to open the SSO settings page.

Supported Protocols and Providers

Forjinn supports the following authentication protocols:

• SAML 2.0: Works with Okta, OneLogin, ADFS, PingIdentity, and other SAML-based providers.
• OIDC (OpenID Connect): Works with Google Workspace, Microsoft Azure AD, Auth0, Okta, and other OIDC-compatible providers.

Configuring SSO

Step 1: Add an Identity Provider

1. On the SSO Config page, click Add Provider.
2. Select the protocol type (SAML or OIDC).
3. Fill in the provider details:

For OIDC:

• Provider Name: Display name for the login button (e.g., "Google Workspace", "Azure AD").
• Client ID: The application client ID from your identity provider.
• Client Secret: The application client secret.
• Issuer URL: The OIDC discovery/issuer endpoint (e.g., https://accounts.google.com).
• Scopes: Space-separated OAuth scopes (typically openid email profile).

For SAML:

• Provider Name: Display name for the login button.
• Identity Provider Metadata URL: The XML metadata endpoint from your IdP.
• Entity ID: The unique identifier for your IdP.
• ACS URL: The Assertion Consumer Service endpoint (auto-generated by Forjinn; register this in your IdP).
• Entity ID (SP): The Service Provider entity ID (auto-generated by Forjinn).

Step 2: Configure Your Identity Provider

1. In your IdP's admin console, register a new application.
2. Enter the Forjinn callback URL, ACS URL, and SP Entity ID as provided in the SSO Config page.
3. Download or copy the metadata XML or OIDC discovery endpoint details.
4. Map user attributes (email, name, groups) to the appropriate claims in the SAML assertion or OIDC token.

Step 3: Finalize and Test

1. Save the provider configuration in Forjinn.
2. Open the Forjinn login page.
3. You should see the SSO provider button alongside standard login options.
4. Click the SSO button and verify that authentication works and the user is redirected into Forjinn.

Enforcing SSO

By default, SSO is an additional login option alongside standard email/password authentication. Organization administrators can enforce SSO as the only login method:

1. On the SSO Config page, locate the enforcement setting.
2. Toggle Enforce SSO or Disable standard login.
3. All users must then authenticate through the configured identity provider.

Warning: Before enforcing SSO, ensure at least one admin account can successfully authenticate through the identity provider to avoid locking out all access.

Role Mapping

Forjinn supports mapping identity provider groups or claims to platform roles:

• Define rules that map IdP group names (e.g., forjinn-admins, forjinn-editors) to Forjinn roles (Admin, Editor, Viewer).
• Role mapping is applied automatically during SSO login.
• Users not matching any mapping rule receive the default role configured in the SSO settings.

Troubleshooting

• "Invalid SAML response" or "Authentication failed": Verify that the IdP's ACS URL matches the Forjinn endpoint exactly. Check that required claims (email, name) are included in the SAML assertion.
• "Redirect URI mismatch" (OIDC): Ensure the Forjinn callback URL is registered in the OIDC application settings in your IdP.
• Users not getting correct roles: Review the role mapping rules. Confirm that the IdP sends group or role claims in the expected format.
• SSO button not appearing on login page: Verify the provider is saved and enabled in the SSO Config page. Clear browser cache if needed.
• Locked out after enforcing SSO: Use the backup admin recovery process or contact Forjinn support to restore access.

Best Practices

• Test before enforcing: Always validate the SSO flow with multiple user accounts before disabling standard email/password login.
• Maintain backup access: Keep at least one local admin account as a recovery mechanism.
• Rotate secrets: Periodically update the OIDC client secret and reconfigure both the IdP and Forjinn.
• Monitor login activity: Use the Login Activity page to review SSO authentications for anomalies.