SheerID API for educator verification

SheerID is a third-party service that we use for verifying real identities and roles of our users (educators, not students). We use SheerID in three ways:

1. an iframe hosted on their servers which we load in Step 3 of the Educator signup flow,
2. a webhook endpoint to which SheeerID posts any and all updates about our users after they submit the form in the iframe,
3. an API from which we gather detailed information about users who submitted the form in the iframe.

The way that SheerID lets us know when there is a new user in the verification process is by making a POST request to an endpoint as a webhook—handled in Accounts by the EducatorSignup::SheeridWebhook class which is a Lev handler. SheerID sends us a verificationId, and then using that, we make a request to SheerID's API requesting more details (SheeridAPI.get_verification_details(verification_id))

In the ideal scenario, our users are instantly verified by SheerID, in which case the user's SheerID verification currentStep will be "success". At that point, the VerifyEducator class handles the request.

What EducatorSignup::VerifyEducator does is it gets the user's verification details. That is, the:

• currentStep (either "success" or "docUpload" or "rejected")
• firstName
• lastName
• email
• organization.name

And then it updates the User record with that information which we trust to be accurate while changing the user's faculty_status to "confirmed_faculty". At this point, when the user is verified, we update the user's Salesforce Lead with all the information we have about the user (see EducatorSignup::UpdateSalesforceLead)

Sometimes, when users are not instantly verified, they may go to the "docUpload" SheerID step. In that case, Accounts just stores the user's sheerid_verification_id, sets the user's faculty_status to "pending_faculty", stores the sheerid_reported_school, as well as the first and last name. Users have three opportunities to submit a document that serves as proof of their identity and after the third time being rejected, their faculty status changes to "rejected_faculty" in which case we will allow them to submit their information for review by our own Customer Support team.

Important links

• SheerID verification steps: https://developer.sheerid.com/concepts#steps
• Diagram to the Teacher flow in SheerID: https://developer.sheerid.com/reference#teacher-flow
• SheerID API reference: https://developer.sheerid.com/reference#teacher

Relevant pieces of code

• EducatorSignup::ProcessSheeridWebhookRequest https://github.com/openstax/accounts/blob/660711e8985fa40e0fddc531f0115d7746048eac/app/routines/newflow/educator_signup/process_sheerid_webhook_request.rb#L5
• EducatorSignupController#sheerid_webhook https://github.com/openstax/accounts/blob/660711e8985fa40e0fddc531f0115d7746048eac/app/controllers/newflow/educator_signup_controller.rb#L112-L132
• EducatorSignupController::VerifyEducator https://github.com/openstax/accounts/blob/660711e8985fa40e0fddc531f0115d7746048eac/app/routines/newflow/educator_signup/verify_educator.rb#L5
• SheeridAPI::Request https://github.com/openstax/accounts/blob/660711e8985fa40e0fddc531f0115d7746048eac/lib/sheerid_api/request.rb#L1-L2