Automate User Provisioning with SCIM

Automate user lifecycle management with your identity provider

Manually adding and removing users from Vouch when people join or leave your organization is error-prone and easy to forget. A missed offboarding means someone retains access to hardware-backed credentials they should no longer have.

SCIM (System for Cross-domain Identity Management) lets your identity provider – Google Workspace, Okta, Azure AD, or OneLogin – handle this automatically in real time. Vouch supports the SCIM 2.0 protocol (RFC 7644 (opens in new tab)) for automated user provisioning and de-provisioning. When SCIM is configured, your identity provider (IdP) can automatically:

• Create new Vouch user accounts when people join your organization.
• Update user attributes (name, email, role) when they change in your directory.
• Deactivate accounts instantly when someone leaves or changes roles.

This removes the manual steps and keeps credential access in sync with your corporate directory.

How It Works

1. You generate a SCIM bearer token from the Vouch server.
2. You configure your identity provider to point at Vouch’s SCIM 2.0 endpoint.
3. The IdP pushes user lifecycle events (create, update, deactivate) to Vouch in real time.
4. Vouch processes each event and updates its internal user directory accordingly.

Because SCIM is a standardized protocol, Vouch works with any identity provider that supports SCIM 2.0 – including Google Workspace, Okta, Azure AD (Entra ID), and OneLogin.

Step 1 – Generate a SCIM Token

Before your identity provider can communicate with Vouch, you need to generate a bearer token that the IdP will use to authenticate its requests.

First, ensure you are logged in with an account that has organization administrator privileges:

vouch login

Then create a SCIM token:

curl -X POST https://us.vouch.sh/api/v1/org/scim-tokens \
  -b ~/.local/state/vouch/cookie.txt \
  -H "Content-Type: application/json" \
  -d '{"description": "Google Workspace SCIM", "expires_in_days": 365}'

The response includes the plaintext token:

{
  "id": "scim_tok_abc123",
  "description": "Google Workspace SCIM",
  "token": "vouch_scim_xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx",
  "expires_at": "2027-01-15T00:00:00Z",
  "created_at": "2026-01-15T12:00:00Z"
}

Security note: Vouch stores only a cryptographic hash of the token. The plaintext value is shown exactly once in the creation response. Copy it immediately and store it securely – you will not be able to retrieve it again. If you lose the token, revoke it and create a new one.

The expires_in_days field is required and must be an integer between 1 and 365. Set the expiry to match your token-rotation schedule — for example, 365 days with annual rotation.

Step 2 – Configure Your Identity Provider

Use the following values when configuring SCIM in your identity provider:

Replace the token value with the plaintext token you received in Step 1.

Google Workspace

1. Open the Google Admin Console (opens in new tab).
2. Navigate to Apps > Web and mobile apps.
3. Find or add the Vouch application.
4. Open the Auto-provisioning section.
5. Set the SCIM Base URL to https://us.vouch.sh/scim/v2.
6. Set the Authentication Type to Bearer Token and paste your SCIM token.
7. Click Test Connection to verify.
8. Enable auto-provisioning and configure the desired attribute mappings.
9. Click Save.

Okta

1. Open the Okta Admin Dashboard.
2. Navigate to Applications > Applications.
3. Select or create the Vouch application.
4. Go to the Provisioning tab and click Configure API Integration.
5. Check Enable API Integration.
6. Set the SCIM 2.0 Base URL to https://us.vouch.sh/scim/v2.
7. Set the API Token to the SCIM bearer token from Step 1.
8. Click Test API Credentials to verify connectivity.
9. Click Save.
10. Under Provisioning > To App, enable the desired actions: Create Users, Update User Attributes, and Deactivate Users.

Azure AD (Entra ID)

1. Open the Azure Portal (opens in new tab) and navigate to Azure Active Directory > Enterprise Applications.
2. Select or create the Vouch application.
3. Go to Provisioning and set the Provisioning Mode to Automatic.
4. Under Admin Credentials:
   • Set Tenant URL to https://us.vouch.sh/scim/v2.
   • Set Secret Token to the SCIM bearer token from Step 1.
