Appcelerator SAML
Appcelerator SAML provides SAML 2.0 Autehntication for Appcelerator Arrow driven applications. The module is tested and works with the following IDps : Onelogin, Okta, Shibboleth, SimpleSAMLphp.
The module uses
- node passport
- node passport-saml
Authentication flow
- User visits the application
- The appcelerator-saml module checks if the user is logged in
- If not authenticated, the user is redirected to loginUrl, which you have to set (see point 3.1.).
- From the login route the user is redirected to the Identity Provider
- On success - the IDp returns the user to the callbaclUrl (see point 2.1. - configuration options)
- On error - user is redirected to the callbackUrl as well
- appcelerator-saml grabs the data sent from the IDp, writes it and makes it accessable trough the application request object (see point 3.4.)
1. Installation
- Install the module
``
npm install appcelerator-saml
`` - Add APIKeyAuthPlugin authentication type in the configuration file
./conf/default.js
APIKeyAuthType: 'plugin', // Modify the default 'APIKeyAuthType', and set it to 'plugin'
APIKeyAuthPlugin: 'appcelerator-saml'
Typescript files and the tsconfig.json file, are not included with the node module. If you want to use the typescript files, clone the repo.
2. Configuration
Copy conf/example.config.js
to you project's configuration folder, and rename the file to :
appc.saml.default.js
.
2.1. Configuration options
Set the privateCertLocation and certLocation if you are going to use private key and certificate, to authenticate against the server.
//Application login Url loginUrl: '/saml/login', //The url, where data sent from the IDp will be handled callbackUrl : '/saml/response/callback', //optional : Location of private key file privateCertLocation : './pk/login.axway.com.pem', //optional : Location of certificat file certLocation : './pk/login.axway.com.crt', // Routes that don't require authentication allowedPaths : ['/saml/response/callback', '/saml/login', '/successed'], //resultObject : is the Object structure, that you application requires //the object member values are the keys of the Object received from the IDp resultObject : { firstName : 'firstname', lastName : 'lastname', email : 'email', username : 'username', language : 'preferredLanguage' }, //passport-saml configuration object passport: { strategy: 'saml', saml: { //Should be an absolute path callbackUrl: 'https://localhost:8080/response/callback', entryPoint: 'https://idp.com/saml2/idp/SSOService.php', issuer: 'cloud:passport:saml', authnContext: 'http://schemas.microsoft.com/ws/2008/06/identity/authenticationmethod/windows', logoutCallbackUrl: 'https://localhost:8080/saml/logout' } }
- loginUrl - string - Path of the login Route
- callbackUrl - string - Where the user is redirected by the Identity Provider
- privateCertLocation - string - (optional) Location of private key file (relative to project root)
- certLocation - string - (optional) Location of certificat file (relative to project root)
- allowedPaths - Array - (optional) Array of Routes that don't require authentication
- passport - passport-saml configuration object
- resultObject - Object - Maps the response Object of the IDP to your desired structure. Where the parameter values are the parameter keys in the IDP's response. eg.: The IDP returns an object like thisAnd the object structure that you want is :So the resultObject should look like this :
For more infromation on the passport object, check the documentation of the passport-saml extension.
3. Usage
Once set, appcelerator-saml checks if current user is authenticated, for all routes (except for the loginUrl). You can add exceptions ( routes / endpoints which unauthorized users can visit ). Just add paths to the allowedPaths
Array. Don't forget to add loginUrl to it as well.
After you set "appc.saml.default.js"
file, and add APIKeyAuthPlugin to ./conf/default.js
, you have to set the application Routes, which are going to intercept the information sent by the IDp.
3.1. Setting a login route
This route should be the same, as the one you set as loginRoute in the module's configuration.
var Arrow = require;//Require the Modulevar SamlAuth = require;//Instantiate the SamlAuth and pass a server instance to the constructorvar auth = new SamlAuth; var LoginRoute = Arrow.Router.extend; module.exports = LoginRoute;
The auth.passport.authenticate
method redirects the user to the login page of the identity provider ( entryPoint ).
3.2. Setting a callback route
This route should match callbackUrl
parameter from the config. This is where appcelerator-saml, grabs the response from the IDP and persists the data. You can later on access the data, trough the application's Request object.
var Arrow = require;var SamlAuth = require;var auth = new SamlAuth; var CallbackRoute = Arrow.Router.extend; module.exports = CallbackRoute;
The successRedirect
property of auth.passport.authenticate, is the route where the user is going to be redirected on success.
3.3. Authenticating with && without a certificate
Set the privateCertLocation and certLocation (the location of the .pem and .crt files), to enable certificate authentication
3.4. Using the information sent from the server
The authentication information is accessable trough the Arrow's Request object
request.isAuthenticated() // returns wether the user is authenticated
request.user // returns user information object ( the one you set with resultObject )
Let's create a api endpoint that returns information on currently logged user.
var Arrow = require; var UserAPI = Arrow.API.extend; var user_data = {}; module.exports = UserAPI;
3.4. Setting up a logout route
var Arrow = require; var LogoutRoute = Arrow.Router.extend; module.exports = LogoutRoute;