Identity Verification and Account Linking, Campus-Hosted (JWT Integration)

Overview

Account linking is usually performed when a user authenticates into each of their accounts to prove ownership (and to release attributes to the linking service). In some cases a user may not have (or remember they have) an account at an institution and need to go through an identity verification process to release the institutional attributes to link. This document describes how such a campus-hosted ID verification service integrates with the Cirrus account linking proxy. (Note: Cirrus Identity can host the ID Verify application if the campus provides an API)

JWTs

A JWT (pronounced jot) is a secure way to construct and exchange claims/attributes between services and is what Cirrus uses for letting a campus-hosted ID Verification service securely send a user's identifier to the account linking proxy. A JWT specification is part of OpenID Connect and OAuth and there is wide support across programming languages. A JWT contains a JSON structure, and the ID verification service will add any attributes to the JSON and then sign it.

You can learn more about JWTs at https://jwt.io/

Basic Flow

Once the campus ID verification service has verified a user's identity and determined their attributes/identifiers it will construct a JWT. The JWT will contains the identifiers/attributes to send to Cirrus and some metadata. The campus' ID verify service will then sign the JWT with its private key and redirect the user to the Cirrus Identity account linking proxy. The redirect will contain the JWT in a query parameter called idVerifyToken. The Cirrus account linking proxy will then validate the JWT and extract the user's identifiers and link those to their social account.

The JWT must be signed using asymmetric keys and the RS256 algorithm.

The user should be sent to https://TENANT_ID.proxy.cirrusidentity.com/module.php/cirrusaccountlink/link.php?idVerifyToken=JWT

JWT Claims/Attributes

These attributes (or claims in JWT parlance) are set regardless of the number identifiers sent

• aud: Audience is a claim that lets Cirrus know this JWT is intended for proxy. The value for aud is customer specific, and will vary between production and UAT/testing. 
• iat: seconds since epoch. This is the time when the token was issued.
• jti: a guid for the token.
• kid: an id name for the key used in signing (this goes it the jwt header). This allows multiple keys to be used and for keys to be rotated without an interruption of service.
• exp: An expiration time (seconds since epoch) for the token. Cirrus will reject JWTs that have expired.

Single Attribute

For an ID verification service that has a single identifier, that identifier should be placed into the sub  claim.

Multiple Attributes

For an ID verification service that wants to return multiple identifiers:

• The primary ID should be placed in the sub claim.
• All attributes (including the primary ID) should be placed into an cirrusAttributes claim.

Example

Header

 Payload

The Cirrus Identity account linking proxy will then be able to assert these attributes during authentication.

JWT Signing

The ID Verification Service should sign the JWT using the RS256 (RSA using SHA-256 hash) algorithm. 

Key Generation

Your ID Verification Service will need to generate  asymmetric keys and share the public key with Cirrus.

openssl genrsa -out key1.pem 2048
openssl rsa -in key1.pem -outform PEM -pubout -out key1.crt

Picking a Key Id

The Key Id (kid) is an identifier that your ID Verification service puts into the header to help Cirrus identify the key used to sign the JWT. Customers generally pick names like 'prod1', 'prod2' or 'dev1' to distinguish between their keys and environments.

Validation

The account linking proxy validates the JWT in the following way:

• Ensure that the audience matches the the audience for a customer's instance of the account linking proxy
• Ensure that the JWT hasn't expired and wasn't issued in the future.
• Ensure that the token was signed with the RS256 algorithm
• Ensure that the customer has a public key with the provided key id.
• Ensure that the JWT can be verified with that public key.