5. Click Test Connection to verify that Azure can reach the Vouch SCIM endpoint.
6. Configure attribute mappings under Mappings to align Azure AD attributes with Vouch user fields.
7. Set Provisioning Status to On.
8. Click Save to begin provisioning.

OneLogin

1. Open the OneLogin Admin Panel.
2. Navigate to Applications > Applications.
3. Select or create the Vouch application.
4. Go to the Provisioning tab.
5. Enable provisioning and set the SCIM Base URL to https://us.vouch.sh/scim/v2.
6. Set the SCIM Bearer Token to the token from Step 1.
7. Under Provisioning Actions, enable Create user, Update user, and Delete user.
8. Click Save.

Step 3 – Test the Integration

After configuring your identity provider, verify that the SCIM connection is working correctly by querying the Vouch SCIM endpoints directly.

Check the Service Provider Configuration

This endpoint returns the SCIM capabilities supported by Vouch:

curl -s https://us.vouch.sh/scim/v2/ServiceProviderConfig \
  -H "Authorization: Bearer vouch_scim_xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx" \
  | jq .

A successful response returns a JSON object describing the supported SCIM features, including authentication schemes, bulk support, and filtering capabilities.

List Provisioned Users

Retrieve the list of users that have been provisioned through SCIM:

curl -s https://us.vouch.sh/scim/v2/Users \
  -H "Authorization: Bearer vouch_scim_xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx" \
  | jq .

This returns a ListResponse containing all SCIM-managed users and their attributes.

List Provisioned Groups

Retrieve the list of groups that have been provisioned through SCIM:

curl -s https://us.vouch.sh/scim/v2/Groups \
  -H "Authorization: Bearer vouch_scim_xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx" \
  | jq .

This returns a ListResponse containing all SCIM-managed groups and their membership information.

SCIM 2.0 Endpoints

Vouch implements the following SCIM 2.0 endpoints:

All endpoints require a valid SCIM bearer token in the Authorization header. Filtering is supported on the Users and Groups list endpoints using the SCIM filter syntax (e.g., ?filter=userName eq "alice@example.com").

Domain Validation

POST /scim/v2/Users requires userName (or an entry in emails[]) to be an email address — Vouch keys users by email. The email’s domain must also be one your organization has proven it owns: the primary domain, or an additional domain that has completed DNS TXT verification. A push for any other domain — including a domain that is added but not yet verified, or a subdomain of a verified one — is rejected with 400 and "scimType": "invalidValue".

See Email Domains for adding and verifying additional domains.

Immediate De-provisioning

SCIM integration provides immediate de-provisioning. When an employee leaves your organization or changes roles:

1. Your identity provider sends a PATCH or DELETE request to the Vouch SCIM endpoint to deactivate the user.
2. Vouch immediately marks the user account as inactive.
3. All active sessions for that user are revoked instantly, and their issued SSH certificates are revoked via the CA revocation list.
4. The user can no longer obtain new credentials. Other previously issued short-lived credentials continue to function until their natural expiration — up to 1 hour for AWS STS, and up to 12 hours for ECR and CodeArtifact tokens.

Because all Vouch credentials are short-lived, the exposure window after de-provisioning is limited. Sessions and SSH certificates are revoked immediately, and outstanding tokens expire on their own within at most 12 hours.

With Vouch and SCIM, de-provisioning is automated, and exposure is bounded by the credential lifetimes above.

Managing SCIM Tokens

Organization administrators can list, create, and revoke SCIM tokens through the Vouch API.

List All SCIM Tokens

Retrieve all active SCIM tokens for your organization:

curl -s https://us.vouch.sh/api/v1/org/scim-tokens \
  -b ~/.local/state/vouch/cookie.txt \
  | jq .

The response includes token metadata (ID, description, creation date, expiration date) but never the plaintext token value.

Create a New Token

curl -X POST https://us.vouch.sh/api/v1/org/scim-tokens \
  -b ~/.local/state/vouch/cookie.txt \
  -H "Content-Type: application/json" \
  -d '{"description": "Okta SCIM Integration", "expires_in_days": 180}'

