Overview

The easier you can make it for your parents to sign up for PushCoin the better user experience and quicker platform adoption. This in turn helps your school staff as PushCoin eliminates manual labor in funding lunch accounts and taking payments from parents for mandatory school fees.

Here we describe a feature of PushCoin that signs parents up with PushCoin by simply clicking a link within your “Home Access”-like website. This is often referred to as Single Sign On or SSO.

To illustrate how this works at a high level, consider a parent who is logged in a school website, for example to check on grades. A conveniently located link is visible to the parent. The link, if clicked, takes the parent to PushCoin. The link includes encoded information permitting PushCoin to:

  • Create a new PushCoin account for the parent and link all dependent students,
  • Or, if a parent already has a PushCoin account, sign the parent in.

The parent link cannot be a trivial https://pushcoin.com/ since that would not convey any information about the parent, dependent students, nor the district its coming from. In order for the link to function as automatic login or sign-up mechanism, it needs to be dynamically generated by your website and include the following information:

  • Your district account identifier assigned when the district joined the PushCoin platform.
    The district account identifier (10 characters) is visible at the top of the website, when you login to PushCoin as a school administrator.
  • A parent’s unique identifier in your system, such as a database key or a hash of the database key.
    It’s important that the provided parent identifier is stable, meaning it does not change even if a parent updates her email or last name on your record.
  • Parent full name and current email address.
  • A list of student IDs the parent has access to.

Finally, the information listed above must be cryptographically signed by the school website at the time of generating the link using a key that is trusted by PushCoin. Later we show how to generate a key-pair and share the public-key with PushCoin.

Generating the sign up link

PushCoin leverages the open internet standard JSON Web Signature (JWS) for encoding information that goes into the link. JWS ensures that the information in the link arrives unchanged and from a trusted source, like your school district.

Step 1. Create a JSON record

JSON is one of the more popular formats for encoding information exchanged over the internet. Below is a sample JSON message that includes all the fields to be added to the parent sign up link:

{
  "iss":"ABCXYZ1234",
  "exp":1300819380,
  "pushcoin/msg": {
    "emid":"12312A1231",
    "fn":"John",
    "ln":"Smith",
    "email":"jsmith@example.com",
    "dependants":["student-id-A","student-id-B"],
  }
}

The JWS specification refers to fields in the JSON message as claims. Let’s look at each claim:

  • “iss”: issuer claim, is the district account identifier provided by PushCoin.
  • “exp”: expiration time claim, identifies the expiration time after which the message must not be accepted for processing. The processing of the exp claim requires that the current date/time must be before the expiration date/time listed in the exp claim. Its value must be a number of seconds since 1970-01-01T00:00:00Z UTC, known as “Seconds Since the Epoch”. The recommended expiration time is “now plus 1 hour”.
  • pushcoin/msg”: message claim, wraps the parent information record.
  • “emid”: parent unique identifier claim, a unique key assigned by your school database system for the parent record.
  • “fn”: first name claim, parent’s first name.
  • “ln”: last name claim, parent’s last name.
  • “email”: email claim, parent’s current email address.
  • “dependants”: a list of one or more student IDs that the parent must be provided access to.

Step 2. Sign the JSON record and include it in a link

A JSON message like above needs to be cryptographically signed and inserted into a parent link on your website. The URL has this format:

https://api.pushcoin.com/api/v1/guest/merchant-auth?jwt=<signed message>

The JWT.IO site lists helpful libraries that can be used to take a JSON message, sign it and serialize so it’s suitable for URL link. Below, we demonstrate this with Python JOSE library, but it can analogously be done in PHP, Java or .NET using one of the other libraries.

#!/usr/bin/env python
import jose
from time import time

# example JOSN message with claims about the parent
claims = {
  "iss":"AATHERLY43",
  "exp": int(time()) + 3600,
  "pushcoin/msg": {
    "emid":"12312A1231",
    "fn":"John",
    "ln":"Smith",
    "email":"jsmith@example.com",
    "dependants":["1102076","2202076"],
  }
}

# read private RSA key stored in PEM format
priv_key = open('sender_key.pem').read()

# wrap the key in JWK as required by the 'sign' call below
priv_jwk = {'k': priv_key}

# sign the message
jws_out = jose.sign(claims, priv_jwk, alg='RS256')

# produce the final URL link
jwt_out = jose.serialize_compact(jws_out)
print 'https://api.pushcoin.com/api/v1/guest/merchant-auth?jwt='+jwt_out

Crypto key for signing and verification

In steps above, you needed a key to sign the JSON message. Below we show one way to generate the RSA key-pair. You will use the private key for signing and only share the public key with PushCoin.

# Generate a 2048-bit RSA private key for signing. Do not share with anybody.
$ openssl genrsa -out private_key.pem 2048

# Extract public key and share with PushCoin
$ openssl rsa -in private_key.pem -pubout -outform PEM -out public_key.pem

Share the public key with PushCoin by going to your account settings, Public Key tab. Copy and paste the entire contents of public_key.pem file and press Submit.

Public Key - Google Chrome_091 (copy 1)

That’s it. You are ready to create PushCoin sign up links for your parents.