Enterprise plans include single sign-on (SSO) integration, allowing your team to authenticate using your existing identity provider (IdP). AI SEO Agents supports both SAML 2.0 and OpenID Connect (OIDC) federation via AWS Cognito User Pool.
Supported Identity Providers
| Provider | Protocol | Tested |
|---|---|---|
| Okta | SAML 2.0 / OIDC | Yes |
| Azure AD (Entra ID) | SAML 2.0 / OIDC | Yes |
| Google Workspace | OIDC | Yes |
| OneLogin | SAML 2.0 | Yes |
| Auth0 | OIDC | Yes |
| PingFederate | SAML 2.0 | Yes |
| Custom SAML/OIDC | SAML 2.0 / OIDC | Manual setup |
SAML 2.0 Setup
Create a SAML App in Your IdP
In your identity provider (e.g., Okta, Azure AD), create a new SAML application. Use the following values:
Configure SAML Parameters
ACS URL: https://auth.aiagentssee.com/saml2/idpresponse
Entity ID: urn:amazon:cognito:sp:eu-north-1_QF6r7kySt
Name ID format: Email address
Send Us Your Metadata
Export the SAML metadata XML from your IdP and send it to our team via the contact page. We'll configure the federation on the Cognito side within 1 business day.
Test and Roll Out
We'll provide a test login URL. Verify that SSO login works for a test user before enabling it for your entire organization.
OIDC Setup
Register a Client in Your IdP
Create an OIDC client/application in your identity provider.
Provide Configuration
Send us: Issuer URL, Client ID, and Client Secret. We support the authorization code flow with PKCE.
Configure Redirect URIs
Add https://auth.aiagentssee.com/oauth2/idpresponse as an allowed redirect URI in your IdP.
Attribute Mapping
| IdP Attribute | Cognito Attribute | Required |
|---|---|---|
| Yes | ||
| given_name | given_name | No |
| family_name | family_name | No |
| groups | custom:groups | No (used for role mapping) |
When SSO is enabled, users are automatically provisioned on first login. No manual account creation is needed. Users are deprovisioned when removed from the IdP group.
Custom Domain
Enterprise customers can configure a custom authentication domain (e.g., login.yourdomain.com) to provide a fully branded login experience. Contact our team to set up a custom domain with your SSL certificate.
User Provisioning and Deprovisioning
SSO integration includes automatic user lifecycle management that eliminates the need for manual account administration. When an employee authenticates via your identity provider for the first time, an account is automatically created in AI SEO Agents with the appropriate role and permissions. When the employee is removed from your IdP or their group assignment changes, their access is updated accordingly.
- Just-in-time provisioning: New users are created automatically on first SSO login. The platform extracts the user's email, name, and group memberships from the SAML assertion or OIDC claims and creates a corresponding account with the appropriate role.
- Group-based access: Map your IdP groups to platform roles (Owner, Editor, Viewer, Billing). Users inherit their role based on group membership, and role changes take effect on the next login. Multiple group assignments are supported with the highest-privilege role taking precedence.
- Automatic deprovisioning: When a user is removed from the SSO group in your IdP, their next session will fail authentication. Active sessions are invalidated within 1 hour (the Cognito JWT token lifetime). For immediate revocation, use the "Revoke User" option in the team management panel.
- SCIM support (coming soon): System for Cross-domain Identity Management (SCIM) protocol support will enable real-time provisioning and deprovisioning without requiring users to attempt login. This is currently on the product roadmap for enterprise customers.
Role Mapping Configuration
Role mapping connects your IdP group names to platform permission roles. This ensures that employees receive the correct level of access based on their team and responsibilities, without requiring manual role assignment in the AI SEO Agents dashboard.
| IdP Group Name (Example) | Platform Role | Permissions |
|---|---|---|
| seo-admins | Owner | Full access: agents, content, publishing, billing, team management, settings |
| seo-editors | Editor | Create and manage agents, trigger jobs, publish content, view reports |
| seo-viewers | Viewer | View dashboard, articles, reports, and job progress (read-only) |
| seo-billing | Billing | Manage subscription, view invoices, update payment methods |
Group names are configurable — map whatever group names exist in your IdP to the platform roles. The mapping is configured during SSO setup and can be updated at any time by contacting our team or through the Settings panel. Users who belong to no mapped groups are denied access by default (fail-closed security model).
Session Management
SSO sessions are managed through the interaction between your IdP session and the Cognito JWT tokens used by the platform. Understanding session lifecycle helps you configure appropriate timeout and refresh policies for your security requirements.
- Token lifetime: JWT tokens issued by Cognito have a 1-hour lifetime. After expiration, the dashboard automatically refreshes the token using the refresh token (24-hour lifetime) without requiring re-authentication.
- IdP session dependency: Token refresh succeeds only if the user still has an active session in your IdP. If the user has been logged out of the IdP or their session has expired, the refresh fails and they are redirected to the IdP login page.
- Forced re-authentication: For sensitive operations (changing team permissions, managing API keys, updating billing), the platform can require step-up authentication that forces a fresh IdP login regardless of existing session state.
- Concurrent session limits: By default, users can have active sessions on up to 5 devices simultaneously. Enterprise customers can configure stricter limits (e.g., single-session enforcement) to meet their security policies.
- Session revocation: Administrators can revoke all active sessions for a specific user from the team management panel. This invalidates all existing tokens immediately, forcing the user to re-authenticate on their next request.
SSO Troubleshooting
| Issue | Likely Cause | Resolution |
|---|---|---|
| Login redirects to error page | Misconfigured ACS URL or Entity ID in IdP | Verify the ACS URL and Entity ID match the values provided during setup |
| User gets "access denied" after login | User not in a mapped IdP group | Add the user to an appropriate group in your IdP |
| Wrong role assigned | Group mapping mismatch or user in multiple groups | Review group mappings in Settings. The highest-privilege role takes precedence. |
| Token refresh fails repeatedly | IdP session timeout shorter than Cognito refresh token lifetime | Increase IdP session timeout to at least 8 hours, or accept more frequent re-authentication |
| SSO login works but API keys do not | API keys are separate from SSO authentication | API keys authenticate independently. SSO is for dashboard login only. Both methods are valid. |
When troubleshooting SSO issues, check the SAML response in your browser's developer tools (Network tab). The SAML assertion contains the attributes and group memberships being sent by your IdP, which helps identify mapping and attribute issues. For OIDC, inspect the JWT token using a tool like jwt.io.
Related Documentation
- Security Overview — Authentication architecture and encryption details.
- Data Privacy — User data handling and tenant isolation.