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.

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 doesn’t 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>

Endpoints

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>

Endpoints

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.

Register Clients

Clients and relying parties can be registered with CAS as such:

1
2
3
4
5
6
{
  "@class" : "org.apereo.cas.ws.idp.services.WSFederationRegisteredService",
  "serviceId" : "https://wsfed.example.org/.+",
  "name" : "Sample WsFed Application",
  "id" : 100
}

Service definitions may be managed by the service management facility.

Claims

The following claims are supported by CAS for release:

The attribute release policy assigned to relying parties and services is able to link a given standard claim and map it to an attribute that should be already available. The configuration looks as such:

1
2
3
4
5
6
7
8
9
10
11
12
{
  "@class" : "org.apereo.cas.ws.idp.services.WSFederationRegisteredService",
  "serviceId" : "https://wsfed.example.org/.+",
  "realm" : "urn:wsfed:example:org:sampleapplication",
  "attributeReleasePolicy" : {
    "@class" : "org.apereo.cas.ws.idp.services.WSFederationClaimsReleasePolicy",
    "allowedAttributes" : {
      "@class" : "java.util.TreeMap",
      "GIVEN_NAME" : "givenName"
    }
  }
}

The above snippet allows CAS to release the claim http://schemas.xmlsoap.org/ws/2005/05/identity/claims/givenname whose value is identified by the value of the givenName attribute that is already retrieved for the authenticated principal.

Configuration

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

You may also need to declare the following Maven repository in your CAS Overlay to be able to resolve dependencies:

1
2
3
4
5
6
7
8
<repositories>
    ...
    <repository>
        <id>shibboleth-releases</id>
        <url>https://build.shibboleth.net/nexus/content/repositories/releases</url>
    </repository>
    ...
</repositories>

Troubleshooting

To enable additional logging, modify the logging configuration file to add the following:

1
2
3
4
<AsyncLogger name="org.apache.cxf" level="debug" additivity="false">
    <AppenderRef ref="console"/>
    <AppenderRef ref="file"/>
</AsyncLogger>