Skip to main content

Notice: this Wiki will be going read only early in 2024 and edits will no longer be possible. Please see: https://gitlab.eclipse.org/eclipsefdn/helpdesk/-/wikis/Wiki-shutdown-plan for the plan.

Jump to: navigation, search

Difference between revisions of "SAML2 IdP Solution"

(How to configure OpenLDAP for TLS)
(Removing all content from page)
 
(36 intermediate revisions by 4 users not shown)
Line 1: Line 1:
This page describes how to download, build, configure and deploy the Higgins SAML2 IdP. This deployment is a web application that is able to act as a SAML 2.0 IdP endpoint to authenticate users against a Higgins IdAS [[context]]. By default, an LDAP context is used, however any technology for which a Higgins context provider exists can be used instead.
 
  
In addition, a second web application is provided that acts as a sample relying party to test the IdP. This is not necessary if you have your own SAML 2.0 relying party application.
 
 
''Note: In SAML 2.0 terminology, the terms "relying party" (RP) and "service provider" (SP) are synonymous.''
 
 
This page contains instructions on how to check out and deploy the components. See [[SAML2 IdP]] for more information on how the deployed web applications interact with each other.
 
 
==Prerequisites==
 
 
This guide assumes you have the following software:
 
* Eclipse IDE 3.3 or later (see http://www.eclipse.org/)
 
* Web standard tools 2.0.1 or later (see http://www.eclipse.org/webtools/)
 
* Apache Tomcat 5.5 or later (or other servlet container)
 
* JDK/JRE 1.4 or later
 
 
==Set up your Eclipse workspace==
 
 
===Open a blank workspace===
 
 
After you start Eclipse, it should display a blank workspace. If you have already been working in Eclipse and your workspace is not empty, you can create a new empty one by selecting File -> Switch Workspace -> Other. Select a folder to use for your new, blank workspace.
 
 
Your workspace should look like this:
 
 
[[Image:saml2idp-setup1.png|thumb|none|Blank Eclipse workspace]]
 
 
===Configure JRE===
 
 
You should specify the JDK or JRE (Java Runtime Environment) you want to use to build the Higgins components. Click Window -> Preferences and select Java -> Installed JREs. The default JRE is the one that was used to launch Eclipse, however you may want to add a different one and set it as the workspace-default one for building. Higgins components are usually built with a Java 1.4 compiler.
 
 
[[Image:saml2idp-setup11.png|thumb|none|Configure JRE]]
 
 
''Note: You should also check Java -> Compiler -> Compiler compliance level, and make sure this matches the JRE you use to build the projects.''
 
 
===Configure server runtime===
 
 
In order to work with web applications, Eclipse needs to know about the servlet container (e.g. Tomcat) you want to use. Click Window -> Preferences and select Server -> Installed Runtimes. Click "Add...". Select the server you want to use (e.g. Tomcat 5.5), click "Next", specify the installation directory and click "Finish".
 
 
[[Image:saml2idp-setup10.png|thumb|none|Configure server runtime]]
 
 
''Note: It is recommended to install Tomcat at a path that does not contain any spaces.''
 
 
==Populate the Eclipse workspace==
 
 
The next step is to populate your Eclipse workspace with the required projects. There are three ways of doing this:
 
 
* Download and import .war files. This is a quick and simple approach that already includes all third party libraries.
 
* Check out and build sources via download script. This will always give you the latest versions of all components. Simply import projects into eclipse workspace after the script complete it's work.
 
* Check out and build sources manually. This will always give you the latest versions of all components, but requires manually downloading and installing dependencies.
 
 
===Download and import .WAR files===
 
 
Two .WAR files (one for the IdP, one for the RP) are provided for download that constitute snapshots done at one point in time:
 
 
http://graceland.parityinc.net/~msabadello/saml2idp/org.eclipse.higgins.saml2idp.server.war for the IdP web application.
 
 
http://graceland.parityinc.net/~msabadello/saml2idp/org.eclipse.higgins.saml2idp.test.war for the RP web application (optional).
 
 
Download these files to your computer. Then in your blank Eclipse workspace, click File -> Import. In the import source list, select Web -> WAR file. Click "Browse" and select the org.eclipse.higgins.saml2idp.server.war file you just downloaded. In the "Target runtime" drop-down list, select the server runtime you configured when setting up the workspace. Click "Finish". Eclipse will create a project containing the SAML2 IdP Server web application. When asked to switch to the Java EE perspective, click "Yes".
 
 
Optional: Also import the org.eclipse.higgins.saml2idp.test.war file, if you want to use the RP as well.
 
 
Now your workspace should look like this:
 
 
[[Image:saml2idp-setup2.png|thumb|none|Two imported web application projects]]
 
 
===Check out sources automatically===
 
 
This section explains how you can use an automatic script to check out all required sources and dependencies.
 
 
<span id="myanchor">qsdf</span>First of all import org.eclipse.higgins.auto project into workspace, click File -> Import. In the import source list, select CVS -> Projects from CVS. The information for connecting to the Eclipse CVS see in 'Check out sources manually' section.
 
Project CVS path is:
 
 
# Checkout '''org.eclipse.higgins.auto project''' at '''org.eclipse.higgins/builds/''' from '''dev.eclipse.org:/cvsroot/technology'''
 
# If you don't have cvs binary on your machine, download it from internet (windows version can be downloaded from [http://other.jrsoftware.org/ic/cvs-1.11.2.zip here]) and add it to your PATH. You need to restart eclipse after adding cvs binary to PATH.
 
# Right click on org.eclipse.higgins.auto/runtime/fetchwithdeps.xml -> Run As ... -> Ant Build ... Then select the "Classpath" tab.
 
# Click on "User Entries" and then click "Add JARs ..."
 
# Add bsf.jar, commons-logging-1.1.jar, js.jar, xercesImpl.jar, xml-apis.jar from org.eclipse.higgins.auto/lib and auto-classes.jar from org.eclipse.higgins.auto/build/lib
 
# Select the "Main" tab, then in the "Arguments" textbox, type -DprojectId=<required_project_id> [-DbuildDirectory=<path_to_store_projects>].
 
#* ''required_project_id'' - name of project you wish to check out (all dependencies (projects &amp; libs) downloading automatically). For example org.eclipse.higgins.saml2idp.server or org.eclipse.higgins.saml2idp.test.
 
#* ''path_to_store_projects'' - path where projects will be stored. This param is optional, by default projects stores into the same directory where org.eclipse.higgins.auto located (current eclipse workspace). May be relative to current eclipse workspace.
 
# Click Run button, wait until script complete work. Note: This may take several minutes, depending on your internet connection and current Eclipse server load.
 
# Click File -> import -> General -> Existing Projects into Workspace -> Next.
 
# Select root directory - currect workspace or ''path_to_store_projects'' if specified.
 
# If the org.eclipse.higgins.auto project is present in the list and checked, un-select it (since it already exists in workspace).
 
# Click Finish.
 
 
''Note #1: This checks out one project with all its dependencies. If you want to use both the saml2idp.server and saml2idp.test projects you will need to repeat steps 6-11 twice.''
 
 
''Note #2: The script does not build the .jar files of the plugin projects that are required to run the web applications. This means that in order to make the web applications work, you still have to follow the last part of the "Check out sources manually" section, starting with the "Next step is to build .jar files" paragraph. [[#buildjars|Click]] to scroll there.''
 
 
[[Image:saml2idp-setup18.png|thumb|none|Configuring parameters for the fetchwithdeps.xml build script]]
 
 
[[Image:saml2idp-setup17.png|thumb|none|The build script runs for several minutes, fetching dependencies]]
 
 
[[Image:saml2idp-setup19.png|thumb|none|The fetched projects are imported into the workspace]]
 
 
===Check out sources manually===
 
 
The third option is to manually check out and build components from the Eclipse CVS. The primary source of information on building components is the [[Components]] wiki page.
 
 
In order to check out the components needed for the SAML2 IdP, click File -> Import. In the import source list, select CVS -> Projects from CVS. The information for connecting to the Eclipse CVS is as follows:
 
 
{| class="wikitable" style="text-align:left; border="1" cellpadding="5" cellspacing="0" 
 
| rowspan="2" | Connection Type
 
| Committers
 
| :ext:
 
|-
 
| Anon access
 
| :pserver:
 
|-
 
| colspan="2" | Host
 
| dev.eclipse.org
 
|-
 
| colspan="2" | Repository Path
 
| /cvsroot/technology
 
|-
 
|}
 
 
This information should be entered in the "Checkout from CVS" dialog as follows:
 
 
[[Image:saml2idp-setup3.png|thumb|none|Checkout from CVS]]
 
 
Click "Use an existing module" to see a list of modules available for checking out.
 
 
In order to build the SAML2 IdP Server, you need to check out the following projects:
 
 
* org.eclipse.higgins/app/org.eclipse.higgins.saml2idp.server
 
* org.eclipse.higgins/plugins/org.eclipse.higgins.configuration.api
 
* org.eclipse.higgins/plugins/org.eclipse.higgins.configuration.common
 
* org.eclipse.higgins/plugins/org.eclipse.higgins.configuration.xml
 
* org.eclipse.higgins/plugins/org.eclipse.higgins.configuration.xrds
 
* org.eclipse.higgins/plugins/org.eclipse.higgins.idas.api
 
* org.eclipse.higgins/plugins/org.eclipse.higgins.idas.common
 
* org.eclipse.higgins/plugins/org.eclipse.higgins.cp.jndi
 
* org.eclipse.higgins/plugins/org.eclipse.higgins.idas.registry
 
* org.eclipse.higgins/plugins/org.eclipse.higgins.idas.spi
 
* org.eclipse.higgins/plugins/org.eclipse.higgins.messages
 
* org.eclipse.higgins/plugins/org.eclipse.higgins.saml2idp.saml2
 
* org.eclipse.higgins/plugins/org.eclipse.higgins.util.idas.cp
 
* org.eclipse.higgins/plugins/org.eclipse.higgins.util.jscript
 
* org.eclipse.higgins/plugins/org.eclipse.higgins.util.socket
 
 
If you also want to use the Test RP, you need to check out the following:
 
 
* org.eclipse.higgins/app/org.eclipse.higgins.saml2idp.test
 
* org.eclipse.higgins/plugins/org.eclipse.higgins.saml2idp.saml2
 
 
Select them all and click "Finish". They will be checked out as projects into your Eclipse workspace.
 
 
An alternative way of checking out these projects from CVS is to use the following Team Project Sets:
 
 
* [http://dev.eclipse.org/viewcvs/index.cgi/org.eclipse.higgins/app/org.eclipse.higgins.saml2idp.server/saml2idp-server-anonymous-with-depends.psf?root=Technology_Project&view=co  Team Project Set for SAML2 IdP Server web application]
 
* [http://dev.eclipse.org/viewcvs/index.cgi/org.eclipse.higgins/app/org.eclipse.higgins.saml2idp.test/saml2idp-test-anonymous-with-depends.psf?root=Technology_Project&view=co  Team Project Set for SAML2 IdP Test web application]
 
 
A Team Project Set contains CVS information and a list of projects. To import a Team Project Set, click File -> Import. In the import source list, select Team -> Team Project Set. Select a Team Project Set file (.psf) and click "Finish". All projects contained in that set will be checked out.
 
 
After checking out the projects either manually or using the Team Project Sets, your workspace should look like this:
 
 
[[Image:saml2idp-setup4.png|thumb|none|Checked out Higgins projects]]
 
 
Note that it contains several build errors, since third party libraries are not stored in the Eclipse CVS. These have to be downloaded manually according to the [[Components]] page.
 
 
First, the third party libraries for the plugin projects have to be downloaded and installed into the lib/ folders of the respective projects. Plugin projects are all projects except the web applications (saml2idp.server and saml2idp.test). For example, after installing libraries for configuration.common and configuration.xml, these projects should build without errors:
 
 
[[Image:saml2idp-setup5.png|thumb|none|Projects build after libraries have been placed into lib/]]
 
 
After the libraries of all plugin projects have been installed, your workspace should look like this:
 
 
[[Image:saml2idp-setup6.png|thumb|none|All libraries have been installed]]
 
 
<span id="buildjars"></span>Next step is to build .jar files from the plugin projects. To do this, add an Ant view to the Eclipse workspace. Click Window -> Show View -> Other. Select Ant -> Ant and click "OK". The Ant view should appear in the workspace. You can drag it around in the workspace. Now for all plugin projects, find the "build.xml" file and drag it into the Ant view. Then your workspace should look like this:
 
 
[[Image:saml2idp-setup7.png|thumb|none|Getting ready to build plugin projects]]
 
 
Now, run the "jar" build target for all the Ant scripts. This will create .jar files in the build/lib folders of the plugin projects. For example, the configuration.xml project should then contain the file build/lib/higgins-configuration-xml_0.9.0.jar. You may need to right-click on the project and hit "Refresh" (F5) before you see the file.
 
 
[[Image:saml2idp-setup8.png|thumb|none|Building the plugin project .jar files]]
 
 
We are almost done. Now the only remaining step is to copy the plugin .jar files PLUS their third party dependencies to the WebContent/WEB-INF/lib folders of the two web application projects.
 
 
In total, this means that the WebContent/WEB-INF/lib/ folder of the saml2idp.server project should contain the following files:
 
 
<pre>
 
axiom-api-1.2.jar
 
axiom-impl-1.2.jar
 
bandit-jndi-0.2.1030.jar
 
bandit-misc-0.2.1030.jar
 
commons-codec-1.3.jar
 
commons-logging-1.0.4.jar
 
dom4j-1.6.1.jar
 
higgins-configuration-api_0.9.0.jar
 
higgins-configuration-common_0.9.0.jar
 
higgins-configuration-xml_0.9.0.jar
 
higgins-configuration-xrds_0.9.0.jar
 
higgins-idas-api_0.9.0.jar
 
higgins-idas-common_0.9.0.jar
 
higgins-idas-cp-jndi_0.9.0.jar
 
higgins-idas-registry_0.9.0.jar
 
higgins-idas-spi_0.9.0.jar
 
higgins-messages_0.9.0.jar
 
higgins-saml2idp-saml2_0.9.0.jar
 
higgins-util-idas-cp_0.9.0.jar
 
higgins-util-jscript_0.9.0.jar
 
higgins-util-socket_0.9.0.jar
 
js.jar
 
ldap.jar
 
log4j-1.2.13.jar
 
openxdas-0.5.257.jar
 
openxri-client.jar
 
openxri-syntax.jar
 
stax-api-1.0.1.jar
 
wstx-asl-3.0.1.jar
 
xalan-2.6.0.jar
 
xercesImpl.jar
 
xml-apis.jar
 
xmlsec-1.4.0.jar
 
</pre>
 
 
And the WebContent/WEB-INF/lib/ folder of the saml2idp.test project should contain these:
 
 
<pre>
 
commons-codec-1.3.jar
 
commons-logging-1.0.4.jar
 
higgins-saml2idp-saml2_0.9.0.jar
 
log4j-1.2.13.jar
 
xalan-2.6.0.jar
 
xercesImpl.jar
 
xmlsec-1.4.0.jar
 
</pre>
 
 
Now the workspace should be without errors. If not, try cleaning and rebuilding the workspace by clicking Project -> Clean.
 
 
[[Image:saml2idp-setup9.png|thumb|none|All dependencies have been installed]]
 
 
If you still have problems building, try right-clicking on the web application projects, select Properties, and check if the entries under "Targeted Runtimes" and "Java Build Path -> Libraries" match the server runtime (e.g. Tomcat) you are using.
 
 
==Configure the web applications==
 
 
Both web application projects (saml2idp.server and saml2idp.test) have a WebContent/conf folder that contains configuration files. These can be edited in the Eclipse workspace. They can also be edited after the web application has been deployed on a production server, however in this case the servlet container has to be restarted in order for the changes to take effect.
 
 
===Configure the SAML2 IdP===
 
 
The saml2idp.server web application project contains the following files in the WebContent/conf folder:
 
* '''application.properties''': General configuration options for the IdP.
 
* '''HigginsConfiguration.xml''': Configuration for the Higgins context to be used for authenticating users.
 
* '''privkey.der''': This is the private key used to sign SAML 2.0 messages. This can be either a DSA or RSA key. The file is expected to have a PKCS8 structure and be in DER (binary) format.
 
* '''cacert.pem''': This is the matching certificate (including a public key) for the private key. It is used for constructing the <KeyInfo> element in XML Signatures in SAML 2.0 messages. The file is expected to have a X509 structure and be in PEM (ascii) format.
 
 
The private key and certificate files can be created using [http://www.openssl.org/ OpenSSL]. See below for a very quick start for creating these files.
 
 
The '''application.properties''' file contains the following options:
 
* ''saml2-issuer'': This is a human readable string that will be put into the <Issuer> element of SAML messages.
 
* ''saml2-assertion-validity-millis'': This is used to construct the value of the NotOnOrAfter attribute of the <Conditions> element of SAML messages.
 
 
The '''HigginsConfiguration.xml''' configures the Higgins IdAS context to be used for authenticating users. By default, an LDAP context is used. You may want to edit several settings in this file:
 
* The setting ''Address'' holds the URL of the LDAP server (e.g. "ldap://localhost:389")
 
* The setting ''java.naming.security.principal'' holds the DN of the principal to bs used to connect to the LDAP server (e.g. "cn=Manager,dc=parityinc,dc=net")
 
* The setting ''java.naming.security.credentials'' holds the password of the principal to be used to connect to the LDAP server (e.g. "secret")
 
* The setting ''consumerSubjectIDToProvider'' contains a JavaScript to transform usernames to LDAP DNs. A DN usually looks like "uid=saba,dc=parityinc,dc=net", but you only want your user to enter "saba" in the web form, therefore this little JavaScript is used to transform the name entered by the user to a full LDAP DN.
 
 
''Note: If your LDAP server does not require authentication, you can simply omit the java.naming.security.* settings from the configuration.''
 
 
===Configure the SAML2 RP===
 
 
The saml2idp.test web application project contains the following files in the WebContent/conf folder:
 
* '''application.properties''': General configuration options for the IdP.
 
* '''cacert.pem''': This is the matching certificate (including a public key) for the private key. It is used to verify XML Signatures in SAML 2.0 messages received from the IdP. The file is expected to have a X509 structure and be in PEM (ascii) format.
 
 
The private key and certificate files can be created using [http://www.openssl.org/ OpenSSL]. See below for a very quick start for creating these files.
 
 
The '''application.properties''' file contains the following options:
 
* ''saml2-idp-endpoint'': This is the URL of the IdP endpoint.
 
* ''saml2-rp-endpoint'': This is the URL of the RP endpoint.
 
* ''saml2-providername'': This is a human readable string that will be put into the ProviderName attribute of a <AuthnRequest> SAML message.
 
* ''saml2-issuer'': This is a human readable string that will be put into the <Issuer> element of SAML messages.
 
 
==Run the web applications from within Eclipse==
 
 
To test the web applications, you can run them directly on your localhost from within Eclipse. To do so, follow these steps:
 
 
1. Make sure the Java EE perspective is open. Click Window -> Open Perspective -> Other. Select "Java EE".
 
 
2. Open the "Server" view. Click Window -> Show View -> Servers.
 
 
''Note: Now if you already see a server in the Server view, you can omit the following three steps. Instead, right-click on the server and click "Add and remove projects.". Then proceed with step 6.''
 
 
3. Right-click on the Server view and click New -> Server.
 
 
4. Select the server type and runtime you want to use. This should be the same as the one you configured when you set up your workspace.
 
 
5. Click "Next".
 
 
[[Image:saml2idp-setup12.png|thumb|none|Create a new server]]
 
 
6. You are now asked to add web application projects to be deployed on the server. In the "Available projects" list there should be two projects (or only one if you did not download the test RP project).
 
 
7. Click "Add All".
 
 
[[Image:saml2idp-setup13.png|thumb|none|Add projects to the server]]
 
 
You should now see the new server in the Server view. If you double-click on it, you can further configure it. One setting you may want to check is the HTTP/1.1 TCP Port (set this to 80).
 
 
[[Image:saml2idp-setup14.png|thumb|none|Further server configuration]]
 
 
You can now start the server. Right-click on the server in the Server view and click "Start". Some logging information should appear in the Console view, and the server should be running.
 
 
Try accessing http://localhost/org.eclipse.higgins.saml2idp.test/
 
 
[[Image:saml2idp-setup15.png|thumb|none|The Test RP running on localhost]]
 
 
==Export the web applications to .WAR files==
 
 
Deploying a web application on a production server usually requires a .WAR (web archive) file. If you followed section 3.1 on this page, you already have such files and can immediately deploy them, however in this case you will have to edit the configuration files directly on your production machines after the applications are deployed, as opposed to editing them in Eclipse beforehand.
 
 
If you want to create a .WAR file from the web applications in your Eclipse workspace, you can right-click on the project, then click Export -> WAR file. Enter a destination file name and click "Finish".
 
 
[[Image:saml2idp-setup16.png|thumb|none|Exporting a .WAR file]]
 
 
==Deploy the web applications on Tomcat==
 
 
Deploying a .WAR file on Tomcat is usually done by placing the file into the webapps/ directory of Tomcat. Under the default configuration, it will be auto-deployed (i.e. decompressed into a context subdirectory). By default, the name of the .WAR file directly maps to the name of the context, which also becomes part of the URL under which the context can be accessed.
 
 
For example, if you are running Tomcat at your website '''www.example.com''', and you place the file '''org.eclipse.higgins.saml2idp.server.war''' in the '''webapps/''' directory, it will be auto-deployed to the '''webapps/org.eclipse.higgins.saml2idp.server''' context subdirectory, and becomes available at the URL '''http://www.example.com/org.eclipse.higgins.saml2idp.server/'''. The SAML endpoint servlet will be at '''http://www.example.com/org.eclipse.higgins.saml2idp.server/SAMLEndpoint''', and the logout servlet will be at '''http://www.example.com/org.eclipse.higgins.saml2idp.server/Logout'''.
 
 
It may be a good idea to rename the .WAR file before deploying it (e.g. to '''saml2idp-server.war''') for prettier URLs.
 
 
Please refer to the documentation of Tomcat or your other servlet container for more information on how to deploy web applications.
 
 
==Notes on OpenLDAP and OpenSSL==
 
 
This section contains various other helpful information for getting started with the Higgins SAML2 IdP. OpenLDAP can be used as the backend of the Higgins JNDI context provider, and OpenSSL can be used to create the keys used to sign/verify SAML 2.0 assertions.
 
 
===OpenLDAP quick start===
 
 
http://www.openldap.org/
 
 
LDAP TCP port: '''389'''
 
 
Check if the LDAP server is running: '''ps -e -f|grep slapd'''
 
 
Stop the LDAP server: '''kill -INT `cat /usr/local/var/run/slapd.pid`'''
 
 
Start the LDAP server: '''/usr/local/libexec/slapd'''
 
 
Location of the LDAP server configuration file: '''/usr/local/etc/openldap/slapd.conf'''
 
 
How to search for all entries: '''ldapsearch -x -b 'dc=parityinc,dc=net' '(objectclass=*)''''
 
 
How to create user '''saba''' with password '''testpass''':
 
 
* Create a file named saba.ldif:
 
<pre>
 
dn: uid=saba,dc=parityinc,dc=net
 
objectclass: inetOrgPerson
 
objectClass: person
 
uid: saba
 
cn: Markus Sabadello
 
givenname: Markus
 
sn: Sabadello
 
userPassword: testpass
 
</pre>
 
 
* Add the entry: '''ldapadd -x -D "cn=Manager,dc=parityinc,dc=net" -W -f saba.ldif'''
 
 
How to delete user saba: '''ldapdelete -x -D "cn=Manager,dc=parityinc,dc=net" -W "uid=saba,dc=parityinc,dc=net"'''
 
 
===OpenSSL quick start===
 
 
http://www.openssl.org/
 
 
How to generate a DSA private key without password: (this also automatically generates the public key):
 
 
<pre>
 
openssl dsaparam -out dsaparam.pem 2048
 
openssl gendsa -out privkey.pem dsaparam.pem
 
</pre>
 
 
How to convert the private key to PKCS8 structure and DER format:
 
 
<pre>
 
openssl pkcs8 -topk8 -nocrypt -in privkey.pem -outform der -out privkey.der
 
</pre>
 
 
How to generate a self-signed certificate in X509 structure and PEM format:
 
 
<pre>
 
openssl req -new -x509 -key privkey.pem -out cacert.pem -days 1095
 
</pre>
 
 
==Setting up OpenLDAP with TLS (SSL)==
 
 
This section explains how to 1) set up the OpenLDAP server with TLS support, and 2) how to configure the Higgins JNDI context provider to use a TLS connection to the server.
 
 
Reference links:
 
* http://www.openldap.org/faq/data/cache/185.html
 
* http://www.openldap.org/doc/admin24/tls.html
 
 
===How to configure OpenLDAP for TLS===
 
 
'''1. Create a certificate request and private key for the server. The common name on the certificate must match the full hostname of the server.'''
 
 
<pre>
 
openssl req -new -nodes -keyout newreq.pem -out newreq.pem
 
</pre>
 
 
'''2. Create a certificate from the certificate request. This can be done by a commercial certificate authority, or by creating your own like this:'''
 
 
'''2.a. Create your own certificate authority:'''
 
 
<pre>
 
cd /var
 
mkdir myca
 
cd myca
 
/usr/share/ssl/misc/CA.pl -newca
 
</pre>
 
 
''Note: When asked for "CA certificate filename", press enter; Then specify a password and information about your private CA.''
 
 
'''2.b. Use your own certificate authority to create a certificate from the certificate request:'''
 
 
<pre>
 
/usr/share/ssl/misc/CA.pl -sign
 
</pre>
 
 
''Note: Enter the password you specified when creating the CA.''
 
 
'''3. Install the certificate, the private key, and the trusted certificate of the CA:'''
 
 
<pre>
 
cp ./demoCA/cacert.pem /usr/local/etc/openldap/cacert.pem
 
mv ./newcert.pem /usr/local/etc/openldap/servercrt.pem
 
mv ./newreq.pem /usr/local/etc/openldap/serverkey.pem
 
chmod 600 /usr/local/etc/openldap/serverkey.pem
 
</pre>
 
 
'''4. Configure the OpenLDAP server to use these files:'''
 
 
Add the following lines to /usr/local/etc/openldap/slapd.conf:
 
 
<pre>
 
TLSCACertificateFile /usr/local/etc/openldap/cacert.pem
 
TLSCertificateFile /usr/local/etc/openldap/servercrt.pem
 
TLSCertificateKeyFile /usr/local/etc/openldap/serverkey.pem
 
</pre>
 
 
'''5. Optional: Configure the OpenLDAP client applications to use the server certificate:'''
 
 
Add the following line to /usr/local/etc/openldap/lapd.conf:
 
 
<pre>
 
TLS_CACERT /usr/local/etc/openldap/cacert.pem
 
</pre>
 
 
'''6. Stop the LDAP server:'''
 
 
<pre>
 
kill -INT `cat /usr/local/var/run/slapd.pid`
 
</pre>
 
 
'''7. Start the LDAP server with a special parameter to make it answer to TLS requests:'''
 
 
<pre>
 
/usr/local/libexec/slapd -h "ldaps:/// ldap:///"
 
</pre>
 
 
'''8. Optional: Use OpenSSL to check if the OpenLDAP server correctly listens to TLS requests, and to see its certificate:'''
 
 
<pre>
 
openssl s_client -connect localhost:636
 
</pre>
 
 
'''9. Optional: Use the OpenLDAP client applications to access the OpenLDAP server via TLS:'''
 
 
<pre>
 
ldapsearch -H "ldap://localhost:389" -x -b 'dc=parityinc,dc=net' '(objectclass=*)'
 
ldapsearch -H "ldaps://localhost:636" -x -b 'dc=parityinc,dc=net' '(objectclass=*)'
 
ldapsearch -ZZ -H "ldap://localhost:389" -x -b 'dc=parityinc,dc=net' '(objectclass=*)'
 
</pre>
 
 
''Note: The first command uses a plain text connection. The second uses the SSL port 636. The third uses the StartTLS extension.''
 
 
===How to configure the Higgins SAML2 IdP accordingly===
 
 
In order for the SAML2 IdP to be able to connect to an LDAP server using TLS, it needs to trust the server's CA.
 
 
'''1. Import the certificate of the server's CA into a Java keystore file, using the keytool provided with JDKs:'''
 
 
<pre>
 
keytool -keystore ldapks.jks -import -file cacert.pem -alias cacert
 
</pre>
 
 
''Note: Choose any password for the keystore.''
 
 
'''2. Change the relevant sections of the HigginsConfiguration.xml file to use the StartTLS mechanism and the keystore file:'''
 
 
<pre>
 
<Setting Name="AddressList" Type="htf:list">
 
  <Setting Name="Address" Type="xsd:string">ldap://graceland.parityinc.net:389</Setting>
 
</Setting>
 
<Setting Name="env" Type="htf:map">
 
  <Setting Name="java.naming.security.authentication" Type="xsd:string">none</Setting>
 
  <Setting Name="java.naming.ldap.attributes.binary" Type="xsd:string">guid</Setting>
 
  <Setting Name="org.eclipse.higgins.idas.cp.jndi.startTLS" Type="xsd:string">true</Setting>
 
  <Setting Name="org.eclipse.higgins.idas.cp.jndi.trustStore" Type="xsd:string">/opt/tomcat/webapps/saml2idp-server/conf/ldapks.jks</Setting>
 
</Setting>
 
</pre>
 
 
''Note: The hostname in the ldap:// URI must match the name in the LDAP server's certificate (i.e. use the real hostname, not localhost).''
 
 
''Note: This uses no authentication to connect to the server. If authentication is required, see step 3''
 
 
'''3. (Optional, depends on server configuration) Connect with authentication:'''
 
 
If the server requires the client to authenticate in order to connect, the above configuration has to be changed like this:
 
 
<pre>
 
<Setting Name="AddressList" Type="htf:list">
 
  <Setting Name="Address" Type="xsd:string">ldap://graceland.parityinc.net:389</Setting>
 
</Setting>
 
<Setting Name="env" Type="htf:map">
 
  <Setting Name="java.naming.security.authentication" Type="xsd:string">simple</Setting>
 
  <Setting Name="java.naming.security.principal" Type="xsd:string">cn=usr,dc=company</Setting>
 
  <Setting Name="java.naming.security.credentials" Type="xsd:string">secret</Setting>
 
  <Setting Name="java.naming.ldap.attributes.binary" Type="xsd:string">guid</Setting>
 
  <Setting Name="org.eclipse.higgins.idas.cp.jndi.startTLS" Type="xsd:string">true</Setting>
 
  <Setting Name="org.eclipse.higgins.idas.cp.jndi.trustStore" Type="xsd:string">/opt/tomcat/webapps/saml2idp-server/conf/ldapks.jks</Setting>
 
</Setting>
 
</pre>
 

Latest revision as of 19:16, 25 April 2008

Back to the top