Vigilfield Docs
Organization and access

Single sign-on and SCIM

Connect a SAML 2.0 or OpenID Connect identity provider, and provision users and teams with SCIM 2.0.

Connect your identity provider (IdP), such as Okta or Microsoft Entra ID, so your people sign in with their company account. You can also let the IdP create, update and deactivate users and teams in Vigilfield over SCIM 2.0.

Only admins can manage identity providers.

Before you start

Verify the email domains the IdP will serve. See Verified domains. Each domain can belong to only one identity provider.

Connect an identity provider

Create the provider with Create an identity provider. It needs:

  • name: a label for your admins.
  • protocol: saml or oidc.
  • domains: one or more of your verified domains. People with these email domains are sent to this IdP when they sign in.
  • The protocol settings below.
  • enabled: optional, true by default. A disabled provider is not offered at sign-in and its SCIM requests are refused.

SAML 2.0

In saml, give one of:

  • metadata_url: your IdP's metadata URL. It must use https.
  • metadata_xml: the metadata document itself.

Set sign_requests to true if your IdP requires signed requests.

OpenID Connect

In oidc, give:

  • issuer: your IdP's issuer URL. It must use https.
  • client_id and client_secret of the application you registered in your IdP. The secret is never shown again after you save it.
  • scopes: optional extra scopes to request along with openid.

Attribute mappings

attribute_mappings tells Vigilfield which attribute in your IdP's response holds each value. Enter the attribute name your IdP sends.

MappingWhat it sets
emailThe user's email.
display_nameThe user's name.
roleThe user's role. The value must be admin or member.
groupsThe teams the user joins. The values must be Vigilfield team IDs.

How people sign in

  1. The person enters their email on your organization's sign-in page.
  2. If the email domain belongs to an enabled identity provider, Vigilfield sends them to the IdP. They never see a Vigilfield password field.
  3. After they sign in at the IdP, they return to Vigilfield signed in.

If the person has no Vigilfield account yet, one is created on their first sign-in:

  • Their email domain must be fully verified at that moment.
  • They become a member, unless you mapped role. A mapped admin makes them an admin. A mapped owner is treated as admin: single sign-on can never create an owner.
  • They join Everyone. If you mapped groups, they also join the teams it names. Teams managed by Vigilfield or by SCIM cannot be joined this way.
  • A role or teams your IdP sends without the matching mapping are ignored.

Federated users have no Vigilfield password. They cannot use Forgot your password?, and admins cannot reset their password. Manage their credentials in your IdP.

Provision users and teams with SCIM

SCIM lets your IdP keep Vigilfield in step with your directory: new hires appear, leavers are deactivated, and groups become teams.

Turn it on

  1. Turn SCIM on for the provider by setting its scim settings, for example with Update an identity provider.
  2. Go to Administration → Identity Providers. In the provider's menu, select Rotate SCIM bearer and confirm.
  3. Copy the token from New SCIM bearer with Copy bearer. It is shown only once.
  4. In your IdP's SCIM settings, enter the token as the bearer token.

You can also issue the token with the API.

Rotating the token revokes the old one immediately. There is no grace period, so any SCIM client still using the old token is refused on its next call. Update your IdP right after you rotate.

Endpoints

PathSupports
/scim/v2/UsersGET (list), POST (create)
/scim/v2/Users/{id}GET, PATCH, DELETE
/scim/v2/GroupsGET (list), POST (create)
/scim/v2/Groups/{id}GET, PATCH, DELETE
/scim/v2/ServiceProviderConfig, /scim/v2/Schemas, /scim/v2/ResourceTypesDiscovery, no token needed

PUT is not supported. Configure your IdP to send PATCH.

Filters support eq only, on userName, externalId, displayName and emails[type eq "work"].value. A page holds at most 200 results.

What SCIM can do to users

  • Create. The user's email domain must be verified, connected to this IdP, and not revoked. An email that already has an account is refused. New users are always members and join Everyone.
  • Update. Only active and displayName can change.
  • Deactivate. Setting active to false, or deleting the user, makes them Inactive and signs them out everywhere. The user is kept, not erased.
  • Reactivate. Setting active to true.

An IdP only sees and changes the users it created.

SCIM cannot:

  • change a user's role or email,
  • deactivate or reactivate an admin or the owner,
  • deactivate a user who owns apps, until those apps have a new owner.

Groups become teams

Each SCIM group becomes a Vigilfield team, marked Managed by and your provider's name.

  • Your IdP can rename the group and add, replace or remove members.
  • Only users this IdP created can be members. Other users are skipped.
  • Deleting the group deletes the team. Its members lose the team, and the team's grants are revoked.

In Vigilfield, admins cannot rename these teams, change their members or delete them. Make those changes in your IdP. Admins can still give these teams grants.

API reference

Verified domains

Prove that your organization owns an email domain, and what a verified domain unlocks.

Apps, installations and clients

Give a script or service its own identity and OAuth credentials for the Vigilfield API.

On this page

Before you startConnect an identity providerSAML 2.0OpenID ConnectAttribute mappingsHow people sign inProvision users and teams with SCIMTurn it onEndpointsWhat SCIM can do to usersGroups become teamsAPI reference