Single Sign-on with Sunbird

Trusted, Passwordless authentication with Sunbird

Sunbird allows users on integrated systems to seamlessly navigate to Sunbird. By design, we keep the systems loosely-coupled, and achieve the seamless navigation by sharing trusted login status. This keeps the technical complexity for integrating systems simple and the systems do not need to change their own sign-on protocols.

The philosophy is built around a premise of trust between Sunbird and the integrated systems. When an authenticated user on an integrated system navigates to Sunbird, the integrated system redirects the browser and sends the details of the user to Sunbird. This data is signed using a private key of the sender, to allow Sunbird to trust the incoming data and allow the user to sign in. This ensures that for integrating systems, the change is only how they redirect users to Sunbird, and not on their internal authentication implementation.

This document describes a protocol to create new users in the Sunbird and to log them in via the signed token.

Protocol

The authentication protocol provides:

1. Registration of trusted tenant systems

2. A secure API endpoint to auto-login a user into Sunbird

The Integrating Tenant System (IS) can register itself as a trusted partner with Sunbird system using the Registration process. Later the IS can direct a User to login to Sunbird and create a new session. To authenticate the User, the IS must send a signed token which contains the user identity and profile information.

Registration

Single sign-on will only be available to registered Sunbird clients -- a new client will need to register before being able to access this endpoint. In order to register a new client which will authenticate users through a link, the client will need to provide the following information:

● Identifier for partner system (iss), example: apekx

● RSA public key

To create a pair of public/private keys, the following command can be used:

openssl genrsa -out private.pem 2048

This private key must be kept secret. To generate a public key corresponding to the private key, execute:

openssl rsa -in private.pem -outform PEM -pubout -out public.pem

When the above commands are run, the public key will be written in public.pem, while the private key will be written in private.pem. The private key should be kept with the client and never shared. The public key should be given to the Sunbird integration team to verify the client’s signature.

Auto-login

The Integrating Tenant System (IS) must redirect users to Sunbird system by sending a signed JWT token which will be verified by Sunbird system against the registered public key and allows users into the system.

JWT Tokens

We use JWT (pronounced “jot”) in our protocol to generate signed tokens which can be verified by the Receiving Party (RP). A JWT is a signed token containing claims from the sender to the recipient. Because the token is signed by the sender, the recipient can be sure that the token has not been tampered. For a more detailed overview of JWTs see: https://jwt.io/introduction/

JWTs are represented in JSON. To authenticate with Sunbird, a JWT provided to the auto-login endpoint must contain the following fields (also known as claims) in its payload. Unless noted, the fields are

• jti: a unique id of the token, can be any string generated by the sender which is unique

• iss: the issuer of the JWT, this must be the id of the registered client (see Registration below)

• sub: the subject of the token, this must be the userid of the person in the tenant system who will be logged in to Sunbird

• aud: the consumer of the token, for now this must be <base_url>

• iat: issued at, the time at which the token was generated (expressed as the number of seconds since epoch in GMT)

• nbf: not before, the earliest time when the token can be used (expressed as the number of seconds since epoch in GMT). The nbf time cannot be in the future

• exp: expires, the timestamp at which the token expires (expressed as the number of seconds since epoch in GMT). The exp time cannot be more than 600 seconds after the nbf time

• name: the name of the person whose userid is in sub

• state_id: orgId value of this tenant's rootOrg in Sunbird system

• school_id: the id of the sub-org to which the user belongs to, this must be the id of the sub-org in the tenant and the sub-org should be pre-created in Sunbird system with this id as the external id.

• redirect_uri: the url of the page where the user should be directed after login to Sunbird

The header of the JWT payload should have the following

{  
    "typ": "JWT",  
    "alg": "RS256" 
}  

Note:

In the JWT Payload header,

• If it has property “kid”, then it should be equivalent to the value of “iss”

• Remove “kid” from the header, otherwise.

In the JWT payload body:

• Shouldn't contain any extra key like roles or identifier in payload.

Example Payload

{  
    "jti": "261263cd-3a0e-4aee-8faf-6d9d9eb14bb1",  
    "iss": "slug/channel value from Sunbird",  
    "sub": "user_external_id",  
    "aud": "<base_url>",  
    "iat": 1498556656, 
    "nbf": 1498556656,  
    "exp": 1498560256,  
    "name": "Some User",  
    "state_id": "slug/channel value from Sunbird",  
    "school_id": "suborg_external_id",  
    "redirect_uri": "<base_url>/resources"  
}    

Signature

The payload described above must be signed before sending it to the authentication endpoint. The JWT specification permits signing via HMAC, RSA or ECDSA algorithms. For the purpose of this authentication end-point, the only permitted algorithm will be RSA signing via a private key. The corresponding public key will need to be provided during registration of the client. (for an example of creating a RSA-signed JWT in Java see: https://connect2id.com/products/nimbus-jose-jwt/examples/jwt-with-rsa-signature)

Auto-Login Users

To login a user, the client must provide a link (which makes a GET request) to the auto-login endpoint /v2/user/session/create?token=<jwt_token> with the JWT token in the query parameter of the request. Here’s an example:

<base_url>/v2/user/session/create?token=eyJhbGciOiJIUzI1NiIsInR5cCI6I kpXVCJ9.eyJzdWIiOiIxMjM0NTY3ODkwIiwibmFtZSI6IkpvaG4gRG9lIiwiYWRtaW4iO nRydWV9.TJVA95OrM7E2cBab30RMHrHDcEfxjoYZgeFONFh7HgQ

If a user already exists in the Sunbird system with the given external id and within the specified tenant, the user will be automatically logged in. If the user is not found, the user will be prompted to provide their phone number, which will be used to create the user account in the Sunbird system and then will be logged in.

Custom authentication page is to be developed by Integrating Tenant system which post authentication will redirect to Sunbird SSO URL with user jwt token. This page should be publicly available. The URL of this custom page will be configured at Sunbird for Tenant users (SSO users) to choose login via the Tenant system.

SSO Form configuration:

{ 
    "request": { 
      "type": "organization", 
      "subType": "organization", 
      "action": "sign-in", 
      "component": "*", 
      "framework": "*", 
      "rootOrgId": "*" 
    } 
} 

Note:

• Whitelist tenant slug/channel value in System settings to allow user updates from the tenant portal to flow through to Sunbird system.

• Ensure Tenant system server is in sync with current time to avoid user sso token issues

• Ensure Tenant portal page for SSO login is a secure (https://), public domain URL for configuring in Sunbird