Check out our upcoming webinars and client office hours calendar here!

How Can We Help?

Search icon

Search Results

About User Provisioning

User provisioning encompasses the discrete processes of account creation, granting access to institutional data, and defining roles for one or more products. User provisioning can be done at the platform level within each product application or via API integration.

 

Check out this article on how to Provision Users and Product Access via the API for more information using the API for provisioning.

 

For testing purposes, the best practice is to create a small group (<5) of fake profiles with dummy data and fake email addresses. A user's core profile contains their name, address, phone number, and email address, and changes to user profiles in a development tenant will be reflected in that user's profile in any other tenant to which they're related (e.g., production or another institution) and vice versa. 

See this article for more on Interfolio's environment architecture.

 

About User Provisioning…

…via the API

User Provisioning Process

Once the steps below are done, the end result is a fully provisioned user that has an underlying account associated with the institution's tenant and with an assigned role for one or more products.

 
  1. Create the underlying account with the required attributes (first name, last name, and email address) and the feature-dependent attributes (UID, SSO ID).

    Note that some products require additional attributes (such as FacultyID in FAR).

     
  2. Assign the new user(s) with one of our products and assign permissions for that product.
 
 

Technical Details

  • User accounts are created with a PID (a user identifier generated by Interfolio) and are tied to an institution's tenant by an association record.
  • Users are granted access to a product with a permissions record in that product application that references the PID.
  • User access can be revoked for a given product by removing the permissions record, deactivating that user's association with the tenant, or removing the tenant association altogether.
 
 
 
 

…via SFTP

Interfolio supports the ability to provision users via JSON files sent over SFTP. This article covers the steps needed to provision users, including optional attributes your institution can send. To get started with our SFTP services, please fill out the Request Form for SSO & SFTP Setup, API Keys.

The process of provisioning users via SFTP is a timed job wherein the Interfolio API processes a file containing user data to add, update, or deactivate users at your institution. Each action – add, update, or deactivate – is performed separately and requires separate files. The SFTP processes run daily, usually at the beginning of the day (3am UTC), but can be configured to run at any specified time and interval. 

 

Bulk user provisioning via SFTP can benefit clients who need to provision users via an automated job but cannot or will not set up API integrations to do so. 

 

1. Setup

Once an SFTP directory has been created for your institution, please contact Interfolio’s Technical Services team to setup user provisioning. Your project team will need to work with the Technical Services team to validate a test file as part of the implementation/setup process.

 
 

2. Prepare Files to Process

In order for Interfolio to process your create/update/deactivate lists, the files will need to be prepared in a specific format. Each file will be a JSON file with a file extension of “.json” and contain an array of user objects. The filenames will be as follows: 

add.json 
update.json 
deactivate.json 

Users listed in the “add” file will be created and associated with your institutional hierarchy. Users listed in the “update” file will have their attributes updated to match those contained in the file. Users listed in the “deactivate” file will have their hierarchical permissions and access revoked. The full user object within the Interfolio API contains the following attributes: 

{ 
"first_name": string, 
"last_name": string, 
"email": string, 
"institution_user_id": string, 
"external_user": boolean, 
"eppn": string, 
"unit_id": integer 
} 
Attributes Description
  • first_name
  • last_name
  • email
  • university_user_id
Required Attributes
institution_user_id
  • The parameter “institution_user_id” can be any string and usually contains a value that is proprietary to your internal systems
  • The value for “institution_user_id” is set in the “add” file and cannot change
  • It is also required for the “update” file and “deactivate” file
external_user
  • If your institution has chosen to use SSO as your authentication method, you can pass “external_user” with the boolean value of “true” to exempt a user from SSO authentication enforcement
  • Otherwise, the default value is “false”
eppn You can also optionally provision your users with a defined value for “eppn” to provision their SSO access ahead of time. The “eppn” attribute is used with the Shibboleth / SAML SSO strategy and can be defined as any string.
unit_id You can assign a basic unit association by passing a value for “unit_id”. The value for “unit_id” can be the ID for any unit within your unit hierarchy in Interfolio’s API. 
 
 

3. Create Payload for SFTP

After preparing your lists of users, the next step is to prepare the package to upload to Interfolio’s SFTP server. The package will be a “TAR” file with a file extension of “.tar” and will have a specific naming convention, “prefix_date_service.tar”. The “prefix” will be your SFTP username. The date will be in “YYYYMMDD” format. The service will be either “Search” (for Faculty Search) or “Tenure” (For Review, Promotion, & Tenure) depending on the service in which you’re adding / updating / deactivating the given users. An example filename would be “charlie_20170123_tenure.tar”. You can create this file by running one of the following terminal commands:

$ tar -cvf charlie_20170123_tenure.tar /users 
$ tar -cvf charlie_20170123_tenure.tar add.json update.json deactivate.json 
 
 

4. Upload the Payload

Now that you have the package of user files prepared, the next step is to upload the package to Interfolio’s SFTP server. First, log into the SFTP with the following credentials, provided to you at the time of setup:

Connection Type: SFTP (SSH File Transfer Protocol)
Server/Host: transfer.ops.interfolio.com
Username: [Your Interfolio-provided username]
Password: None
SSH Key: Your private key.

You can connect using the private key you set up, and please work with your IT staff to ensure permit access to TCP Port 22 (SSH) destination in your institution’s firewalls as follows: transfer.ops.interfolio.com (3.215.32.29, 52.202.198.155)

Next, change directory into the “incoming” directory by running the following:
sftp> cd incoming

Finally, upload your file to the “incoming” directory by running the following:
sftp> put charlie_20170123_tenure.tar

And, that’s it! That’s all you need to do. From there, the Interfolio SFTP service will take over and process your files. If you have any questions, please contact your help@interfolio.com or your Client Success Manager.

 
 

MetaData

When provisioning users via SFTP, you can include arbitrary “key”:”value” pairs expressed as JSON. This data is saved as metadata and can be used for reporting purposes. Below is an example of what to include in these files. In this example, the additional parameters of “favorite_color” and “on_site” are stored as metadata: 

[ 
{ 
"first_name": "Joe", 
"last_name": "User", 
"email": "joe.user@interfolio.com", 
"unit_id": 9557, 
"university_user_id": "jhu3v", 
"favorite_color": "green", 
"on_site": false 
}, 
{ 
"first_name": "Jane", 
"last_name": "Doe", 
"email": "jane.doe@interfolio.com", 
"university_user_id": "jld8e", 
"favorite_color": "blue", 
"on_site": true 
} 
] 

Troubleshooting Scenarios

Error Message Explanation of Message Fix
“user already exists with that email” This can occur when trying to update a faculty email with an email address that is already in use by a different Interfolio account. Contact Interfolio support to remediate.
“user already exists with that UID”    
“user already exists with that SSO ID”    
 
 
Was this article helpful?
Give feedback about this article