Configure Service Access Strategy

The access strategy of a registered service provides fine-grained control over the service authorization rules. It describes whether the service is allowed to use the CAS server, allowed to participate in single sign-on authentication, etc. Additionally, it may be configured to require a certain set of principal attributes that must exist before access can be granted to the service. This behavior allows one to configure various attributes in terms of access roles for the application and define rules that would be enacted and validated when an authentication request from the application arrives.

Default Strategy

The default strategy allows one to configure a service with the following properties:

Field Description
enabled Flag to toggle whether the entry is active; a disabled entry produces behavior equivalent to a non-existent entry.
ssoEnabled Set to false to force users to authenticate to the service regardless of protocol flags (e.g. renew=true).
requiredAttributes A Map of required principal attribute names along with the set of values for each attribute. These attributes MUST be available to the authenticated Principal and resolved before CAS can proceed, providing an option for role-based access control from the CAS perspective. If no required attributes are presented, the check will be entirely ignored.
requireAllAttributes Flag to toggle to control the behavior of required attributes. Default is true, which means all required attribute names must be present. Otherwise, at least one matching attribute name may suffice. Note that this flag only controls which and how many of the attribute names must be present. If attribute names satisfy the CAS configuration, at the next step at least one matching attribute value is required for the access strategy to proceed successfully.
unauthorizedRedirectUrl Optional url to redirect the flow in case service access is not allowed.
caseInsensitive Indicates whether matching on required attribute values should be done in a case-insensitive manner. Default is false
rejectedAttributes A Map of rejected principal attribute names along with the set of values for each attribute. These attributes MUST NOT be available to the authenticated Principal so that access may be granted. If none is defined, the check is entirely ignored.
Are we sensitive to case?

Note that comparison of principal/required attribute names is case-sensitive. Exact matches are required for any individual attribute name.

Released Attributes

Note that if the CAS server is configured to cache attributes upon release, all required attributes must also be released to the relying party. See this guide for more info on attribute release and filters.

Examples

The following examples demonstrate access policy enforcement features of CAS.

Disable Service Access

Service is not allowed to use CAS:

1
2
3
4
5
6
7
8
9
10
11

{
  "@class" : "org.apereo.cas.services.RegexRegisteredService",
  "serviceId" : "testId",
  "name" : "testId",
  "id" : 1,
  "accessStrategy" : {
    "@class" : "org.apereo.cas.services.DefaultRegisteredServiceAccessStrategy",
    "enabled" : false,
    "ssoEnabled" : true
  }
}

Enforce Attributes

To access the service, the principal must have a cn attribute with the value of admin AND a givenName attribute with the value of Administrator:

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16

{
  "@class" : "org.apereo.cas.services.RegexRegisteredService",
  "serviceId" : "testId",
  "name" : "testId",
  "id" : 1,
  "accessStrategy" : {
    "@class" : "org.apereo.cas.services.DefaultRegisteredServiceAccessStrategy",
    "enabled" : true,
    "ssoEnabled" : true,
    "requiredAttributes" : {
      "@class" : "java.util.HashMap",
      "cn" : [ "java.util.HashSet", [ "admin" ] ],
      "givenName" : [ "java.util.HashSet", [ "Administrator" ] ]
    }
  }
}

To access the service, the principal must have a cn attribute with the value of admin OR a givenName attribute with the value of Administrator:

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17

{
  "@class" : "org.apereo.cas.services.RegexRegisteredService",
  "serviceId" : "testId",
  "name" : "testId",
  "id" : 1,
  "accessStrategy" : {
    "@class" : "org.apereo.cas.services.DefaultRegisteredServiceAccessStrategy",
    "enabled" : true,
    "ssoEnabled" : true,
    "requireAllAttributes": false,
    "requiredAttributes" : {
      "@class" : "java.util.HashMap",
      "cn" : [ "java.util.HashSet", [ "admin" ] ],
      "givenName" : [ "java.util.HashSet", [ "Administrator" ] ]
    }
  }
}

To access the service, the principal must have a cn attribute whose value is either of admin, Admin or TheAdmin.

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15

{
  "@class" : "org.apereo.cas.services.RegexRegisteredService",
  "serviceId" : "testId",
  "name" : "testId",
  "id" : 1,
  "accessStrategy" : {
    "@class" : "org.apereo.cas.services.DefaultRegisteredServiceAccessStrategy",
    "enabled" : true,
    "ssoEnabled" : true,
    "requiredAttributes" : {
      "@class" : "java.util.HashMap",
      "cn" : [ "java.util.HashSet", [ "admin", "Admin", "TheAdmin" ] ]
    }
  }
}
Supported Syntax

Required values for a given attribute support regular expression patterns. For example, a phone attribute could require a value pattern of \d\d\d-\d\d\d-\d\d\d\d.

Static Unauthorized Redirect URL

Service access is denied if the principal does not have a cn attribute containing the value super-user. If so, the user will be redirected to https://www.github.com instead.

1
2
3
4
5
6
7
8
9
10
11
12
13
14

{
  "@class": "org.apereo.cas.services.RegexRegisteredService",
  "serviceId" : "testId",
  "name" : "testId",
  "id": 1,
  "accessStrategy" : {
    "@class" : "org.apereo.cas.services.DefaultRegisteredServiceAccessStrategy",
    "unauthorizedRedirectUrl" : "https://www.github.com",
    "requiredAttributes" : {
      "@class" : "java.util.HashMap",
      "cn" : [ "java.util.HashSet", [ "super-user" ] ]
    }
  }
}

