View Source

Server Credentials & PKI

Shibboleth uses server PKI at three distinct points in the flows. The first is used by SSL to authenticate the authentication service protecting the SSO handler to the browser. This is defined in Apache's configuration(httpd.conf) for the main SSL port, 443. The initial authentication assertion is signed by use of a certificate defined in the <Credentials> element of IdP.xml. The attribute query handler is also protected by SSL, but usually on a separate port or server. A different set of SSL credentials may also be used to protect the attribute query handler for several reasons; bugs within Tomcat and Apache's SSL implementations, the difference in server types, and because federations and web browsers may have different sets of trusted roots. However, in many situations, one set of credentials can be used for all three purposes.

Example usage:

<Credentials xmlns="urn:mace:shibboleth:credentials:1.0">
	<FileResolver Id="mycerts">
		<Key>
			<Path>file:/usr/local/shibboleth-idp/etc/supervillain.key</Path>
		</Key>
		<Certificate>
			<Path>file:/usr/local/shibboleth-idp/etc/supervillain.crt</Path>
		</Certificate>
	</FileResolver>
</Credentials>

<Credentials xmlns="urn:mace:shibboleth:credentials:1.0">

This element is the container for credentials used by the credential mechanism specified by the IdPConfig element. It must contain one FileResolver element for flat key and certificate files or one KeyStoreResolver element for compound keystores.

File-Based Key and Certificate Storage

Flat-file based certificate storage and protection is by far the most straightforward and common credential storage mechanism. Shibboleth supports .pem and .der encodings. These certificate files may be easily shared by both Apache and Shibboleth in the common case where the same key and cert are used for all flows.

It is critical that these files be stored with appropriate permissions in an appropriate location. They must be readable by both Apache and Tomcat, but access should be extremely restricted beyond that. Any compromise of these files represents a compromise of your entire Identity Provider. Revoke the certificate immediately.

<FileResolver Id="string">

This element defines a pair of files used to store a private key and certificate associated with a given identifier and is contained by the Credentials element. RelyingParty elements will refer to these identifiers allowing multiple resolver elements to be used to specify different credential storage for different federations or service providers. It must contain one Key element and should contain one Certificate element.

<Certificate>

This specifies the certificate corresponding to this set of credentials. Certificates are supported in a variety of automatically detected formats: DER, PEM, PKCS8, PKCS12, and all associated encrypted forms. The certificate itself must be referred to using a Path element contained by this element. If this certificate isn't self-signed or signed by a root familiar to the service provider, the files of certificates in the path to the root may be specified using one or more CAPath elements. It resides within the FileResolver element and must be paired with the corresponding private key using the Key element. An optional type attribute can explicitly force a format if needed.

<Key password="password">

This specifies the file containing a private key to be used by a set of credentials. Keys are supported in a variety of automatically detected formats: DER, PEM, PKCS8, PKCS12, and all associated encrypted forms. For encrypted keys, the password may be specified by adding an optional password attribute to this element. It resides within the FileResolver element, should be paired with a Certificate element, and contain a Path element. An optional type attribute can explicitly force a format if needed.

<CAPath>pathname</CAPath>

Paired with a Path element and contained by a FileResolver element, this element allows for the specification of additional certificates in the chain up to the trust anchor. As many CAPath elements as necessary to complete the chain may be specified. The expectations of the service provider and the federation may determine the necessity for the use of this field.

<Path>pathname</Path>

This mandatory element specifies the path to a file or directory utilized by other elements of the configuration. It may be contained by various elements to point to different types of files required by the !IdP.

Java Keystore Access Configuration

Java keystores provide a native, integrated way to store credentials for use by the Shibboleth !IdP, Java-based authentication, and other Java applications. This storage mechanism may be preferred when attempting to run Shibboleth primarily through Java, or other applications need to share the same credentials. These certificates cannot be directly used by Apache for SSL protection of the protocol handlers, and using Tomcat to protect the attribute query handler is problematic for several reasons. Shibboleth includes extkeytool to export flat-file certificates for Apache as well.

