WS Federation Protocol

CAS can act as a standalone identity provider, presenting support for the WS-Federation Passive Requestor Profile. The core functionality is built on top of Apache Fediz whose architecture is described here.

Remember

The functionality described here allows CAS to act as an identity provider to support the WS-Federation protocol. If you wish to do the opposite and hand off authentication to an external identity provider that supports WS-Federation, you may take advantage of Delegation as one integration option.

Security Token Service

The WS-Trust OASIS standard specifies a runtime component called Security Token Service. A service consumer requests a security token from the STS which is sent to the service provider. Either the service provider can validate the security token on its own or sends a request to the STS for validation. This pattern is based on an indirect trust relationship between the service provider and the STS instead of a direct trust between the service provider and service consumer. As long as the service consumer is in the possession of a security token issued by a trusted STS, the service provider accepts this security token.

A key benefit of the STS is the reduced complexity for applications. A web service consumer does not have to know how to create the various types of security tokens its service providers require. Instead, it sends a request to the STS containing the requirements of the client and the service provider and attaches the returned security token to the outgoing SOAP message to the service provider.

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-ws-sts</artifactId>
  <version>${cas.version}</version>
</dependency>
1
implementation "org.apereo.cas:cas-server-support-ws-sts:${project.'cas.version'}"
1
2
3
4
5
6
7
8
9
dependencyManagement {
  imports {
    mavenBom "org.apereo.cas:cas-server-support-bom:${project.'cas.version'}"
  }
}

dependencies {  
  implementation "org.apereo.cas:cas-server-support-ws-sts"
}
YAGNI

You do not need to explicitly include this component in your configuration and overlays. This is just to teach you that it exists. The security token service will be pulled in automatically once you declare the identity provider. Only include this module in your overlay if you need compile-time access to the components within.

Endpoints

Endpoint Description
/ws/sts Presents the list of available SOAP services and their WSDL configuration for each REALM defined in the configuration.

Security Tokens

Security tokens issued are treated as CAS tickets, stored in the ticket registry under the prefix STS and follow the same semantics as all other ticket types when it comes to persistence, replication, etc. These tokens are closely tied to the lifetime of the ticket-granting tickets and match their expiration policy. Tokens themselves do not have a lifespan outside a valid ticket-granting ticket and support for ticket lifetime configuration is not present.

WS Federation Identity Provider

The security model of the STS builds on the foundation established by WS-Security and WS-Trust. The primary issue for Web browsers is that there is no easy way to directly send web service (SOAP) requests. Consequently, the processing must be performed within the confines of the base HTTP 1.1 functionality (GET, POST, redirects, and cookies) and conform as closely as possible to the WS-Trust protocols for token acquisition. The IdP is in charge of transforming the sign-in request of the browser to a SOAP request for the STS and the response of the STS to the sign-in response for the browser. Further the browser user must authenticate with the IdP.

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-ws-idp</artifactId>
  <version>${cas.version}</version>
</dependency>
1
implementation "org.apereo.cas:cas-server-support-ws-idp:${project.'cas.version'}"
1
2
3
4
5
6
7
8
9
dependencyManagement {
  imports {
    mavenBom "org.apereo.cas:cas-server-support-bom:${project.'cas.version'}"
  }
}

dependencies {  
  implementation "org.apereo.cas:cas-server-support-ws-idp"
}

Endpoints

Endpoint Description
/ws/idp/metadata Displays the current federation metadata based on the configuration realm for the identity provider.
/ws/idp/federation Endpoint to receive initial GET authentication requests from clients, typically identified as the issuer.

Realms

At this point, by default security token service’s endpoint operate using a single realm configuration and identity provider configuration is only able to recognize and request tokens for a single realm. While support for multiple realms is not there yet, in general the underlying configuration should allow for that feature to exist in later releases. The default realm recognized by CAS is set to be urn:org:apereo:cas:ws:idp:realm-CAS. Registration of clients need to ensure this value is matched.

Clients

Please see this guide.

Claims

Please see this guide.

Token Types

The following token types are supported by CAS:

Type
http://docs.oasis-open.org/wss/oasis-wss-saml-token-profile-1.1#SAMLV1.1
http://docs.oasis-open.org/wss/oasis-wss-saml-token-profile-1.1#SAMLV2.0
urn:ietf:params:oauth:token-type:jwt
http://docs.oasis-open.org/ws-sx/ws-secureconversation/200512/sct

Token type may be configured on a per-service basis:

1
2
3
4
5
6
7
8
{
  "@class" : "org.apereo.cas.ws.idp.services.WSFederationRegisteredService",
  "serviceId" : "https://wsfed.example.org/.+",
  "realm" : "urn:wsfed:example:org:sampleapplication",
  "name" : "WSFED",
  "id" : 1,
  "tokenType": "http://docs.oasis-open.org/wss/oasis-wss-saml-token-profile-1.1#SAMLV1.1"
}

Configuration

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.

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.

  • cas.client.prefix=
  • Prefix of the CAS server used to establish ticket validators for the client. Typically set to https://sso.example.org/cas

    org.apereo.cas.configuration.model.core.CasJavaClientProperties.

  • cas.client.validator-type=CAS30
  • Determines the type of ticket validator that CAS should create from the Java CAS client when attempting to issue in-bound ticket validation calls. Available values are as follows:

    • CAS10: CAS10 ticket validator.
    • CAS20: CAS20 ticket validator.
    • CAS30: CAS30 ticket validator.
    • JSON: JSON ticket validator.

    org.apereo.cas.configuration.model.core.CasJavaClientProperties.