|
|
| (19 intermediate revisions by 4 users not shown) |
| Line 1: |
Line 1: |
| − | This page describes how to deploy and configure 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 deploy and configure the two web applications. See [[SAML2 IdP Overview]] for more information on how the deployed web applications interact with each other, and see [[SAML2 IdP Development]] for information on how to check out and build the source code of the involved Higgins components.
| |
| − |
| |
| − | ==Prerequisites==
| |
| − |
| |
| − | This guide assumes you have the following software:
| |
| − | * Apache Tomcat 5.5 or later (or other servlet container)
| |
| − | * JDK/JRE 1.4 or later
| |
| − |
| |
| − | ==Obtain .WAR files==
| |
| − |
| |
| − | Two .WAR files (one for the IdP, one for the RP) are automatically built every night and can be downloaded on these pages:
| |
| − |
| |
| − | http://www.eclipse.org/higgins/ver2/downloadsnew.php?loc=downloads/saml2idp.server
| |
| − | (for installing the SAML2 IdP)
| |
| − |
| |
| − | http://www.eclipse.org/higgins/ver2/downloadsnew.php?loc=downloads/saml2idp.test (for installing the SAML2 Test RP)
| |
| − |
| |
| − | Click on the Build ID in the "Latest build" row. Download the "war.zip" file and decompress it.
| |
| − | ==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.
| |
| − |
| |
| − |
| |
| − | ==Configure the web applications==
| |
| − |
| |
| − | Both web applications (saml2idp.server and saml2idp.test) have a conf/ folder that contains configuration files. These can be edited after the web application has been deployed on a production server. Note that the servlets have 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.
| |
| − | * ''accept-acs-urls'': This contains a comma-delimited list of ACS URLs that are accepted by the IdP. If a request with an unknown ACS URL is received, the server returns a HTTP 403 Forbidden reply. If the value of this option is "*", all ACS URLs are accepted.
| |
| − | * ''extract-username-parameter-name'': If the value of this option is not empty, then for every incoming authentication request the SAML2 IdP checks if a parameter with that name exists in the request. If yes, then the value of that field is considered to be a username that is already authenticated.
| |
| − | * ''extract-username-header-name'': If the value of this option is not empty, then for every incoming authentication request the SAML2 IdP checks if a header with that name exists in the request. If yes, then the value of that field is considered to be a username that is already authenticated.
| |
| − | * ''extract-username-cookie-name'': If the value of this option is not empty, then for every incoming authentication request the SAML2 IdP checks if a cookie with that name exists in the request. If yes, then the value of that field is considered to be a username that is already authenticated.
| |
| − |
| |
| − | ''Note:'' The last three options are part of the "Username Extraction" feature, which makes it possible to have the SAML2 IdP issue authentication statements for usernames it does not authenticate itself. If any of the three options is set, and if a parameter/header/cookie with that name is present in a request, then the value of that field is considered to be a username, for which an authentication statement will be issued without any further checks. This is an additional feature of the Higgins SAML2 IdP and not part of SAML 2.0 specifications.
| |
| − |
| |
| − | 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.
| |
| − |
| |
| − | ==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>
| |
| − |
| |
| − | ==Further information==
| |
| − |
| |
| − | For information on how to check out and build the source code of the involved Higgins components, see here: [[SAML2 IdP Development]]
| |
