CAS authentication client and server for the Apostrophe CMS
This module allows an Apostrophe site to act as a CAS client or server.
Client support means that you can send users to a third party site that supports CAS (Centralized Authentication Service) to log in, and then they will be logged into your Apostrophe site. This is known as "single sign-on."
Server support means that other sites can use your site as a CAS server. In this case your site is the authoritative one.
npm install --save apostrophe-cas
Add the module to the
modules section of your
apostrophe-cas:client:protocol: 'https'host: 'cas.myschool.edu'
Next, make sure you shut off the regular authentication system. This is a top-level option in
app.js (that is, it's not inside "modules," it's at the same level as "modules"):
Now your users will be redirected to the CAS login page at
https://cas.myschool.edu/cas/login when they try to log in. After login they are directed back. Logout is also redirected.
In some cases, any person who can log into the CAS server should also be a valid account on your site.
Here's how to automatically create new people on the fly:
apostrophe-cas:client:protocol: 'https'host: 'cas.myschool.edu'createPerson: true
By default, users created on the fly are not added to any group. You can change that, and also set default permissions for the group if it does not already exist:
apostrophe-cas:client:protocol: 'https'host: 'cas.myschool.edu'createPerson:group:name: 'guests'permissions: 'guest'
You can use the
admin option to set a username that always receives full admin permissions upon logging in. This is convenient for bootstrapping a new site that uses CAS login. First use the
admin option to give your own CAS account full privileges, then log in and add groups and permissions for other CAS users.
apostrophe-cas:client:protocol: 'https'host: 'cas.myschool.edu'createPerson: trueadmin: 'jillrocks'
Since CAS servers frequently don't provide any more information than a username, the default behavior is to set the user's first and last name based on their username, which isn't very satisfying.
As an alternative you can set the
before option to a callback function that obtains additional information and populates the
person object more completely, either from the
cas object in the session or by some other means, such as an LDAP call or database call:
apostrophe-cas:client:protocol: 'https'host: 'cas.myschool.edu'createPerson:// What did the cas server give us? Maybe extra// attributes are being passed and we can just// set person.firstName and person.lastName etc.console.logcas;// No good? Try querying your LDAP or database server// with person.username// ...All done, invoke the callbackreturn callbacknull;
There is also an
after option, which takes the same arguments and is invoked after the person exists in the database.
If you prefer you can subclass the
apostrophe-cas module and override the
afterCreatePerson methods in your
index.js file. You'll need to follow the same pattern used when subclassing
apostrophe-snippets. If this is all new to you, just use the options.
client object above you may specify any of the fields below if needed. The defaults are shown. This is taken from the documentation of the connect-cas module, on which the client support in
apostrophe-cas is built.
protocol: 'https'host: undefinedhostname: undefined // ex. googleport: 443paths:validate: '/cas/validate' // not implementedserviceValidate: '/cas/serviceValidate' // This is the one we useproxyValidate: '/cas/proxyValidate' // Not tested with Apostropheproxy: '/cas/proxy' // Not tested with Apostrophelogin: '/cas/login' // The user-visible login URL on the CAS serverlogout: '/cas/logout' // Ditto for logout
Occasionally you may need to temporarily disable login completely. To do so, set the
disabled option to
This is useful during database migrations, content freezes and the like. The
disabled.html page template will be rendered.
Configuring Apostrophe as a CAS server allows other sites to send users to Apostrophe to log in, and then redirects those users back to the other site, allowing that site to verify their username.
Here's the configuration to allow two sites to do this:
The CAS login, logout and serviceValidate URLs will be
/cas/serviceValidate. This is not currently configurable.
You may allow users to to come from an "http:" URL, but you really shouldn't, except for testing.
https is necessary for secure use of CAS.
The CAS server does not check that incoming requests to the
/cas/* routes are secured with https. Since Apostrophe is usually behind a reverse proxy like nginx, this isn't possible anyway. It is your responsibility to ensure that any non-https requests to
/cas/* URLs are rejected by your proxy server in production.