Using Custom Keystore for Web Services Message Level Security
A keystore is a protected database, or a storage facility for keys, that holds cryptographic keys and certificates for an enterprise. Access to a keystore is guarded by a password (defined at the time the keystore is created). In addition, each private key in a keystore can be guarded by its own password.
Keystores may have different types of entries. The two most applicable entry types for a keytool include:
- Key entries - each holds very sensitive cryptographic key information, which is stored in a protected format to prevent unauthorized access. Typically, a key stored in this type of entry is a secret key, or a private key accompanied by the certificate "chain" for the corresponding public key.
- Trusted certificate entries - each contains a single public key certificate belonging to another party. It is called a "trusted certificate" because the keystore owner trusts that the public key in the certificate indeed belongs to the identity identified by the "subject" (owner) of the certificate. The issuer of the certificate vouches for this, by signing the certificate.
Contents
To follow this tutorial, you need the following software and resources.
This tutorial also requires the Identity plugin for NetBeans IDE. Open the Update Center (Tools > Plugins) and look for the Identity plugin, under Web and Java EE.
Before taking this tutorial, you should take the Securing Web Services Using the SAML or UserNameToken Profiles tutorial.
Message Level Security on Web Service Providers and Web Service Clients
The NetBeans IDE Identity plugin enables developers to provide Message Level security on Web Service Provider (WSP) and Web Service Clients (WSC) on the Java Application Server SDK Access Manager. The Message Level security enables the use of these two types of token profiles, as well as others:
- WS-I Basic Security Profile (BSP- based token profiles; namely, SAML_SenderVouches, SAML_HolderOfKey, X509 and UserNameToken).
- Liberty ID-WSF-specific token profiles; namely, LibertySAML, LibertyBearer, and LibertyX509.
The NetBeans Identity tools enable you to sign the security token or the response through certificate settings that are exposed in the WSP and WSC security wizards, as in the following screenshot of the wizard for the certificate settings used by the WSP.
Here, by default, the Use Default Keystore option is selected. With this option, the WSP will use the keystore that is bundled with the Access Manager.
The Default Keystore
There are two keystore files bundled in the Access Manager server:
- amclientkeystore.jks The Client SDK uses this file, which is eventually used by the Authentication Providers at WSC and WSP.
- amserverkeystore.jks This is the server's keystore file. The Access Manager-hosted Liberty discovery service uses this file to generate the security tokens and sign/verify the request/response messages.
The keystore is available after Identity plugin installation. The keystore is pre-populated with key aliases that the Access Manager server and the Client SDK use to:
- Sign the security token (SAML, X509 and Liberty by default)
- Sign the response from WSP and verify the response at WSC
- With the WSC, make the Liberty Discovery service query for the WSP service offerings stored in the trusted authority.
- Sign the Liberty security profiles by the Liberty Discovery service
The default keystore contains the following pre-populated aliases:
- amclient. Used by the WSC/WSP when the outbound SOAP message has to be signed
- amserver. Used by the Discovery Service aka Trusted Authority to create security tokens. The WSP validates this key by using its public key.
The IDE communicates with the Access Manager Server by using the Access Manager Client SDK.
The Access Manager Client SDK is initialized with the properties to talk to the server through a file called AMConfig.properties. This client SDK properties file is installed by default at /addons/accessmanager/AMConfig.properties.
AMConfig.properties Properties that Relate to Keystore Settings
The relevant properties in the AMConfig.properties file that relate to the keystore settings and which are used by the ClientSDK/Authentication Provider runtime are:
- com.sun.identity.liberty.ws.wsc.certalias=amclient
- com.sun.identity.liberty.ws.trustedca.certaliases=LIBERTY_TRUSTEDCA_ALIASES
The com.sun.identity.liberty.ws.wsc.certalias property is used by the Web service client/Web services providers for any outbound SOAP message that needs to be signed using Liberty's X509Token. For example, this property is used by the web services client when it queries for the discovery service for the service offering, and at the same time, the same property is used when it is trying to talk to WSP with X509 token profile.
The WSP uses the com.sun.identity.liberty.ws.trustedca.certaliases property to identify its trusted authorities and their public keys. For example, when we say value for this property as amserver:localhost , it is trusting the localhost 's discovery service whose public key is amserver .
Using Keystore Settings
Within the Identity plugin, you can use keystore settings for the following:
- Sign token profiles when they are sent in a SOAP Header.
Token profiles, as defined by their specifications, need to be signed when sent in a SOAP Header. For example, the SAML specification states that the SAML assertions sent in a SOAP Header should always be signed.
- Sign the response that is sent from the Web Service Provider to the Web Service Clients.
The Identity plugin tooling also enables users to sign the response that is sent from the WSP to the WSC. This feature signs the full SOAP message (both the Header and Body) and enables the WSC to verify the signature before accepting the response from the WSP.
Using Custom Keystores for WSI-BSP Token Profiles and Liberty Token Profiles
To use WSI-BSP token profiles with custom keystores.
- Ensure that you have an existing keystore and that required key aliases are populated.
- In the Runtime window, open the profile. See the figure below.
- In the Certificate Settings section, perform the following steps. Note that none of the values entered can be null.
- Clear the Use Default Key Store checkbox, which is selected by default.
- In the text fields following the checkbox, type the following:
- The full path to obtain the keystore file. The only supported keystore format is JKS.
- The password for the keystore.
- The key alias to be used by the WSP for signing response or to sign the security token.
- The password for the key alias. Enter a valid value even if it is same as the keystore password.
- Click OK to submit changes.
- Open the WSC security panel. Perform the same steps above to add the custom keystore details to be used by the WSC.
- Deploy the client and run the application.
- The WSC and WSP will use the custom keystore specified by the user.
Using Custom Keystores for Liberty Token Profiles
To use custom keystores for Liberty Token Profiles:
You should have an existing keystore with the required key aliases populated. This keystore should be accessible locally (physically located where the application server is installed) for the application server runtime.
- Open the required Liberty Token Profile in the Runtime window.
- Use the same settings for a custom keystore as outlined in the previous section.
- Open the WSC security panel. Perform the same steps as above to add the custom keystore details to be used the WSC.
- To use a custom keystore for the Liberty Token Profile, you must perform additional configuration as described in the IDE's Online help topic "Using a Custom Keystore for the Liberty Token Profile."
- Run the Liberty enabled WSC.
It now uses the custom keystore specified by the developer.
The custom keystore specified by the user is effective for the Application Server instance. All deployed applications on that instance should use the same keystore setup.
See Also
See the following document for a description of keytool usage.
top
