Center for Open Science - CAS Overlay

Master Build Status:

Develop Build Status:

Versioning Scheme:

About

"Center for Open Science - CAS Overlay" is often referred to as CAS or OSF CAS. It is the centralized authentication and authorization system for the OSF and its services such as Preprints, Registries and SHARE.

Features

• OSF Username and Password Login
• OSF Username and Verification Key Login
• OSF Two-Factor Authentication
• OSF Authentication Delegation
  • ORCiD Login with OAuth
  • Institution Login with CAS
  • Institution Login with SAML
• OSF OAuth Provider
• Login Request Throttling

References

The implementation of OSF CAS is based on Yale/Jasig/Apereo CAS 4.1.x using CAS Overlay Template 4.1.x. Official docs from Apereo CAS can be found here. Learn more about the CAS protocol here or refer to the full specification.

Running OSF CAS for Development

Java 8

• Install Java Development Kit 8 (JDK 1.8) either from Oracle or OpenJDK. For macOS, it is recommended to use THE package manager Homebrew with command brew cask install adoptopenjdk8.

JCE with Unlimited Strength

• Download and install Unlimited Strength Jurisdiction Policy Files for Java Cryptography Extension (JCE). Here is the version for JDK 1.8. Unpack the ZIP file and follow the README.txt in the folder to back up existing cryptography policy files and install the new stronger ones.

Apache Maven

• See here for how to install maven and here for IDE integrations.

A Working OSF

• CAS requires a working OSF (more specifically, its database server) running locally. See Running the OSF For Development for how to run OSF locally with docker-compose.

Database

• CAS requires Postgres as its backend database. Use a port other than 5432 since this default one has already been taken by OSF. Update database.url, database.user and database.password in the cas.properties.

• CAS also requires read-only access to OSF's database. No extra Postgres setup or CAS configuration is needed when running OSF locally with docker-compose as mentioned above. The default one works as it is.

Run CAS

• Refer to the Dockerfile in the repository for how to run CAS with the Jetty Maven Plugin. Only the app and dev stages are relevant in this case since the dist one is used for production and staging servers. Take a look at the .travis.yml on how to run unit tests. You can skip package and go for clean and install directly; in addition, toggle the profile nocheck to turn unit tests on and off.

• TL;DR, here are the commands that you need:

  # clean and install w/ test
  mvn clean install -P !nocheck
  # clean and install w/o test
  mvn clean install -P nocheck
  # start jetty
  mvn -pl cas-server-webapp/ jetty:run
  

• With default settings, CAS runs on port 8080 at IP address 192.168.168.167 locally. Change server.name here in cas.properties if you want a different IP or port.

A Few Extra Notes

• To use the "Sign in with ORCiD" feature, create an application at ORCiD Developer Tools with Redirect URI set as http://192.168.168.167:8080/login. Alternatively, COS developers can use the credentials provided in https://osf.io/m2hig/wiki/home/. Update oauth.orcid.client.id and oauth.orcid.client.secret accordingly here in the cas.properties. ORCiD login will not work if CAS is run on a different server.name without updating 1) OSF docker-compose settings and 2) the Redirect URI of the ORCiD developer application.

• The "Sign in through institution" feature is not available for local development. It requires a Shibboleth server sitting in front of CAS handling both SAML 2.0 authentication and TLS.

• Installing java8 with Homebrew on macOS (i.e. brew cask install java8) no longer works due to Oracle's new license for Java SE. Here is the discussion. Instead, use the alternative AdoptOpenJDK and here is the Tap.

• We recommend using an IDE (e.g. IntelliJ IDEA, Eclipse IDE, etc.) for local development.