Integrating your app with TutorCruncher

Header Wave SVG

How do I add my app to the list of Online Integrations TutorCruncher provides?

We love adding new tools into TutorCruncher, and we've made it super easy for you to do just that. We use allow users to sign into your app.

How does SSO with my online integration work?

When a company signs up to your service through TutorCruncher, we send a request to you containing details about the company along with a new Fernet key that users within that company will use to sign into your app. This request is signed with a shared secret key we have with you.

An example of this request looks like this:

import os
import hashlib
import hmac
import json
import requests

from cryptography.fernet import Fernet


def send_company_signup_webhook(company, admin):
    """
    This is the request we will do to your 'Create company' endpoint
    :param company: The company signing up to your app
    :param admin: The admin for that company signing up
    """
    secret_key = os.getenv('shared_secret_key')  # This is the secret key shared between our 2 platforms.
    company_signup_url = os.getenv('company_signup_url') # The URL to send the company creation request to.

    company_fernet_key = Fernet.generate_key()  # This is the new Fernet Key we will create tokens from for SSO.
    data = {
        'company_id': company.id,
        'fernet_key': company_fernet_key,
        'admin_email': admin.email,
        'admin_name': admin.name,
        'company_name': company.name,
    }

    payload = json.dumps(data)
    sig = hmac.new(secret_key, payload.encode(), hashlib.sha256).hexdigest()
    headers = {'Webhook-Signature': sig, 'User-Agent': 'TutorCruncher', 'Content-Type': 'application/json'}

    r = requests.post(company_signup_url, data=payload, headers=headers)
    assert r.status_code == 200
    Integration.objects.create(app_name='your_app_name', key=company_fernet_key)

You then save the company ID to your database with the company's Fernet key so you can use it later with SSO.

After an admin adds your app to TutorCruncher, they'll have an option in their menu to log into your app. When they click that link, we take data about that user and create an encrypted token from it. If the user is clicking the link from inside a lesson, then we'll add data about that lesson to it.

import json

from cryptography.fernet import Fernet

def redirect_user_via_sso(integration, user, lesson=None):
    """
    :param integration: The integration we created for your app with the key we sent you
    :param user: The user clicking the link
    :param lesson: The lesson the user is on. Sometimes user launches a session without being on lesson.
    """
    data = {
        'rt': user.role_type,
        'nm': user.name,
        'id': user.id,
        'role_id': user.role.id,
        'ts': unix_timestamp_now(),
        'tz': user.get_timezone(),
        'br_id': user.branch_id,
        'br_nm': user.branch.name,
        'e': user.email,
    }
    if lesson:
        data.update(
            apt_id=lesson.id,
            apt_nm=curtail(lesson.topic),
            apt_st=to_unix_timestamp(lesson.start),
            apt_fn=to_unix_timestamp(lesson.finish),
        )
    token = Fernet(integration.key).encrypt(json.dumps(data).encode())
    return HttpResponseRedirect('{}?company_id={}&token={}'.format(
        integration.your_app_url,
        user.branch.company_id,
        token.decode())
    )

That's it! If you think you're ready to add your app to TutorCruncher just get in touch with devteam@tutorcruncher.com. Happy Coding!