Be aware that Java keystores have not always maintained backwards -- or forwards -- version compatibility when Java's security libraries are updated. This may cause inspecific failures to load certificates, and is remedied by exporting all information in the keystore and re-importing it to a brand new keystore created by the same JDK as will be processing it.

<KeyStoreResolver Id="string" storeType="type">

This element is contained by the Credentials element to specify a keystore that contains both the certificate and private key for a given set of credentials. Typically, this will be a Java keystore, with a corresponding type of JKS . RelyingParty elements will refer to the Id allowing multiple resolver elements to be used to specify different credential storage for different federations or service providers. It must contain one Path element, one KeyAlias element, and one StorePassword element; it may optionally contain a KeyPassword element or a CertAlias element.

<CertAlias>string</CertAlias>

Specifies the alias for the certificate corresponding to the private key. If no alias is specified, defaults to the private key's alias. Contained by the KeyStoreResolver element.

<KeyAlias>string</KeyAlias>

Specifies the alias used for accessing the private key. Contained by the KeyStoreResolver element.

<KeyPassword>string</KeyPassword>

Specifies the password used to retrieve the private key. Contained by the KeyStoreResolver element.

<StorePassword>string</KeyStorePassword>

Specifies the password to access the keystore containing the private key to be used for symmetric encryption. Contained by the NameMapping element when a CryptoHandleGenerator type is specified.

<Path>pathname</Path>

This mandatory element specifies the path to a file or directory utilized by other elements of the configuration. It may be contained by various elements to point to different types of files required by the !IdP.

Apache SSL Credential Configuration

SSL protection is used at two points in the Shibboleth flows: between the browser user and the authentication service, and between the remote attribute requestor and the attribute query handler. The OpenSSL libraries via Apache are used by Shibboleth for SSL functionality and certificate validation. For many reasons, it is desirable to separate these two services into separate virtual hosts and/or ports:

In many cases separate sets of credentials may be desired, as one may be recognized by SP's in a federation while another is signed by a root commonly found in browsers.
Due to bugs in the Apache 2 SSL implementation, the SSLVerifyClient directive may not be declared within a <Location> block. Leaving SSLVerifyClient enabled for all flows will include that with browser users, which will confuse poorly-implemented web browsers.
There is a fundamental difference between the authentication of browser users and the attribute request flows which should be preserved in case future implementations of Shibboleth separate this further.

Shibboleth utilizes SSL protection of the flows handling attribute requests not only to protect against MITM attacks and confidentiality, but also to identify both principals in the exchange. SSLVerifyClient must be present at a level of either required or optional . Depending on configuration settings, this may be the only identity-proofing of the remote requestor that is performed by the !IdP. If this interaction is misconfigured, or one party does not recognize the other, the SP will be treated as an unauthenticated requester and will only ever be eligible to receive the base set of attributes available to everyone.

Individual certificates or a trusted root list will be distributed by federations as part of metadata.xml .

One of the most common problems encountered is a misconfigured SSLVerifyDepth . This parameter defines how many links the SSL engine will follow on a certificate chain. If this is set too shallow, often to 0 or 1 hops, trust errors will occur since it can't follow the chain back to a trusted root; an arbitrarily high number such as 10 is recommended. Even though OpenSSL doesn't perform validation of other parts of the transaction, this will still cause failure anyway.