Dynamic Unauthorized Redirect URL

Service access is denied if the principal does not have a cn attribute containing the value super-user. If so, the redirect URL will be dynamically determined based on outcome of the specified Groovy script.

1
2
3
4
5
6
7
8
9
10
11
12
13
14

{
  "@class": "org.apereo.cas.services.RegexRegisteredService",
  "serviceId" : "testId",
  "name" : "testId",
  "id": 1,
  "accessStrategy" : {
    "@class" : "org.apereo.cas.services.DefaultRegisteredServiceAccessStrategy",
    "unauthorizedRedirectUrl" : "file:/etc/cas/config/unauthz-redirect-url.groovy",
    "requiredAttributes" : {
      "@class" : "java.util.HashMap",
      "cn" : [ "java.util.HashSet", [ "super-user" ] ]
    }
  }
}

The script itself will take the following form:

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18

import org.apereo.cas.*
import org.apereo.cas.web.support.*
import java.util.*
import java.net.*
import org.apereo.cas.authentication.*

URI run(final Object... args) {
    def registeredService = args[0]
    def requestContext = args[1]
    def applicationContext = args[2]
    def logger = args[3]
    
    logger.info("Redirecting to somewhere, processing [{}]", registeredService.name)
    /**
     * Stuff Happens...
     */
    return new URI("https://www.github.com");
}

The following parameters are provided to the script:

Field Description
registeredService The object representing the matching registered service in the registry.
requestContext The object representing the Spring Webflow RequestContext.
applicationContext The object representing the Spring ApplicationContext.
logger The object responsible for issuing log messages such as logger.info(...).

Enforce Combined Attribute Conditions

To access the service, the principal must have a cn attribute whose value is either of admin, Admin or TheAdmin, OR the principal must have a member attribute whose value is either of admins, adminGroup or staff.

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17

{
  "@class" : "org.apereo.cas.services.RegexRegisteredService",
  "serviceId" : "testId",
  "name" : "testId",
  "id" : 1,
  "accessStrategy" : {
    "@class" : "org.apereo.cas.services.DefaultRegisteredServiceAccessStrategy",
    "enabled" : true,
    "requireAllAttributes" : false,
    "ssoEnabled" : true,
    "requiredAttributes" : {
      "@class" : "java.util.HashMap",
      "cn" : [ "java.util.HashSet", [ "admin", "Admin", "TheAdmin" ] ],
      "member" : [ "java.util.HashSet", [ "admins", "adminGroup", "staff" ] ]
    }
  }
}

Enforce Must-Not-Have Attributes

To access the service, the principal must have a cn attribute whose value is either of admin, Admin or TheAdmin, OR the principal must have a member attribute whose value is either of admins, adminGroup or staff. The principal also must not have an attribute “role” whose value matches the pattern deny.+.

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21

{
  "@class" : "org.apereo.cas.services.RegexRegisteredService",
  "serviceId" : "testId",
  "name" : "testId",
  "id" : 1,
  "accessStrategy" : {
    "@class" : "org.apereo.cas.services.DefaultRegisteredServiceAccessStrategy",
    "enabled" : true,
    "requireAllAttributes" : false,
    "ssoEnabled" : true,
    "requiredAttributes" : {
      "@class" : "java.util.HashMap",
      "cn" : [ "java.util.HashSet", [ "admin", "Admin", "TheAdmin" ] ],
      "member" : [ "java.util.HashSet", [ "admins", "adminGroup", "staff" ] ]
    },
    "rejectedAttributes" : {
      "@class" : "java.util.HashMap",
      "role" : [ "java.util.HashSet", [ "deny.+" ] ]
    }
  }
}
Supported Syntax

Rejected values for a given attribute support regular expression patterns. For example, a role attribute could be designed with a value value pattern of admin-.*.

Global Groovy Script

Access strategy and authorization decision can be carried using a Groovy script for all services and applications. This policy is not tied to a specific application and is invoked for all services and integrations.

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

The configuration settings listed below are tagged as Required in the CAS configuration metadata. This flag indicates that the presence of the setting may be needed to activate or affect the behavior of the CAS feature and generally should be reviewed, possibly owned and adjusted. If the setting is assigned a default value, you do not need to strictly put the setting in your copy of the configuration, but should review it nonetheless to make sure it matches your deployment expectations.

  • cas.access-strategy.groovy.location=

    • The location of the resource. Resources can be URLS, or files found either on the classpath or outside somewhere in the file system.

    In the event the configured resource is a Groovy script, specially if the script set to reload on changes, you may need to adjust the total number of inotify instances. On Linux, you may need to add the following line to /etc/sysctl.conf: fs.inotify.max_user_instances = 256.

    You can check the current value via cat /proc/sys/fs/inotify/max_user_instances.

    org.apereo.cas.configuration.model.SpringResourceProperties.
    The configuration settings listed below are tagged as Optional in the CAS configuration metadata. This flag indicates that the presence of the setting is not immediately necessary in the end-user CAS configuration, because a default value is assigned or the activation of the feature is not conditionally controlled by the setting value.