OAuth/OpenID Authentication

Allow CAS to act as an OAuth/OpenID authentication provider. Please review the specification to learn more.

Configuration

Support is enabled by including the following dependency in the WAR overlay:

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

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

Endpoints

After enabling OAuth support, the following endpoints will be available:

Response/Grant Types

The following types are supported; they allow you to get an access token representing the current user and OAuth client application. With the access token, you’ll be able to query the /profile endpoint and get the user profile.

Authorization Code

The authorization code type is made for UI interactions: the user will enter credentials, shall receive a code and will exchange that code for an access token.

Token/Implicit

The token type is also made for UI interactions as well as indirect non-interactive (i.e. Javascript) applications.

Resource Owner Credentials

The password grant type allows the OAuth client to directly send the user’s credentials to the OAuth server. This grant is a great user experience for trusted first party clients both on the web and in native device applications.

Because there is no redirect_uri specified by this grant type, the service identifier recognized by CAS and matched in the service registry is taken as the client_id instead. You may optionally also pass along a service or X-service header value that identifies the target application url. The header value must match the OAuth service definition in the registry that is linked to the client id.

Client Credentials

The simplest of all of the OAuth grants, this grant is suitable for machine-to-machine authentication where a specific user’s permission to access data is not required.

Because there is no redirect_uri specified by this grant type, the service identifier recognized by CAS and matched in the service registry is taken as the client_id instead. You may optionally also pass along a service or X-service header value that identifies the target application url. The header value must match the OAuth service definition in the registry that is linked to the client id.

Refresh Token

The refresh token grant type retrieves a new access token from a refresh token (emitted for a previous access token), when this previous access token is expired.

Grant Type Selection

A grant is a method of acquiring an access token. Deciding which grants to implement depends on the type of client the end user will be using, and the experience you want for your users.

To learn more about profiles and grant types, please review this guide.

Register Clients

Every OAuth client must be defined as a CAS service (notice the new clientId and clientSecret properties, specific to OAuth):

1
2
3
4
5
6
7
8
9
10
{
  "@class" : "org.apereo.cas.support.oauth.services.OAuthRegisteredService",
  "clientId": "clientid",
  "clientSecret": "clientSecret",
  "serviceId" : "^(https|imaps)://<redirect-uri>.*",
  "name" : "OAuthService",
  "id" : 100,
  "supportedGrantTypes": [ "java.util.HashSet", [ "...", "..." ] ],
  "supportedResponseTypes": [ "java.util.HashSet", [ "...", "..." ] ]
}

The following fields are supported:

Service definitions are typically managed by the service management facility.

Attribute Release

Attribute/claim filtering and release policies are defined per OAuth service. See this guide for more info.

OAuth Expiration Policy

The expiration policy for OAuth tokens is controlled by CAS settings and properties. Note that while access and refresh tokens may have their own lifetime and expiration policy, they are typically upper-bound to the length of the CAS single sign-on session.

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

OAuth User Profile Structure

The requested user profile may be rendered and consumed by the application using the following options.

Nested

By default, the requested user profile is rendered using a NESTED format where the authenticated principal and attributes are placed inside id and attributes tags respectively in the final structure.

1
2
3
4
5
6
7
8
{
  "id": "casuser",
  "attributes": {
    "email": "casuser@example.org",
    "name": "CAS"
  },
  "something": "else"
}

Flat

This option flattens principal attributes by one degree, putting them at the same level as id. Other nested elements in the final payload are left untouched.

1
2
3
4
5
6
{
  "id": "casuser",
  "email": "casuser@example.org",
  "name": "CAS",
  "something": "else"
}

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

Custom

If you wish to create your own profile structure, you will need to design a component and register it with CAS to handle the rendering of the user profile:

1
2
3
4
5
6
7
8
9
10
11
12
package org.apereo.cas.support.oauth;

@Configuration("MyOAuthConfiguration")
@EnableConfigurationProperties(CasConfigurationProperties.class)
public class MyOAuthConfiguration {

    @Bean
    @RefreshScope
    public OAuth20UserProfileViewRenderer oauthUserProfileViewRenderer() {
        ...
    }
}

See this guide to learn more about how to register configurations into the CAS runtime.

Throttling

Authentication throttling may be enabled for the /oauth2.0/accessToken provided support is included in the overlay to turn on authentication throttling support. The throttling mechanism that handles the usual CAS server endpoints for authentication and ticket validation, etc is then activated for the OAuth endpoints that are supported for throttling.

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

Server Configuration

Remember that OAuth features of CAS require session affinity (and optionally session replication), as the authorization responses throughout the login flow are stored via server-backed session storage mechanisms. You will need to configure your deployment environment and load balancers accordingly.

OpenID Authentication

To configure CAS to act as an OpenID provider, please see this page.