Client Registration - OAuth Authentication

Every OAuth relying party must be defined as a CAS service:

{
  "@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", [ "...", "..." ] ],
  "scopes": [ "java.util.HashSet", [ "MyCustomScope" ] ],
  "allowedResources": [ "java.util.HashSet", [ "https://api.example.org/" ] ],
  "audience": [ "java.util.HashSet", [ "MyAudience" ] ],
}

The following fields are supported:

Field	Description
`serviceId`	The pattern that authorizes the redirect URI(s), or same as `clientId` in case `redirect_uri` is not required by the grant type (i.e `client_credentials`, etc). Note that the `redirect_uri` parameter that is ultimately matched against pattern must not have URL fragments, invalid schemes such as `javascript` or `data` or suspicious parameters such as `code`, `state`, etc.
`clientId`	The client identifier for the application/service.
`clientSecret`	The client secret for the application/service. The client secret received from the service will be URL decoded before being compared to the secret in the CAS service definition.
`userProfileViewType`	Formatting options for the user profiles; Default is undefined. Options are `NESTED`, `FLAT`.
`scopes`	Collection of authorized scopes for this service that act as a filter for the requested scopes in the authorization request.
`allowedResources`	Collection of regular expressions for the resource URIs the client may request with the RFC 8707 `resource` parameter. See this section.
`supportedGrantTypes`	Collection of supported grant types for this service.
`supportedResponseTypes`	Collection of supported response types for this service.
`bypassApprovalPrompt`	Whether approval prompt/consent screen should be bypassed. Default is `false`.
`generateRefreshToken`	Whether a refresh token should be generated along with the access token. Default is `false`.
`renewRefreshToken`	Whether the existing refresh token should be expired and a new one generated (and sent along) whenever a new access token is requested (with `grant_type` = `refresh_token`). Only possible if `generateRefreshToken` is set to `true`. Default is `false`.
`jwtAccessToken`	Whether access tokens should be created as JWTs. Default is `false`.
`jwtRefreshToken`	Whether refresh tokens should be created as JWTs. Default is `false`.
`jwtAccessTokenSigningAlg`	The JWT signing algorithm to use for JWT access tokens. Defaults to the signing key’s algorithm.
`introspectionSignedResponseAlg`	Optional. The algorithm header value used to sign the JWT introspection response. Default is `RS512`, also used for `none`.
`introspectionEncryptedResponseAlg`	Optional. The algorithm header value used for content key encryption relevant for introspection JWT responses.
`introspectionEncryptedResponseEncoding`	Optional. The algorithm method header value used to content encryption relevant for introspection JWT responses.
`responseMode`	Allow CAS to alter the mechanism used for returning responses back to the client. See this.
`audience`	Optional. Set of values that can control the `aud` field in JWT access tokens, token introspection responses or ID tokens. If left undefined, the client ID will typically be used instead.

Keep What You Need!

You are encouraged to only keep and maintain properties and settings needed for a particular integration. It is UNNECESSARY to grab a copy of all service fields and try to configure them yet again based on their default. While you may wish to keep a copy as a reference, this strategy would ultimately lead to poor upgrades increasing chances of breaking changes and a messy deployment at that.

Service definitions are typically managed by the service management facility.

Resource Indicators

A client may name the resources it needs an access token for with the RFC 8707 resource parameter, once or more, on the authorization request, a pushed authorization request or request object, the device authorization request, the CIBA backchannel authentication request, and the token request of the password, client_credentials, urn:ietf:params:oauth:grant-type:jwt-bearer and urn:ietf:params:oauth:grant-type:pre-authorized_code grants. Each value must be an absolute URI without a fragment that matches one of the regular expressions in the service’s allowedResources, or in the resources CAS allows for every client, in full, case-sensitively; otherwise, the request is refused with invalid_target. Since every entry is a regular expression, escape characters such as ? or + to match them literally, i.e. "https://api\\.example\\.org/(orders|reports)" in a JSON service definition. The allowedResources of a token exchange policy follow the same rule.

