About

Central Authentication Service (in short CAS) is an open source, Java-based authentication server that includes a mechanism for  single sign-on (SSO) across web applications, including those running on different application servers. When a user requests a page from a CAS-enabled web application, the application redirects the user to the CAS server login page. Thereafter, logged-in users can navigate between all participating applications without needing to log in again. Each application communicates with the CAS server in the background to verify that the user is valid before providing access to its resources.

With the CAS protocol, the client application (Dispatcher Paragon management interface ) never receives or transmits the user’s password. However, unlike LDAP, CAS does not provide any user context, such as roles or organizations. CAS service provider supplies only the identification of the user in form of username property. This is used to map roles and privileges in Dispatcher Paragon management interface. 

For more information about CAS, visit: 

• https://en.wikipedia.org/wiki/Central_Authentication_Service
• https://apereo.github.io/cas/5.1.x/protocol/CAS-Protocol.html

Enabling the Integration

Client's workstation configuration 

CAS integration does not require any specific configuration of the client's workstations or browsers.

Dispatcher Paragon configuration

1. Log into the Dispatcher Paragon management interface using an admin account.
2. Navigate to System > Configuration and change the following properties.
   1. Under Basic filter, change property's webAuthenticationMethod value to CAS Single sign-on to enable the single sign-on method using CAS.
   2. Under Advanced filter, change property's localCasServiceUrl value of the Management interface CAS service endpoint.
   3. Under Advanced filter, change property's casServerUrl value to CAS service provider base URL.
   4. Under Advanced filter, change property's casServerLoginUrl value to URL of CAS server login page, where user authenticates.
   5. (Optional) Under Basic filter, it possible to enable property ldap-replicator-online-mode which determines whether Dispatcher Paragon tries to find user in directory service (e.g. Active Directory) instantly if the user is not present in the database. This parameter applies only to users which are not in the database, but they were successfully authenticated against CAS.
3. Restart Dispatcher Paragon Management Service to apply the settings.

Importing CAS server certificate 

Once the CAS service provider authenticates the user, it forwards the user back to the application where the authentication requests has been initiated. But the application needs to verify the authentication in CAS. For that, the certificate used by the CAS service provider has to be trusted by the Dispatcher Paragon - therefore it has to be imported into Dispatcher Paragon truststore. To do so, do the following:

1. Import the CAS service provider certificate into Dispatcher Paragon truststore using Java keytool. On the machine where the Management interface is running, open the command line and run the following keytool command:

   keytool -import -alias <certificate-alias> -keystore <truststore-location> -file <cas-certificate-location>

   • <certificate-alias> - a key under which will be the certificate stored in the truststore, e.g. cas-certificate

   • <truststore-location> - the location of the keystore, e.g. DispatcherParagon_DIR\Management\conf\ssl-truststore

   • <cas-certificate-location> - the location of the CAS service provider certificate to be imported

2. Enter a password for keystore protection.

3. Write yes to confirm you want to trust this certificate. If import was successful, the following message should appear: 

   Certificate was added to keystore

4. Restart Dispatcher Paragon Management Service to apply the settings.

When this feature is enabled following the instructions above and an administrator is not logged in to Dispatcher Paragon management interface and any page except the login page in entered (e.g., the root page, Dashboard, etc.), the redirection to the CAS service provider login page is done (to the URL defined by the property casServerLoginUrl). On this service, the administrator logs in, and if the logging in succeeds, the user is forwarded back to the Dispatcher Paragon management interface (to the URL defined by the property localCasServiceUrl, i.e.:  https://dispatcher_paragon_server_hostname/login/cas).

When exactly Dispatcher Paragon login page (https://dispatcher_paragon_server_hostname/login) is entered, the user is provided with the possibility to either log in using Single sign-on or may log in via standard username/password login option. 

When user is logged out of the system, the login page will be shown.

Caveats & Limitations

• Implemented CAS 3 .0 protocol specification (https://apereo.github.io/cas/5.1.x/protocol/CAS-Protocol-Specification.html#head2.5.7) without proxy support.
• CAS Single sign-on feature and its setting are available only in single tenant mode due to the technical limitations of the integration.
• CAS Single logout feature is not supported - logout from CAS service does not end an open session in Dispatcher Paragon management interface and vice versa.
• While using Management cluster deployment, only one localCasServiceUrl can be used, thus authenticating only one node in a cluster.
• No protection against login via CSRF is implemented.

Troubleshooting

In case the CAS SSO fails, user is redirected to login page with an common error message and has a possibility to log in via standard username/password login option.

Depending on the log message in the management-service.log one of the following problems may be experienced.

No subject alternative names present

In most cases this is a hostname/SSL certificate CN mismatch. This commonly happens when a self-signed certificate issued to localhost is placed on a machine that is accessed by IP address. It should be noted that generating a certificate with an IP address for a common name, e.g. CN=print-management.com,OU=Middleware will not work in most cases where the client making the connection is Java. For example the Java CAS client will throw SSL errors on connecting to a CAS server secured with a certificate containing an IP address in the CN.This is because IP Address in the CN is deprecated by both the IETF (most tools, like wget and curl) and CA/B Forums (CA's and Browsers). According to both the IETF and CA/B Forums, Server names and IP Addresses always go in the Subject Alternate Name (SAN). 

Unable to find valid certification path to requested target

The problem here is that the CAS client does not trust the certificate presented by the CAS server; most often this occurs because of using a self-signed certificate on the CAS server. To resolve this error, import the CAS server certificate (as described in section Importing CAS server certificate above) into the system truststore of the CAS client. If the certificate is issued by your own PKI, it is better to import the root certificate of your PKI into the CAS client truststore.

CAS server is unresponsive or unavailable

In case of network/configuration issues on side of CAS service provider, a Management interface can still be accessed using the https://dispatcher_paragon_server_hostname/login URL.