Enterprise Single Sign-On for All

Google Authenticator Authentication

Google Authenticator generates 2-step verification codes on your phone. With 2-step verification signing in will require a code generated by the Google Authenticator app in addition to primary authentication. Learn more about the topic here.

Note that the functionality presented here should also be compatible with the likes of LastPass Authenticator.

Configuration

Support is enabled by including the following module in the overlay:

1
2
3
4
5
<dependency>
     <groupId>org.apereo.cas</groupId>
     <artifactId>cas-server-support-gauth</artifactId>
     <version>${cas.version}</version>
</dependency>

To see the relevant list of CAS properties, please review this guide.

Token Repository

In order to prevent reuse of tokens issued, CAS will attempt to keep track of tokens that are successfully used to authenticate the user. The repository that holds registration records and tokens is periodically scanned and cleaned up so that expired and previously used tokens may be removed.

Registration

By default, an account registry implementation is included that collects user device registrations and saves them into memory. Issued tokens are also captured into a self-cleaning cache to prevent token reuse for a configurable period of time. This option should only be used for demo and testing purposes. Production deployments of this feature will require a separate implementation of the registry that is capable to register accounts into persistent storage.

JPA

Registration records and tokens may be kept inside a database instance via the following module:

1
2
3
4
5
<dependency>
     <groupId>org.apereo.cas</groupId>
     <artifactId>cas-server-support-gauth-jpa</artifactId>
     <version>${cas.version}</version>
</dependency>

To learn how to configure database drivers, please see this guide. To see the relevant list of CAS properties, please review this guide.

MySQL / Galera Limitations

Registration records and tokens keps inside a MySQL database backd by a Galera cluster might produce the following error when running CAS for the first time: This table type requires a primary key.

This is due to the fact that Galera needs primary keys on all tables (Galera setting innodb_force_primary_key = 1). See Galera known limitations, but the hibernate_sequence table does not define a primary key (See HHH-11923).

To workaround this issue, you can either:

  1. Create a custom hibernate_sequence table manually with a primary key id column in your Galera cluster:
1
2
3
4
5
CREATE TABLE `hibernate_sequence` (
  `id` bigint(20) NOT NULL AUTO_INCREMENT,
  `next_val` bigint(20) DEFAULT NULL,
  PRIMARY KEY (`id`)
) ENGINE=InnoDB;
  1. Define your own OneTimeToken and OneTimeTokenAccount classes in your overlay project and in both classes, annotate the id column with a @SequenceGenerator definition holding a primary key:
1
2
3
4
5
6
7
8
9
  @Id
  @GeneratedValue(strategy = GenerationType.TABLE, generator="ticket_sequence")
  @javax.persistence.TableGenerator (name="ticket_sequence", 
                                     table="ticket_sequence", 
                                     pkColumnName = "gen_name", 
                                     valueColumnName = "next_val", 
                                     pkColumnValue="gen_name", 
                                     allocationSize=100)
  private long id = Integer.MAX_VALUE;

MongoDb

Registration records and tokens may be kept inside a mongo db instance, via the following module:

1
2
3
4
5
<dependency>
     <groupId>org.apereo.cas</groupId>
     <artifactId>cas-server-support-gauth-mongo</artifactId>
     <version>${cas.version}</version>
</dependency>

To see the relevant list of CAS properties, please review this guide.

REST

Registration records may also be passed along to a REST endpoint. The behavior is only activated when an endpoint url is provided.

Method Headers Expected Response
GET username 200. Secret key of the account in the body.
POST username, validationCode, secretKey, scratchCodes 200. true/false in the body.

To see the relevant list of CAS properties, please review this guide.

JSON

Registration records may also be kept inside a single JSON file for all users. The behavior is only activated when a path to a JSON data store file is provided, and otherwise CAS may fallback to keeping records in memory. This feature is mostly useful during development and for demo purposes.

To see the relevant list of CAS properties, please review this guide.