Skip to main content
Connecting your Identity Provider (IdP) to Serval enables automated access provisioning, leverages your existing group structure, and integrates with onboarding and offboarding workflows.

​
What Is an IdP?

An Identity Provider (IdP) is the central system that manages user identities and group memberships across your organization. Your IdP often serves as the single source of truth for who works at your company and which teams they belong to. Common IdPs include:
  • Okta
  • Microsoft Entra (formerly Azure AD)
  • Google Workspace
  • Rippling
If you already use one of these systems to manage employee accounts and groups, you have an IdP. Connecting it to Serval unlocks powerful automation capabilities.

​
Why Connect Your IdP to Serval

Connecting your IdP transforms how you manage access by automating provisioning and leveraging your existing organizational structure. Serval provides just-in-time access by adding users to pre-existing IdP groups.

​
Key benefits

Automated provisioning

Grant and revoke access by adding or removing users from IdP groups—no manual work in individual applications

Use existing structure

Import all IdP groups to Serval and reuse them for access management without recreating your org structure

Streamlined workflows

Integrate with onboarding and offboarding to automatically provision or revoke access as employees join or leave

​
How IdP integration improves access management

Manual and error-prone:
  • Admin manually creates accounts in each application
  • Access must be granted individually per app
  • Offboarding requires tracking down every system
  • No centralized view of who has access where
  • High risk of forgotten access after employee leaves
Automated and auditable:
  • Add user to an IdP group, access provisioned automatically
  • One group membership can grant access to multiple apps
  • Offboarding removes all access by removing from groups
  • Complete audit trail in both Serval and your IdP
  • Temporary access automatically expires and removes group membership

​
Connect Your IdP

1

Check supported providers

Review the integrations overview to see supported IdP providers.
If your IdP isn’t listed, you can create a custom integration. Contact support for guidance on building custom IdP integrations.
2

Follow the integration guide

Each IdP has specific setup steps. Follow the integration guide for your provider to:
  • Create API credentials in your IdP
  • Grant necessary permissions to Serval
  • Configure the integration in Serval
  • Test the connection
3

Wait for group import

Configure SCIM (System for Cross-domain Identity Management) to automatically sync users and groups from your Identity Provider.After connecting, Serval imports all groups from your IdP as individual resources with the default role “Member” unless otherwise specified as “Admin.”
Large organizations with thousands of groups may take longer.
4

Verify the import

Navigate to Resources to see all imported IdP groups. Each group appears as a resource you can use in access management.
5

Start using Linked Groups

You can now provision access via Linked Groups when configuring roles. This automatically adds and removes users from IdP groups as access is granted and revoked.

​
Using Your IdP in Access Management

Once connected, your IdP integrates with Serval in several ways:

​
Linked Group Provisioning

The most common use case: provision access by adding users to IdP groups. How it works:
1

Configure a role

When setting up a role, choose “Linked Groups” as the provisioning method
2

Select the IdP group

Choose which IdP group should grant access to this role
3

Access is granted

When a user requests and is approved for access, Serval adds them to the IdP group
4

Your IdP provisions access

Your IdP’s existing SCIM or provisioning rules grant the actual application access
5

Access expires automatically

For temporary access, Serval removes the user from the group when access expires
Example: Configure the “GitHub Engineering Team - Member” role to use the “GitHub-Engineering” Okta group. When users request access, they’re added to the Okta group, which grants GitHub access via SCIM. After seven days, they’re automatically removed.

​
Importing Existing Role Configurations

Serval analyzes your IdP groups to suggest role configurations you should import. How it works:
  1. Serval identifies IdP groups that already provision access to applications
  2. These appear in the import portal as suggested roles
  3. You can import them with one click to start managing access via Serval
  4. Existing group memberships are preserved
Importing a role doesn’t change who currently has access. It simply lets Serval manage future access requests using your existing IdP structure.

​
Workflow Integration

Use your IdP in custom workflows for complex provisioning scenarios. Example workflows:

Onboarding automation

When a new employee is added to your IdP, trigger a workflow that:
  • Creates a ticket for IT setup
  • Adds to default company groups
  • Sends welcome email
  • Provisions standard tool access

Role change provisioning

When someone changes teams (reflected in IdP), trigger a workflow that:
  • Removes old team access
  • Adds new team access
  • Notifies managers
  • Updates documentation

Offboarding cleanup

When an employee is deactivated in your IdP, trigger a workflow that:
  • Lists all active access
  • Revokes all permissions
  • Creates audit report
  • Archives user data

Compliance review

Periodically compare Serval access with IdP group membership to:
  • Identify access granted outside Serval
  • Flag orphaned group memberships
  • Generate compliance reports
  • Alert on discrepancies

