Note: The replaces the older keystore-only configuration. It is much better because this allows you to wrap passwords in XML CDATA sections. The older keystore configuration used attributes in the tag which meant that many passwords could not be specified.
This element is used by any component that requires a Secure Socket Layer (SSL) connection to server. Typically, a client of another machine (such as an OA4MP server that has a client certificate to use a MyProxy server) will configure the keystore section. A connection to another machine (such as to an LDAP server) requires a trust store. It is beyond the scope of this document to discuss these in detail.
This consists of either a truststore or keystore (or both) as needed. Either store is a collection of certificates and certificate chains. OA4MP uses SSL for a variety of things. An OA4MP server is a client to a MyProxy server, or possibly an LDAP server, hence it requires a keystore. An OA4MP client may need a specific truststore to connect to an OA4MP server that has a self-signed cert. These are the frequently occurring examples.
| Name | Required | Default | |
| debug | N | false | Enabled low-level SSL debugging. This is not the same as enabling debugging for the server and will tell the SSL layer to print out everything it is doing, which is usually a huge amount of information. This is equivalent to setting the Java system property javax.net.debug to true. |
| useJavaTrustStore | N | true | Use the default Java trust store (which normally resides at $JAVA_HOME/lib/security/cacerts) in addition to the one given in the path. If this element is omitted it is the same as setting this option to "true". Generally, if this is disabled then no commercial certificates will be recognized by SSL. This might be useful in certain cases, but should probably be enabled (i.e. omitted) unless you have good reasons otherwise. |
| useStrictHostnames | N | true | Strictly check hostnames (this is the default). Do not
set to false without an excellent reason, since this creates a security
hole. The reason this exists is that sometimes during development it is necessary to
work with self-signed certs whose hostnames are not quite right.
The aim in such cases should be to get the system working while you are
waiting for your good certificates.
Under no circumstances should this ever be used in a production environment!
Generally ignore this unless you must explicitly set it. |
| useDefaultTrustManager | N | true | (optional) Use the default trust manager for Java rather than the OA4MP specific one. If there is a trustManager block, then that will be used unless this is set false. This flag is a convenience to let you toggle a custom trust manager on or off. No trustManager block means the system will, by default, try to use the default Java trust manager. |
| tlsVersion | N | -- | This will allow for setting the version of TLS used in SSL connections. The options are 1.0, 1.1 or 1.2. If this is omitted, then the default for the current version of Java (1.0 for Java 7, 1.2 for Java 8) will be used. |
A keystore provides credentials that allows a client to connect to a server.
| Name | Required | Default | |
| type | N | JKS | The type of the keystore, e.g. "PKCS12" or "JKS". |
| password | N | - | The password for the keystore |
| path | N | - | The full local path to the keystore. |
| factory | N | - | The name of the factory, e.g. SunX509, which will be used to create the key manager factory. This creates any key managers. You should generally not need to change this. |
A trust store is used to verify credentials from a server.
| Name | Required | Default | |
| type | N | JKS | The type of the truststore, e.g. "PKCS12" or "JKS". |
| password | N | - | The password for the trust store. |
| path | N | - | The full local path to the trust store. |
| certDN | N | - | The Distinguished Name (DN) to be used when connecting to a server. In this case, the Common Name (CN) is gotten from the server's certificate and checked against this for host name verification. A common situation is that you have a self-signed certificate (for your OA4MP server) with common name of localhost and you must supply the certs to connect to that from your client to get an access token, user info etc., Since the lookup for the machine usually does not return "localhost" you can set this to have the value of CN=localhost and manually use that. |
In this example for OAuth 2.0, the server specifies that the MyProxy server and an LDAP server are to be contacted via ssl. LDAP requires a truststore while MyProxy requires a client certificate that it issued be used.
<service name="myconfig">
<ldap enabled="true">
<ssl debug="false"
useJavaTrustStore="true">
<trustStore>
<path>/pt/oa2/etc/config/custom-trust-certs</path>
<password><![CDATA[sfdgfdf(*()(*]]></password>
<certDN><![CDATA[CN=localhost]]></certDN>
</trustStore>
</ssl>
<!-- Rest of LDAP config -->
</ldap>
<myproxy host="myproxy.bigstate.edu" port="7512">
<loa name="http://incommonfederation.org/assurance/silver" port="7514"/>
<loa name="openid" port="7516"/>
<ssl">
<keystore>
<path>/opt/oa2/etc/config/hostcred.pk12</path>
<password><![CDATA[QOFjkhuer73959%&]]></password>
<type>PKCS12</type>
</keystore>
</ssl>
</myproxy>
<!-- Rest of config -->
</service>
The LDAP configuration uses SSL and the assumed default Java trust store in addition to the customized trusted certificate store. The LDAP server is located on the localhost and the name of the machine was not resolving to localhost. Rather than hack DNS, the client is told to accept a common name of localhost when connecting to this particular server. The MyProxy configuration will use the given keystore that contains exactly the host certificate for the MyProxy server and nothing else.