Commit 33383ddc authored by Misagh Moayyed's avatar Misagh Moayyed
Browse files

updated docs

parent 3992627d
......@@ -4,31 +4,52 @@ title: CAS - ClearPass
---
# ClearPass: Credential Caching and Replay
To enable single sign-on into some legacy application it may be necessary to provide them with the actual password. While such approach inevitably increases security risk, at times this may be a necessary evil in order to integrate applications with CAS.
To enable single sign-on into some legacy application it may be necessary to provide them with the actual password.
While such approach inevitably increases security risk, at times this may be a necessary evil in order to integrate
applications with CAS.
<div class="alert alert-warning"><strong>Usage Warning!</strong><p>ClearPass is turned off by default. No applications will be able to obtain the user credentials unless ClearPass is explicitly turned on by the below configuration.</p></div>
<div class="alert alert-warning"><strong>Usage Warning!</strong><p>ClearPass is turned off by default.
No applications will be able to obtain the user credentials unless ClearPass is explicitly turned on by the
below configuration.</p></div>
<div class="alert alert-info"><strong>ClearPass via Proxying!</strong><p>If you wish to review the configuration for ClearPass via proxying, please <a href="ClearPass-Proxy-Authentication.html">see this link instead</a>.</p></div>
<div class="alert alert-info"><strong>ClearPass via Proxying!</strong><p>If you wish to review the configuration
for ClearPass via proxying, please <a href="ClearPass-Proxy-Authentication.html">see this link instead</a>.</p></div>
## Architecture
CAS is able to issue the credential password directly in the CAS validation response. This previously was handled via a proxy authentication sequence and obtaining a proxy-granting ticket for the ClearPass service and was necessary in order to establish trust between the client application and the CAS server. This document describes the configuration that can be applied in order to receive the credential password as an attribute in the CAS validation response.
CAS is able to issue the credential password directly in the CAS validation response. This previously was handled
via a proxy authentication sequence and obtaining a proxy-granting ticket for the ClearPass service and was necessary
in order to establish trust between the client application and the CAS server. This document describes the configuration that can be applied in order to receive the credential password as an attribute in the CAS validation response.
In order to successfully establish trust between the
CAS server and the application, private/public key pairs are generated by the client application and then **the public key** distributed and configured inside CAS. CAS will use the public key to encrypt the credential password and will issue a new attribute `<credential>` in the validation response, only if the service is authorized to receive it.
CAS server and the application, private/public key pairs are generated by the client application and then
**the public key** distributed and configured inside CAS. CAS will use the public key to encrypt the credential
password and will issue a new attribute `<credential>` in the validation response, only if the service is authorized to receive it.
Note that the return of the credential is only carried out by the CAS validation response, provided the client
application issues a request to the `/p3/serviceValidate` endpoint (or `/p3/proxyValidate`). Other means of returning attributes to CAS, such as SAML1 will **not** support the additional returning of this value.
application issues a request to the `/p3/serviceValidate` endpoint (or `/p3/proxyValidate`). Other means of
returning attributes to CAS, such as SAML1 will **not** support the additional returning of this value.
##Configuration
###Create Public/Private Keys
{% highlight bash %}
openssl genrsa -out private.key 1024
openssl rsa -pubout -in private.key -out public.key -inform PEM -outform DER
openssl pkcs8 -topk8 -inform PER -outform DER -nocrypt -in private.key -out private.p8
openssl req -new -x509 -key private.key -out x509.pem -days 365
{% endhighlight %}
###Register Service Public Key
Once you have received the public key from the client application owner, it must be first registered inside the CAS server's service registry:
Once you have received the public key from the client application owner, it must be first registered inside
the CAS server's service registry:
{% highlight xml %}
...
<property name="publicKey">
<bean class="org.jasig.cas.services.RegisteredServicePublicKeyImpl"
c:location="classpath:RSA1024Public.key"
c:location="classpath:public.key"
c:algorithm="RSA" />
</property>
...
......@@ -48,13 +69,16 @@ as an attribute for the given attribute release policy of choice:
{% endhighlight %}
###Decrypt the Password
Once the client application has received the `credential` attribute in the CAS validation response, it can decrypt it via its own private key. Since the attribute is base64 encoded by default, it needs to be decoded first before
Once the client application has received the `credential` attribute in the CAS validation response, it can decrypt
it via its own private key. Since the attribute is base64 encoded by default, it needs to be decoded first before
decryption can occur. Here's a sample code snippet:
{% highlight java %}
final Map<?, ?> attributes = ...
final String encodedPsw = (String) attributes.get("credential");
/* Use the private.key file generated above. */
final PrivateKey privateKey = ...
final Cipher cipher = Cipher.getInstance(privateKey.getAlgorithm());
final byte[] cred64 = decodeBase64ToByteArray(encodedPsw);
......
......@@ -17,9 +17,14 @@ Support is enabled by including the following dependency in the Maven WAR overla
{% endhighlight %}
##Generate Public/Private Keys
The first step is to generate DSA/RSA public and private keys. These are used to sign and read the Assertions. After keys are created, the public key needs to be registered with Google.
The first step is to generate DSA/RSA public and private keys. These are used to sign and read the Assertions.
After keys are created, the public key needs to be registered with Google.
The keys will also need to be available to the CAS application (but not publicly available over the Internet) via the classpath (i.e. `WEB-INF/classes`) though any location accessible by the user running the web server instance and not served publicly to the Internet is acceptable. Thus, inside `WEB-INF` is nice because `WEB-INF` is scoped to the web application but not normally served. `/etc/cas/keys/` is also fine as well and protects the key from being overwritten on deploy of a new CAS webapp version.
The keys will also need to be available to the CAS application (but not publicly available over the Internet)
via the classpath (i.e. `WEB-INF/classes`) though any location accessible by the user running the web server
instance and not served publicly to the Internet is acceptable. Thus, inside `WEB-INF` is
nice because `WEB-INF` is scoped to the web application but not normally served. `/etc/cas/keys/`
is also fine as well and protects the key from being overwritten on deploy of a new CAS webapp version.
{% highlight bash %}
openssl genrsa -out private.key 1024
......@@ -28,29 +33,21 @@ openssl pkcs8 -topk8 -inform PER -outform DER -nocrypt -in private.key -out priv
openssl req -new -x509 -key private.key -out x509.pem -days 365
{% endhighlight %}
The `public.key` and `private.p8` go into classpath. The `x509.pem` file should be uploaded into Google Apps under Security/SSO.
The `public.key` and `private.p8` go into classpath. The `x509.pem` file should be
uploaded into Google Apps under Security/SSO.
##Configure CAS
Google Accounts integration within CAS is enabled by simply adding an additional `ArgumentExtractor`. `WEB-INF/spring-configuration/argumentExtractorsConfiguration.xml` should be modified to add the following:
{% highlight xml %}
<bean id="googleAccountsArgumentExtractor"
class="org.jasig.cas.support.saml.web.support.GoogleAccountsArgumentExtractor"
c:servicesManager-ref="servicesManager"
c:privateKey-ref="privateKeyFactoryBean"
c:publicKey-ref="publicKeyFactoryBean" />
<bean id="privateKeyFactoryBean" class="org.jasig.cas.util.PrivateKeyFactoryBean"
p:location="classpath:private.p8"
p:algorithm="RSA" />
<bean id="publicKeyFactoryBean" class="org.jasig.cas.util.PublicKeyFactoryBean"
p:location="classpath:public.key"
p:algorithm="RSA" />
Adjust the following settings in your `cas.properties`:
{% highlight properties %}
##
# Google Apps public/private key
#
# cas.saml.googleapps.publickey.file=classpath:private.key
# cas.saml.googleapps.privatekey.file=classpath:public.key
# cas.saml.googleapps.key.alg=RSA
{% endhighlight %}
Replace the public.key and private.key with the names of your key files. If they are not available on the classpath, change the location to point to the location of the keys. If you are using DSA instead of RSA, change the algorithm as appropriate.
Also, ensure that Google Apps is registered in your Service Registry, by the `serviceId`: `https://www.google.com/a/YourGoogleDomain/acs`
##Configure Username Attribute
......@@ -59,7 +56,8 @@ can be specified in the CAS service registry via [username attribute providers](
for the registered Google Apps service.
##Configure Google
You'll need to provide Google with the URL for your SAML-based SSO service, as well as the URL your users will be redirected to when they log out of a hosted Google application.
You'll need to provide Google with the URL for your SAML-based SSO service, as well as the URL your users will
be redirected to when they log out of a hosted Google application.
Use the following URLs when you are configuring for Google Apps:
* Sign-in page URL: `https://sso.school.edu/cas/login`
......
Supports Markdown
0% or .
You are about to add 0 people to the discussion. Proceed with caution.
Finish editing this message first!
Please register or to comment