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, etc.

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.

Administrative Endpoints

The following endpoints are provided by CAS:

Endpoint Description
gauthCredentialRepository Manage and control Google Authenticator account records. A GET operation produces a list of all account records. A DELETE operation will delete all account records. A GET operation produces with a parameter selector of /{username} will list the record assigned to the user. A DELETE operation produces with a parameter selector of /{username} will remove the record assigned to the user.

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.

Note that each individual account is allowed to register multiple devices to be used later for multifactor authentication. Duration the authentication flow, the user will be asked to select the appropriate device for authentication if multiple device registration records are found. The ability to handle multiple device registration records can be controlled via CAS settings.

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.

CouchDb

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

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

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

MongoDb

Registration records and tokens may be kept inside a MongoDb 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.

Redis

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

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

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

LDAP

Registration records may be kept inside LDAP/AD systems via the following module:

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

Account registration records are kept inside a designated configurable multi-valued attribute as JSON blobs. The attribute values are parsed to load, save, update or delete accounts. The content of each attribute value can be signed/encrypted if necessary.

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 Behavior
GET username 200. Account records in the body for the user. Fetch user records
GET id 200. Account record in the body for the user. Fetch record for the given identifier.
GET id, username 200. Account record in the body for the user. Fetch user record for the given identifier.
GET N/A 200. Account records currently registered. Fetch all records
DELETE N/A 200. Delete all records.
DELETE username 200. Count deleted records. Delete all records assigned to user
POST username, validationCode, secretKey, scratchCodes, name 200. true/false in the body. Save user record

A sample payload that lists device registration records for the user might be:

1
2
3
4
5
6
7
8
9
10
11
12
[
    "java.util.ArrayList", [{
        "@class": "org.apereo.cas.gauth.credential.GoogleAuthenticatorAccount",
        "scratchCodes": ["java.util.ArrayList", [14883628,81852839,40126334,86724930,54355266] ],
        "id": 123456,
        "secretKey": "UM6ALPJU34CBNFTBBLRFMKBNANMFAIBW",
        "validationCode": 565889,
        "username": "casuser",
        "name": "required-account-name",
        "registrationDate": "2018-06-20T09:47:31.761155Z"
    }]
]

The following endpoints need also be available:

Method Endpoint Headers Expected Response Behavior
GET count N/A 200. Numeric count Count all records
GET count username 200. Numeric count Count all records for the user

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.

REST Protocol Credential Extraction

In the event that the CAS REST Protocol is turned on, a special credential extractor is injected into the REST authentication engine in order to recognize credentials and authenticate them as part of the REST request. The expected parameter name in the request body is gauthotp. The account identifier may also be passed using the gauthacct parameter in the request body.