Provisioning

Manage members via SCIM provisioning

SCIM provisioning is a method based on integration of account information between Swit and IdPs. It allows real time application of changes in user information, and can be used from the Swit Advanced plan and above. Access control and subscription are managed automatically depending on the membership statuses of users, so organization admins don't have to manage the seats.

Provisioning integration overview

Swit provisioning follows the SCIM (System for Cross-domain Identity Management) 2.0 standard, and is managed and updated with the designated IdP regularly.

Integration fundamentals

The IdP requests whether the users or groups in the IdP match the information in Swit, and depending on the response, sends the following requests:

• If there is no such user or group in Swit: Create the same account or team on Swit using the Create request
• If there is such user or group in Swit but the information differ: Apply the same information to Swit using the Update request
• If there is a member or group deactivated in the IdP still active in Swit: Deactivate the user account or delete the team with the Disable/Delete request in Swit
• If the information in Swit matches: No follow-up request

Pre-provisioning

• Enter Swit's endpoint URL for SCIM in the IdP.
  • When the IdP confirms and updates user and group information in the future, requests will be sent to this URL.
• Enter authentication information for open API to be used when sending requests from IdP to Swit.

Configure Swit provisioning with an IdP

You can configure Swit user provisioning with an IdP as follows. To use Microsoft Entra ID (Azure Active Directory) or Okta as an IdP, see here to find out about a more specific procedure.

1. Visit an IdP you want to configure provisioning with.

2. Follow the IdP's user manual to enter the SCIM-related information below. The names of labels may vary depending on the IdP.

   • SCIM endpoint URL: https://saml.swit.io/scim/v2
   • Authentication information (reference: https://devdocs.swit.io/docs/guides/
     1. Select OAuth 2.0 method
     2. OAuth authentication endpoint: https://openapi.swit.io/oauth/authorize
     3. OAuth token swap endpoint: https://openapi.swit.io/oauth/token
     4. OAuth scope: admin:read admin:write
     5. For Client ID and Client Secret, you can configure the app on the Swit Developers website and copy the relevant values.
     6. Add the OAuth callback URL provided by the IdP in the Redirect URLs section as follows:

3. After the OAuth authentication, continue with mapping from the IdP the mapping attributes.

Mapping attributes for provisioning to Swit

The user and group attributes used by Swit are defined as follows, and each attribute has a corresponding attribute on your IdP for mapping.

User attributes

• User ID on the IdP: externalId (recommended to use the attributes at the time of matching)
• Email address: userName (recommended to use the attributes at the time of matching)
• User activation status: active
• Telephone number: phoneNumbers
• User name: displayName
• Interface language to use in Swit: preferredLanguage
  • Recommended to sync only when creating accounts and not with accounts already in use. Most IdPs provide these options based on attributes.
• Custom field: urn:ietf:params:scim:schemas:extension:SwitCustomField:2.0:User:<<CUSTOM_FIELD_ID>>

Group attributes

The "group" in an IdP is synced with the "team" in Swit.

• User specific ID in the IdP: externalId
• Group name: displayName (recommended to use the attributes at the time of matching)
• List of members: members

Provisioning options manageable on Swit

• Synchronizing user attributes with provisioning means when the members edit their profile information, it is synchronized with the information on the IdP, which can cause confusion. Accordingly, Swit provides an option that doesn't allow members to self-edit their profile if provisioning sync is used.
• To use this option, enter Admin console > SAML configuration, and in Provisioning sync, select "Member profiles change only via provisioning". (This option can be used only when Enable single sign-on with SAML is selected.)
• When this option is used, the members cannot change their profile information other than the custom fields as shown below.

Provisioning sync cases by IdP

Below are provisioning sync cases by Microsoft Entra ID (Azure Active Directory) and Okta.

Configure provisioning with Microsoft Entra ID (Azure Active Directory)

Install the Swit app in Azure AD Gallery as follows. If the app is already installed for SSO settings, select the app.

1. Sign in to Azure Portal, click on Active Directory > Enterprise applications, and select All applications.
2. Select Swit from the list of apps.

You can configure provisioning in the Swit app installed in AAD.

1. Select Provisioning in the left panel, and click on Get Started to start configuring.
2. Set the provisioning mode to Automatic.
3. In Admin Credentials, click on the Authorize button to start the OAuth 2.0 authentication. Note that you have to be signed in with Swit's admin account that is synchronized.
4. The Mappings section is where you can map user and group attributes to synchronize. Most mappings are already configured for maps installed from Azure AD Gallery, but if you need customized settings, see the Mapping attributes for provisioning to Swit section to change the settings.
5. If needed, check the items you want in Settings, and click on Save to finish setting.
6. In the left panel, select Users and groups, and add the users you want using Swit provisioning.
7. Go back to Provisioning, and click on the Start provisioning tab.
   • AAD's provisioning synchronizes user and group attributes every 40 minutes maximum. To check on provisioning without waiting for the next cycle, click on the Provision on demand tab.

Okta

1. Sign in to Okta with an admin account.

2. In Admin Console > Applications, select Applications.

3. Select the app to configure provisioning.

4. In the General tab, click the Edit button at the right of the App Settings section.

5. Select SCIM for Provisioning, and click on Save.

6. The Provisioning tab will be created. In the tab, move to the Integration page.

7. At the right of the SCIM Connection section, click on Edit, and fill in the following items.

   • SCIM connector base URL: https://saml.swit.io/scim/v2
   • Unique identifier field for users: userName
   • Supported provisioning actions: Click on all five following items
     • Import New Users and Profile Updates
     • Push New Users
     • Push Profile Updates
     • Push Groups
     • Import Groups
   • Authentication Mode: OAuth 2

8. Fill in the OAuth 2 section following Configure Swit provisioning with an IdP. - Note that it is impossible to enter the scope information separately, so add as parameters in Authorization endpoint URI. - https://openapi.swit.io/oauth/authorize?scope=admin%3Aread%20admin%3Awrite

   • In the list of Redirect URLs in the Swit Developers site, add https://your.site.com/oauth/callback.

9. In Settings, select To App, click on the Edit button at the right of the Provisioning to App section to select the items for provisioning, and click on Save.

10. In the Attribute Mappings section at the bottom, type in the mapping attributes necessary for provisioning.