Requested resources are added to the access token audience, after the audience of the service or the client ID. The JWT access token and the token introspection response report the same audience.
The consent screen lists the requested resources, and a consent decision covers them: a decision remembered for some resources does not approve a request for others.
When redeeming an authorization code or a refresh token, the token request may name some of the resources granted to the code or refresh token, and the access token is issued for those only. Naming any other resource is refused with invalid_target. A refresh token keeps all the resources of its grant. When the grant carries no resources, the token request may name any resource that matches the service’s allowedResources or the resources CAS allows for every client.
A token exchange issues tokens for its requested audience or resource only, without the resources of the exchanged token.

Resources For Every Client

Resources defined in CAS settings may be requested by every client, in addition to the allowedResources of its service. This suits resources hosted by CAS itself, such as the CAS MCP server, which clients that register themselves dynamically cannot list in their own registration. Entries are regular expressions and follow the same matching rule. By default, CAS allows its MCP server endpoint, i.e. \Qhttps://sso.example.org/cas/mcp\E, built from the CAS server prefix and the MCP endpoint path; defining these resources replaces that default, so list the MCP server endpoint again if clients should still request it.

The following settings and properties are available from the CAS configuration catalog:

cas.authn.oauth.core.allowed-resources

no default

Type: List<String>
Default: none

Required settings may be needed to activate or affect the feature; review them even when they have a default. Optional settings only need to be set to change a default or to turn on the behavior they control. Third party settings belong to libraries such as Spring Boot that CAS builds on; their own documentation may have more detail.

Notes on configuration

Configuration Metadata

The collection of configuration properties listed in this section are automatically generated from the CAS source and components that contain the actual field definitions, types, descriptions, modules, etc. This metadata may not always be 100% accurate, or could be lacking details and sufficient explanations.

Be Selective

This section is meant as a guide only. Do NOT copy/paste the entire collection of settings into your CAS configuration; rather pick only the properties that you need. Do NOT enable settings unless you are certain of their purpose and do NOT copy settings into your configuration only to keep them as reference. All these ideas lead to upgrade headaches, maintenance nightmares and premature aging.

YAGNI

Note that for nearly ALL use cases, declaring and configuring properties listed here is sufficient. You should NOT have to explicitly massage a CAS XML/Java/etc configuration file to design an authentication handler, create attribute release policies, etc. CAS at runtime will auto-configure all required changes for you. If you are unsure about the meaning of a given CAS setting, do NOT turn it on without hesitation. Review the codebase or better yet, ask questions to clarify the intended behavior.

Naming Convention

Property names can be specified in very relaxed terms. For instance cas.someProperty, cas.some-property, cas.some_property are all valid names. While all forms are accepted by CAS, there are certain components (in CAS and other frameworks used) whose activation at runtime is conditional on a property value, where this property is required to have been specified in CAS configuration using kebab case. This is both true for properties that are owned by CAS as well as those that might be presented to the system via an external library or framework such as Spring Boot, etc.

Note

When possible, properties should be stored in lower-case kebab format, such as cas.property-name=value. The only possible exception to this rule is when naming actuator endpoints; The name of the actuator endpoints (i.e. ssoSessions) MUST remain in camelCase mode.

Settings and properties that are controlled by the CAS platform directly always begin with the prefix cas. All other settings are controlled and provided to CAS via other underlying frameworks and may have their own schemas and syntax. BE CAREFUL with the distinction. Unrecognized properties are rejected by CAS and/or frameworks upon which CAS depends. This means if you somehow misspell a property definition or fail to adhere to the dot-notation syntax and such, your setting is entirely refused by CAS and likely the feature it controls will never be activated in the way you intend.

Validation

Configuration properties are automatically validated on CAS startup to report issues with configuration binding, especially if defined CAS settings cannot be recognized or validated by the configuration schema. Additional validation processes are also handled via Configuration Metadata and property migrations applied automatically on startup by Spring Boot and family.

Indexed Settings

CAS settings able to accept multiple values are typically documented with an index, such as cas.some.setting[0]=value. The index [0] is meant to be incremented by the adopter to allow for distinct multiple configuration blocks.

Attribute Release

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