RIT uses Shibboleth SSO for the authentication of all RIT users. Shibboleth communicates via SAML2. This application will be handling SAML via passport-saml.

SAML Authentication is enabled in staging and production builds. Development builds will use a simple webpage login. This development login is NOT secure and should not be used outside of local environments.

Sequence Diagram

Strategy

Tha Application uses passport-saml to send SAML2 requests and decrypt responses. passport-saml holds a "strategy" which contains various attributes that alter the SAML request. The strategy necessary for securely communicating with SHibboleth is as follows:

  const authStrategy = new SamlStrategy(
    {
      //The url to the application's metadata (`ISSUER` in .env)
      issuer: issuer,
      
      //The url where the SAML response will be sent and handled (`CALLBACK_URL` in .env)
      callbackUrl: callbackUrl,

      //The url where the SAML request will be sent (`ENTRY_POINT` in .env)
      entryPoint: entryPoint,

      //The format used to encrypt attributes in the request and response. (`ID_FORMAT` in .env)
      //For RIT Shibboleth it is "urn:oasis:names:tc:SAML:2.0:nameid-format:unspecified"
      identifierFormat: process.env.ID_FORMAT ?? "",

      //The private key for the x509 public key; used to decrypt the request. (`SSL_PVKEY` in .env)
      decryptionPvk: process.env.SSL_PVKEY ?? "",

      //The x509 public key from the IdP's metadata. (`IDP_PUBKEY` in .env)
      cert: process.env.IDP_PUBKEY ?? "",

      //Disable requesting of Authentication Context as it is not necessary for Shibboleth
      disableRequestedAuthnContext: true,

      //The encryption algorithm for sent signatures
      signatureAlgorithm: "sha256",

      //The decryption algorithm for received responses
      digestAlgorithm: "sha256",
  
      //Allow 180ms delay between response signing and retrieval
      acceptedClockSkewMs: 180, // "SAML assertion not yet valid" fix
    },
    (profile: any, done: any) => {
      // your body implementation on success, this is where we get attributes from the idp
      return done(null, profile);
    },
    (profile: any, done: any) => {
      // your body implementation on success, this is where we get attributes from the idp
      return done(null, profile);
    }
  );

Response Attributes

The SAML Response is automatically decrypted by passport-saml. Within the response, Shibboleth provides certain bits of user information as oid values:

• First Name (Preffered Name): urn:oid:2.5.4.42
• Last Name: urn:oid:2.5.4.4
• Username: urn:oid:0.9.2342.19200300.100.1.1
• University ID: urn:oid:1.3.6.1.4.1.4447.1.20