SSO Middleware

This middleware integrates the application to synchronize login sessions of users with the SSO Auth Server. All auth related tasks are forwarded to the SSO Auth Server via the middleware. The user profile of currently logged in user is added into the context of each request res.locals via the middleware. The middleware also establishes a local session.

Pre-requisites

• You must have been given read access to the sso-middleware repository. Please email [email protected] for access.
• You must have a valid clientId from registering your application with the SSO Server.
• You must have express-session installed into your application and configured: https://www.npmjs.com/package/express-session
• For development / testing purposes, you need to have registered an account with the SSO Server: http://54.219.190.15
• Have your account be granted access to the registered application. Please email [email protected] to do this.
• You need to server your frontend from your backend.

Warning
The cookie name for user session with sso server is crownanalytica.ssoSession. Be sure when configuring your session that your cookie name does not conflict if your application will be hosted within the same domain as the SSO Server.

Installation

npm install -g install-local

install-local is a utility for installing npm packages locally. It extends from base npm link, adding ability to work with typescript projects. You may install it globally or just for your application as a dev dependancy.

# Clone Middleware Repository
git clone [email protected]:crownanalytica/sso-middleware.git
# Change Directory into your Project
cd <project-dir>

#Install middleware into your project
install-local <sso-middleware-directory>

Note
For the moment, there is no private organization set up in npm to host modules like these.
Incurring the monthly payment for a single module is not currently worth it.
I will also not be publishing public packages to npm as this work is done for the project under Crown Consulting Inc.
Therefore, until a private npm organization is created, all custom npm packages to be used be future node applicatons will be installed following this format.

Usage

const ssoMiddleware = require('@crown-analytica/sso-middleware');
// ES import
import ssoMiddleware from '@crown-analytica/sso-middleware';

var app = express();
const config = {
    clientId: '<client-id'>,
    authUrl:'http://<auth-url>',
    logoutPath:'/auth/logout',
    onAuthenticationVerified: (req,res,profile) => {
        console.log("Profile Loaded into context", profile);
    };
}
app.use(ssoMiddleware(config));

ssoMiddleware(config)

Initializes SSO Middleware with the given config

Config

sso-middleware accepts these properties in the config object.

clientId

clientId provided by the SSO Auth Server once integration has been approved by the connected auth server. Note Public Access to SSO Auth Server with custom configuration is WIP. Link to that repo will be linked here.

authUrl

authUrl is the url the middleware will be sending requests to. By default it is http://localhost:3001 which is the default port that the SSO Auth Server will listen on.

onAuthenticationVerified

onAuthenticationVerified is a function that is called once a user has been verified as logged in by the SSO Auth Server on each request. The function is given req, res, profile as arguments.

req Express request object.

res Express response object.

profile Profile that is stored in the context of the request once login has been verified. Note The same value is stored in res.locals by this point.

{
    // User Id in SSO Database
    ssoUserId:number,
    // Username in SSO Database (hashed)
    userName: string;
    // Email of user.
    email: string;
    // Company user is apart of.
    company: string;
    // Role of user in respective application.
    role: string;
    // AWS Credentials of user.
    iam_access_key: string;
    iam_secret_key: string;
    verified: boolean;
}

logoutPath

By default, logoutPath is /auth/logout. Application may make a request to respective backend server at logoutPath This will send logout request to SSO Server to terminate the user's session. This will end the user's session on all applications integrated with SSO Server. This will then return a response with loginUrl provided that your frontend can update the current page to.

port

By default, the host name automatically added in headers during requests will suffice as normally only port 80 is expected to be exposed. However, this will make sure all redirects that are configured during logout calls and sessions ending will work in the case that your application has exposed another port.

Testing the Middleware

No Access Without Authentication

Open your browser and go to the url of your application. If you have not logged into the SSO Server before, it will redirect you to the login page.

After you've successfully logged in, you will be redirected to your application.

Subsequent requests to your application will verify that you are logged in and go directly to your application without redirecting.

User Profile in Request Context

You may test that the user that is logged in is in the request context by logging res.locals.user.
Upon logging, you will see profile object as described above.

User Global Session Information in Session

You may view the session your application is keeping track of by logging req.session.user. Upon logging you should see sessionId, ssoToken.

Testing Logout

Logout endpoint is available for all applications. You may add a logout button on your respective UI. Upon making the request, the response should return loginUrl with redirect set back to your application.

Update the user's page to that loginUrl in reponse via

location.href = response.data.loginUrl;

If you login at that point, you will be redirected back to your application.

After logging out, if you try to land directly on the application again, you will be redirected to the login page.