The response includes the plaintext token. Store it securely – it will not be shown again.

Revoke a Token

Revoke a SCIM token by its ID to immediately disable it:

curl -X DELETE https://us.vouch.sh/api/v1/org/scim-tokens/scim_tok_abc123 \
  -b ~/.local/state/vouch/cookie.txt

After revocation, any identity provider using this token will receive 401 Unauthorized responses and provisioning will stop until a new token is configured.

Rotating SCIM Tokens

To rotate a SCIM token without interrupting provisioning, follow this four-step process:

1. Create a new token with a descriptive name that indicates it is the replacement:

   curl -X POST https://us.vouch.sh/api/v1/org/scim-tokens \
     -b ~/.local/state/vouch/cookie.txt \
     -H "Content-Type: application/json" \
     -d '{"description": "Google Workspace SCIM (rotated 2026-02)", "expires_in_days": 365}'
   

2. Update your identity provider with the new token value. Follow the configuration steps for your IdP described in Step 2 above, replacing the old token with the new one.

3. Test the new token by triggering a sync from your identity provider or by querying the SCIM endpoint directly with the new token:

   curl -s https://us.vouch.sh/scim/v2/Users \
     -H "Authorization: Bearer vouch_scim_NEW_TOKEN_HERE" \
     | jq '.totalResults'
   

4. Revoke the old token once you have confirmed that the new token is working:

   curl -X DELETE us.vouch.sh/api/v1/org/scim-tokens/scim_tok_OLD_ID \
     -b ~/.local/state/vouch/cookie.txt
   

By creating the new token before revoking the old one, you ensure there is no window during which provisioning is interrupted.

Troubleshooting

401 Unauthorized

The SCIM token is invalid, expired, or revoked.

• Verify the token has not expired by listing your active tokens.
• Ensure the Authorization header uses the format Bearer <token> with no extra whitespace or characters.
• If the token was recently created, confirm you copied the full plaintext value – it is only shown once during creation.
• If the token has expired or been revoked, create a new token and update your identity provider configuration.

409 Conflict

A user or group with the same unique identifier already exists.

• This occurs when your identity provider attempts to create a user who has already been provisioned, either through a previous SCIM sync or through manual registration.

• Check whether the user already exists in Vouch by querying the Users endpoint with a filter:

  curl -s "https://us.vouch.sh/scim/v2/Users?filter=userName%20eq%20%22alice%40example.com%22" \
    -H "Authorization: Bearer vouch_scim_xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx" \
    | jq .
  

• If the user exists, the IdP must update the existing record with PUT or PATCH rather than POST a new one; IdPs that support SCIM conflict resolution do this automatically after the initial conflict.

Users Not Syncing

If users are not appearing in Vouch after configuring SCIM:

• Verify the SCIM Base URL. Ensure it is set to https://us.vouch.sh/scim/v2 with no trailing slash.

• Test connectivity. Use the ServiceProviderConfig endpoint to confirm the IdP can reach Vouch:

  curl -s https://us.vouch.sh/scim/v2/ServiceProviderConfig \
    -H "Authorization: Bearer vouch_scim_xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx" \
    | jq .
  

• Check your IdP’s provisioning logs. Look for HTTP error codes or timeout messages in the IdP’s log of SCIM operations.

• Confirm provisioning is enabled. In Okta and Azure AD, you must explicitly enable provisioning actions (Create, Update, Deactivate) after configuring the API connection.

• Verify user assignment. IdPs that scope provisioning to assigned users or groups only provision those users. Check that the intended users or groups are assigned to the Vouch application.

Attribute Mapping Issues

If user attributes (name, email, department) are not appearing correctly in Vouch:

• Review the attribute mappings in your identity provider’s SCIM configuration.
• Vouch expects the standard SCIM 2.0 User schema attributes:
  • userName – The user’s email address (used as the unique identifier).
  • name.givenName – The user’s first name.
  • name.familyName – The user’s last name.
  • emails – An array of email objects; the primary email is used for notifications.
  • active – A boolean indicating whether the account is active.
• Ensure your IdP is mapping its directory attributes to these standard SCIM fields.