About Petrock

Petrock is an authentication service that allows for MIT students to quickly add Touchstone authentication to their website. It is a student-made replacement for the now decommissioned MIT OIDC Pilot service (oidc.mit.edu).

Who is this service for?

MIT students creating web services for the MIT community
MIT clubs and organizations that want to add Touchstone authentication to their backend services

How does Petrock work?

Petrock is an instance of SATOSA by IdentityPython, a proxy that translates from SAML to OpenID Connect, among other protocols.

Why not use other MIT auth services?

Currently if you are a student developer creating individual web applications at MIT, the main way of getting user authentication for your website is through Shibboleth.

Most official MIT applications do use Shibboleth, but the set up guide for Shibboleth can be cumbersome and confusing if you are not familiar with the protocol. Also, the simplest way to set it up requires using Apache or building a custom version of Nginx from source, which may not always be preferable.

As another note, Touchstone is SAML under the hood, so any SAML client also works (not just Shibboleth), but SAML is very enterprise-y and has a lot of options that are beyond our comprehension. If you are writing an application from scratch that does not already easily support SAML, it can take a lot of painful back and forth to get it right. You probably don't want to be thinking about urn:oid:2.16.840.1.113730.3.1.241 when all you want to type is name.

So why OIDC?

Petrock models itself after oidc.mit.edu, which was an another MIT authentication service that uses the OpenID Connect protocol. OIDC is an open-source protocol that has widespread library support across many different programming languages. In addition, we believe it's easier to use and understand for student web developers. OIDC is also used in other authentication services like Shimmer (operated by CSAIL) that powers most of Course 6 websites and CSAIL services.

In addition, the Petrock project will be continually supported by SIPB, which is a student club responsible for other dependable services like: Hydrant, Courseroad, and Scripts.

I'm currently using `oidc.mit.edu`, how do I switch to Petrock?

Depending on what library/custom code you're using to support the OpenID Connect protocol, the main changes would be with editing your configuration to use Petrock endpoints instead of the old OIDC Pilot endpoints.

First, you'll need to provide the following information through our signup form:

Name of your web service
The purpose of your web service
A primary contact email
List of redirect URL(s) that can receive successful authentication response
- These should be the server endpoint(s) that is able to receive the authentication code after a successful user login
- We allow for multiple in case you have multiple servers (e.g., a testing + production) running the same service

The link to the form is: https://forms.gle/VirozJ8tRZK2hBax9

We'll then email you back with:

a client_id (safe to store in Github + publicly)
a client_secret (MUST BE KEPT SECRET)

Example

For example, given a service like SIPB DormDigest, we would have:

Name: DormDigest
Purpose: DormDigest automatically parses dormspam emails by type onto a web calendar, and we require authentication to login to protect the privacy of students emails.
Contact email: sipb-dormdigest-admin@mit.edu
Redirect URL(s):
- https://dormdigest.mit.edu/oidc-response
- https://dormdigest.xvm.mit.edu/oidc-response

Editing your configuration

With this information, you should edit your configuration such that:

client_id and client_secret: Replace with corresponding values we gave you
OIDC Authority URI: Replace https://oidc.mit.edu with https://petrock.mit.edu
Token Issuer: Replace https://oidc.mit.edu/ with https://petrock.mit.edu (no trailing slash)
Auth endpoint: Replace /authorize with /touchstone/oidc/authorization
Token endpoint: Replace /token wit /oidc/token
User Info endpoint: Replace /userinfo with /oidc/userinfo
Public key endpoint: Replace /jwk with /oidc/jwks
OIDC scopes
- Make sure it includes openid, email, and profile
- Ex. openid email profile

For step 4-7, you might need to specify the full URL, so for example you might be going from:

https://oidc.mit.edu/authorize
to https://petrock.mit.edu/touchstone/oidc/authorization

Once you restart your services with these changes, you should now be able to authenticate using Petrock.

I'm creating a new web application, how can I start?

Depending on your choice of language/web frameworks, there are a number of official and non-official OIDC libraries that you can use. Because OIDC is built on top of OAuth 2.0 protocol, for Next.js projects, you can even try to use the built-in OAuth support and add some custom handler functions to make it work with OpenID Connect.

For Petrock, we provide a web application template (found at auth_client) that implements support for OIDC protocol, and is comprised of two components:

A React.js frontend (running Node 16)
A Express.js backend

An example website running this web template can be found at: https://unofficial-oidc-client.xvm.mit.edu/

This web application template was designed with security and flexibility in mind (see the Security Design section). It is intended to be used by MIT students who wants to quickly spin up a web project that has built-in support for MIT Touchstone authentication via Petrock. It has minimal design choices baked-in as to allow students ease-of-use in adapting the template to their needs.

The template README also provides guidance + information on important aspects of building a secure web application (such as session management, certificates, hosting) that will be important to all web projects that want to support OIDC authentication.

For example, a version of this template is used in the SIPB DormDigest project (Source Code).

What information do I get about a user?

Given a user's access token (see this guide if you're unsure what that is), you can query Petrock's user info endpoint at https://petrock.mit.edu/oidc/userinfo. The access token will need to be provided in the HTTP Authorization header using the Bearer scheme (see).

Assuming you set your OIDC scopes as described above (with openid, email, and profile), you will be able to get back a JSON with the following keys:

sub - Unique user ID (equivalent to email)
- Note: This behavior is different from oidc.mit.edu, which used to return a hash that is unique to each person.
email - Student email
affiliation - MIT primary affiliation (ex. student,faculty,staff,affiliate)
name - Full name
given_name - First name
family_name - Surname or family name

For example, it may look something like this:

      {
         "sub": "ben@mit.edu",
         "email": "ben@mit.edu",
         "affiliation": "student",
         "name": "Ben Bunsen Bitdiddle",
         "given_name": "Ben",
         "family_name": "Bitdiddle"
      }

(Jump back to top)