@crownanalytica/sso-middleware v1.0.0
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 pbasiga@crownci.com 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 pbasiga@crownci.com 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 git@bitbucket.org: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.
3 years ago