​
Managing IdP Groups in Serval

​
Understanding Imported Groups

When Serval imports your IdP groups, they appear as resources with special properties: What gets imported:
  • Group name
  • Group description
  • Current members
  • Nested groups (if applicable)
What doesn’t change in your IdP:
  • Existing group memberships remain unchanged
  • Your IdP’s group structure stays intact
  • Users maintain current access
Serval imports IdP groups as read-only snapshots. Changes you make in Serval (via access requests) sync back to your IdP, but Serval doesn’t modify your IdP’s group structure itself.

​
Group Sync Behavior

Serval keeps IdP groups in sync:
  • Real-time for Linked Groups: When Serval adds/removes users via Linked Group provisioning, changes happen immediately
  • Periodic for group list: The list of groups and their members syncs every 24 hours to catch changes made directly in your IdP
  • On-demand refresh: You can manually trigger a sync from the IdP integration settings

​
Special Cases: Groups to Exclude from Access Management

Some IdP groups should not be managed through Serval’s access management:
Google groups used as access control lists (ACLs) for SSO don’t grant application access—they only control who can authenticate.These groups typically:
  • Enable SAML SSO to applications
  • Don’t grant specific permissions in the app
  • Follow naming patterns like “[app]-sso-users”
Instead: Manage the actual application access through Serval, not the SSO group.
Email distribution lists are for communication, not access control.Why to exclude:
  • They don’t grant application access
  • Adding/removing members doesn’t affect permissions
  • They’re managed by different teams
Instead: Use dedicated access groups, not email lists, for provisioning.
Some Okta groups grant automatic access to all employees (birthright access).Special handling:
  • These groups are imported but marked as “birthright”
  • Users don’t request access—they’re added automatically
  • Removing a user from these groups requires special approval
Instead: Configure these as system-managed groups with restricted modification.
Communication channel membership is typically managed within Slack/Teams, not through IdP groups.Why to exclude:
  • Channel membership doesn’t map to IdP groups
  • Users join/leave channels frequently
  • Channel access is more social than security-critical
Instead: Let users manage their own channel memberships in Slack/Teams.

​
Best Practices

Connect IdP first

Set up your IdP integration before configuring other applications. This lets you use Linked Groups from the start.

Use descriptive group names

Ensure your IdP groups have clear names that explain what access they grant. This makes role configuration easier.

Leverage existing structure

Don’t recreate groups in Serval. Use your IdP’s existing group structure for access management.

Document group purposes

Add descriptions to IdP groups explaining what access they grant. This helps when configuring Linked Groups.

Audit group memberships

Regularly review who’s in each IdP group. Serval can only provision access correctly if group memberships are accurate.

Plan for nested groups

If your IdP uses nested groups, understand how they work before configuring Linked Groups to avoid unintended access.

​
Troubleshooting Common Issues

Possible causes:
  • API permissions aren’t sufficient
  • Connection to IdP is broken
  • Import is still in progress
Solutions:
  • Verify API credentials have read access to groups
  • Check the integration status in Serval
  • Wait 5-10 minutes and refresh the page
  • Re-authenticate the integration if needed
Possible causes:
  • Application doesn’t integrate with your IdP
  • SCIM provisioning isn’t configured
  • IdP provisioning rules are incorrect
Solutions:
  • Verify the application supports SCIM from your IdP
  • Check your IdP’s provisioning logs for errors
  • Confirm the IdP group is correctly mapped to the application
  • Test provisioning directly in your IdP first
Possible causes:
  • Sync hasn’t run in 24 hours
  • Manual changes were made in IdP after last sync
  • Sync failed silently
Solutions:
  • Manually trigger a sync from integration settings
  • Check sync logs for errors
  • Verify API credentials are still valid
  • Wait a few minutes for sync to complete
Possible causes:
  • Group was created after last sync
  • Group is excluded by sync filters
  • Group doesn’t have any members
Solutions:
  • Trigger a manual sync
  • Check if empty groups are excluded in integration settings
  • Verify the group exists in your IdP
  • Check for name changes in your IdP

​
Security Considerations

Important: Connecting your IdP to Serval grants API access to group memberships. Follow these security best practices:

Use service accounts

Create a dedicated service account in your IdP for Serval integration. Don’t use a personal account.

Grant minimal permissions

Only grant read access to groups and users. Serval only needs write access to modify group membership for provisioning.

Enable audit logging

Turn on audit logging in your IdP to track all changes made by Serval’s service account.

Review regularly

Periodically review the API credentials and permissions to ensure they’re still appropriate and secure.
Serval encrypts all IdP credentials and uses them only to sync groups and modify memberships for provisioning. Your IdP credentials are never exposed to end users.