Standard SSL protection of the SSO handler and authentication system should work with minimal changes to default Apache configuration. Ensure that the proper port and protocol(=http*s*://=) are being referenced in relying party metadata.

extkeytool

The JDK includes the command line program keytool for managing Java keystores. This utility cannot import or export private key information, making it difficult to use the same private key and certificate for Apache and Java-based applications. The Shibboleth distribution includes extkeytool , a program that can be used in conjunction with keytool to perform these tasks. Select the appropriate step-by-step procedure for your situation from the following guides. Before running extkeytool , the variable SHIB_HOME must be set to the path to the directory where the Shibboleth tarball was exploded(typically =/opt/shibboleth-idp-1.3c-install/=).

If you have a pre-exiting RSA key/certificate combination in a keystore and you would like to use it with Apache

Determine the alias of the keystore keyEntry containing the key you would like to use in your Apache setup. Assuming that your keystore is named yourstore , the following command should present a list of the entries in the keystore: $ keytool -list -v -keystore yourstore

Assuming that you identified the appropriate alias as youralias and the password for the keystore is yourpass , enter the following command to export the key in Base64-encoded pkcs8 format:
$ extkeytool -exportkey -keystore yourstore -alias youralias -storepass yourpass -rfc -file yourkey.pkcs8

In order to use this key with Apache, you must convert it to PEM-encoded RSA native format. You have the option of storing the key unencrypted or encrypted:

To use the unencrypted format, enter the following command for the conversion:
$ openssl pkcs8 -in yourkey.pkcs8 -nocrypt|openssl rsa -out yourkey.key

To use the encrypted format, enter the following command for the conversion:

$ openssl pkcs8 -in yourkey.pkcs8 -nocrypt|openssl rsa -des3 -out yourkey.enckey

The following command will export the corresponding certificate.

$ keytool -export -keystore
		yourstore -alias youralias -rfc -file yourcert

Set the mod_ssl SSLCertificateKeyFile and SSLCertificateFile directives to point to the two files you have just created. Take care to remove any temporary files you created (i.e. =yourkey.pkcs8=) and set appropriate file permissions, especially if you chose to store the key in an unencrypted format.

If you have a pre-existing RSA key/certificate combination that you use with Apache and would like to import it into a java keystore

Convert the private key to unencrypted DER-encoded pkcs8 format. Assuming your PEM-encoded key is stored in a file named yourkey.enckey , enter the following command.
$ openssl pkcs8 -in yourkey.enckey -topk8 -nocrypt -outform DER -out yourkey.der.pkcs8

Create a certificate bundle file. This file should include a series of PEM-encoded X509 certificates representing a complete trust chain, from the root CA certificate to the certificate that matches your private key. If your certificate is stored in a file named mycert and the CA signer certificate is stored in a file named ca.cert , you might enter the following command to create the bundle.
$ cat mycert ca.cert > cert.bundle

Note: mod_ssl enabled Apache installations include a number of commonly recognized CA certificates in the ca-bundle.crt file under the $ServerRoot/conf/ssl.crt/ directory.

Create an empty JKS keystore.

$ keytool -genkey -keyalg RSA -alias "selfsigned" -keystore yourstore -storepass "secret" -validity 360

$ keytool -delete -alias "selfsigned" -keystore yourstore -storepass "secret"

Import the key and certificate into the keystore. Assuming you have already created a keystore named yourstore with a password of of yourpass , enter the following command to store the data under the alias youralias .
$ ./extkeytool -importkey -keystore yourstore -alias youralias -storepass yourpass -keyfile yourkey.der.pkcs8 -certfile cert.bundle -provider org.bouncycastle.jce.provider.BouncyCastleProvider

You can verify that the import was successful by listing the entries in the keystore.
$ keytool -list -v -keystore yourstore -alias youralias

Remember to delete yourkey.der.pkcs8 , as it contains your unencrypted private key.

If you are starting from scratch and do not yet have a certificate/key pair

Generate an RSA private key. Use the command below, substituting yourkey with an appropriate name to use to refer to the key.
$ openssl genrsa -des3 -out yourkey.enckey 1024

The following command generates a Certificate Signing Request, which should be communicated to a Certificate Authority.
$ openssl req -new -key yourkey.enckey

The Certificate Authority should respond with a PEM-encoded X509 certificate. Set the mod_ssl !SSLCertificateKeyFile directive to point to the key file you just created and the SSLCertificateFile directive to point to the file containing the certificate issued by the Certificate Authority. Previous sections explaion how to share the key/certificate pair with a Java keystore.