OSF CAS by Center for Open Science

Master Build Status: TBI

Develop Build Status: TBI

Versioning Scheme:

License:

About

OSF CAS is the centralized authentication and authorization service for the OSF and its services such as OSF Preprints and OSF Registries.

Features

• OSF username and password login
• OSF username and verification key login
• OSF two-factor authentication
• Delegated authentication
  • OAuth 2.0 client: supports ORCiD login
  • CAS client: supports institution SSO using the CAS protocol
  • SAML service provider: supports institution SSO using the SAML protocol
• OAuth 2.0 authorization server for OSF
• Authentication failure throttling

Implementations

The implementation of OSF CAS is based on Apereo CAS 6.2.8 via CAS Overlay Template 6.2.x. Refer to CAS Documentation 6.2.x for more details.

Legacy Implementations

A legacy version can be found at CAS Overlay, which was built on Jasig CAS 4.1.x via CAS Overlay Template 4.1.x.

Versions

• OSF CAS 21.2.x
• Apereo CAS 6.2.8
• PostgreSQL 9.6
• JDK 11

Configure, Build and Run OSF CAS

It is recommended to use the provided scripts to build and run CAS. Refer to Apereo README.md for more options.

Use cas.properties and Dockerfile to configure staging and production servers. Use cas-local.properties and Dockerfile-local for local development. To accelerate developing OSF CAS, use the reload script to rebuild, reconfigure and restart the running container.

OSF

OSF CAS requires a working OSF running locally. Refer to OSF README-docker-compose.md for how to set up and run OSF with docker-compose. Must disable fakeCAS to free port 8080 for CAS to use.

OSF DB

More specifically, CAS requires a running OSF PostgreSQL database to handle authentication for OSF. Use the authentication handler's JPA settings for OsfPostgresAuthenticationHandler to connect to and access OSF DB.

Here is an example for local development. Use 192.168.168.167 to access host outside the docker container. Set readOnly=true since CAS only needs read-only access (Principle of Least Privilege).

# In `cas.properties` or `cas-local.properties`

cas.authn.osf-postgres.jpa.user=postgres
cas.authn.osf-postgres.jpa.password=
cas.authn.osf-postgres.jpa.driver-class=org.postgresql.Driver
cas.authn.osf-postgres.jpa.url=jdbc:postgresql://192.168.168.167:5432/osf?targetServerType=master&readOnly=true
cas.authn.osf-postgres.jpa.dialect=io.cos.cas.osf.hibernate.dialect.OsfPostgresDialect

CAS DB

The implementation of OSF CAS uses the JPA Ticket Registry for durable ticket storage and thus requires a relational database. Set up a PostgreSQL@9.6 server and review JPA Ticket Registry settings. In most cases, only Database connections need to be updated. Other JDBC and JPA settings can be adjusted if necessary.

Here is an example for local development. Use 192.168.168.167 to access host outside the docker container. Use the port 54321 since the default 5432 one has been used by OSF DB. Update pg_hba.conf to grant proper access permission depending on the setup.

# In `cas.properties` or `cas-local.properties`

cas.ticket.registry.jpa.user=longzechen
cas.ticket.registry.jpa.password=
cas.ticket.registry.jpa.driver-class=org.postgresql.Driver
cas.ticket.registry.jpa.url=jdbc:postgresql://192.168.168.167:54321/osf-cas?targetServerType=master
cas.ticket.registry.jpa.dialect=org.hibernate.dialect.PostgreSQL95Dialect

# In `pg_hba.conf`

# TYPE  DATABASE        USER            ADDRESS                 METHOD
host    osf-cas         longzechen      192.168.168.167/24      trust

Signing and Encryption Keys

CAS Server

• Refer to signing and encryption 1 in cas.properties for signing and encrypting client sessions and ticket granting cookies.

OAuth Server

• Refer to signing and encryption 2 in cas.properties for signing and encrypting OAuth 2.0 registered services.

• You can optionally enable OAuth JWT access tokens, which requires signing and encryption 3 to be configured.

Auto-generate Key Pairs

Set empty values to the above keys and CAS will generate the key pairs automatically. The keys will be re-generated once server restarts. Follow the server warning logs for further actions.

Authentication Delegation

ORCiD Login

To enable ORCiD login, update cas.authn.pac4j.orcid.id and cas.authn.pac4j.orcid.secret here in delegation settings accordingly.

For local development, set up a developer app at ORCiD with http://localhost:8080/login and http://192.168.168.167:8080/login as redirect URIs.

Institution Login

SAML / Shibboleth

Details coming soon ...

CAS / Pac4j

Details coming soon ...

fakeCAS Login for institution osftype0 (Local Development Only)

With OSF CAS running locally as the authentication server for OSF, the previously disabled fakeCAS can be re-configured to serve as an identity provider. Simply update fakecas in OSF's docker-compose.yaml to listen on port 8081.

fakecas:
  image: quay.io/centerforopenscience/fakecas:master
  command: fakecas -host=0.0.0.0:8081 -osfhost=localhost:5000 -dbaddress=postgres://postgres@postgres:5432/osf?sslmode=disable
  restart: unless-stopped
  ports:
    - 8081:8081
  depends_on:
    - postgres
  stdin_open: true

Related cas.propeties settings can be found here.

# In `cas-local.properties`

cas.authn.osf-postgres.institution-clients[2]=${cas.authn.pac4j.cas[2].client-name}

cas.authn.pac4j.cas[1].login-url=http://192.168.168.167:8081/login
cas.authn.pac4j.cas[1].client-name=osftype0
cas.authn.pac4j.cas[1].protocol=CAS30
cas.authn.pac4j.cas[1].callback-url-type=QUERY_PARAMETER

OAuth 2.0 Server

Details coming soon ...