How To Implement 2-Way SSL Using Policy Manager

Learn how to use Policy Manager to implement mutual authentication using an SSL (Secure Socket Layer) Certificate to authenticate either your business's legal name and location or, alternatively, just your domain.

Table of Contents

SSL Overview

In this section:

Identity Certificates

When a user visits your secure site, your web server will send a copy of your SSL (Secure Socket Layer) certificate to the user's web browser. The information in the certificate will always include your web site's domain name, such as www.yourdomain.com and the name of the certificate authority (CA) that issued the certificate; sometimes it will also include your company's information. This lets the browser know that the web site it's connecting to is the correct web site, and not an impostor or phishing site. This is authentication.

There are two types of SSL Authentication: full-authentication and domain-authentication.

Fully-Authenticated SSL Certificates

A fully-authenticated SSL certificate will contain information about your domain name and the legal name of your business organization. It will also contain the geographical location information for the city, state, and country where your business is registered to do business. Before a Certificate Authority issues this certificate, the applying business has to fax in supporting proof-of-organization documents to prove its identity. Fully-authenticated websites will typically have a green bar before their domain name.

Domain-Authenticated SSL Certificates

A domain-authenticated certificate will vouch for your domain only. It will not include any information about your company nor its location in the certificate (except for the two-letter country code). Domain-authenticated websites will have a lock icon before their name.

2-Way SSL Prerequisites

In order for Policy Manager to properly implement mutual authentication, the following requirements must be met inside Policy Manager:

  1. You must have an HTTP Security Policy with the Require Client Certificate Authentication option enabled and attached to the service you want.
  2. You must have an Authentication Policy that will check that the correct certificate is presented
  3. You must set your HTTPS Inbound Listener on your Network Director to Accept Client Certificates.
  4. Your HTTPS Inbound Listener must have a set of PKI Keys and an X.509 Certificate.

Assumptions

This topic implements mutual authentication with an anonymous contract. It allows any user in your Workbench with the correct certificate attached to access the service.

Create HTTP Security Policy

The purpose of the HTTP Security Policy is to require a certain credential from the client. In this case we want to require the client to send a certificate as their credentials, which will be validated by the authentication policy in the next step. The HTTP Security Policy must be attached to the virtual service of any service you want to implement mutual authentication on.

  1. Go to [Organization Containing Service] > Polices > Operational Policies.
  2. On the Policies Summary, click Add Policy and create an HTTP Security Policy.
  3. On the HTTP Security Policy Details portlet, click Modify.
  4. On the Specify HTTP Authentication Options screen, click Next.
  5. On the Specify Client Certificate Authentication screen, click the Require Client Certification Authentication checkbox and select the Use clients X.509 certificate from the SSL context radio button.
  6. Under Subject Category, select End-User and click Finish.

  7. In the Policy Workflow actions portlet, click Activate Policy.
  8. Attach this policy to the service you want to implement mutual authentication on.
  9. Navigate to your virtual service.
  10. In the Policy Attachments portlet, click Manage in the Operational section.
  11. Navigate the Policy Hierarchy, select the newly created HTTP Security Policy, and click Apply.

Create Authentication Policy

The purpose of the authentication policy is to ensure that the correct certificate is received. The HTTP Security Policy only requires that a certificate be sent by the client, but that could be any certificate. This policy must also be attached to the service you want to implement mutual authentication on.

  1. Go to [Organization Containing Service] > Polices > Operational Policies.
  2. On the Policies Summary, click Add Policy and create an Authentication Policy.
  3. On the Authentication Policy portlet, click Modify.
  4. On the Modify Authentication Policy pop-up, select the End User radio button.
  5. In the Domains section, select any domains you wish to have access to, use >> to move them to the right panel, and then click Apply.

  6. In the Policy Workflow actions portlet, click Activate Policy.
  7. Attach this policy to the service you want to implement mutual authentication on.
  8. Navigate to your virtual service.
  9. In the Policy Attachments portlet, click Manage in the Operational section.
  10. Navigate the Policy Hierarchy, select the newly created Authentication Policy, and click Apply

Configure Outbound HTTPS Support

The Network Director supports Outbound HTTPS to the physical service/endpoint using the following two methods:

Outbound HTTP Certificate Configured on the Virtual Service (Suggested Method)

If you want to use different outbound certificates for different services, you can accomplish this by attaching them to a particular virtual service.

On the Manage Outbound Identities page, check the Use Incoming Identities as Outbound Identities box, as shown above. When you check this box, the platform uses the HTTP client's mutual SSL certificate. This allows using different client certificates for each service. If the box isn't checked, the listener certificate is used.

  1. In Policy Manager Workbench, select the virtual service you want to attach an Outbound Certificate to.
  2. On the Service Details screen, click Manage PKI Keys from the Actions portlet.
  3. On the Select Key Management Option screen. Two options can be used.
  4. Option 1: Generate Your Own PKI keys and an X.509 certificate. Use this option if you do not have your own certificate and PKI keys. Policy Manager will create them for you and display the information after. Note that Policy Manager must be configured as a Certificate Authority in order to complete the following steps.
  5. Select Generate PKI Keys and X.509 Certificate, and click Next.
  6. Select the key length value (2048 is recommended).
  7. Fill out Certificate Details and click Finish.
  8. Option 2: Import your already existing certificate and keys. Use this option if you have purchased a certificate from a CA and want to use it.
  9. Select Import PKI Keys and X.509 Certificate and click Next.
  10. Specify the Keystore Type.
  11. Specify the Keystore Path.
  12. Enter the password for the selected keystore.
  13. Click Load Aliases.
  14. Select the Key Alias you want to import and click Finish.

  15. From the Details page for the service, from the Actions portlet, click Manage Outbound Identities. Check the Use Service Identity for Outbound HTTPS box, as shown in the diagram at the beginning of this procedure. Click Finish.

Outbound HTTPS Certificate Configured on the Network Director Container

This optional method can be thought of as a “default” certificate that is sent with every request made by services hosted on the Network Director. It is configured in the Details tab in the Outbound Configuration portlet.

  1. In Policy Manager Workbench, go to Organization Tree > Containers and select the Network Director container instance the service is hosted on.
  2. In the Outbound Configurations portlet, click Manage PKI Keys.

  3. On the Select Key Management Option screen, select from two options:
  4. Option 1: Generate Your Own PKI keys and an X.509 certificate. Use this option if you do not have your own certificate and PKI keys. Policy Manager will create them for you and display the information after.

    Note: Policy Manager must be configured as a Certificate Authority in order to complete the following steps.

    • Select Generate PKI Keys and X.509 Certificate and click Next.
    • Select the key length value (2048 is recommended).
    • Fill out the Certificate Details and then click Finish.
  5. Option 2: Import your already existing certificate and keys. Use this option if you have purchased a certificate from a CA and want to use it.
    • Select Import PKI Keys and X.509 Certificate and click Next.
    • Specify the Keystore Type.
    • Specify the Keystore Path.
    • Enter the password for selected keystore.
    • Click Load Aliases.
    • Select the Key Alias you want to import and then click Finish.

Configure Inbound HTTPS Support

There are two things to do in order to enable client certification:

  • Set your HTTPS inbound listener to accept client certificates.
  • Use Policy Manager to create a client certificate and add it to your store of trusted CA Certificates.

To create an HTTPS inbound listener

Note: If you have an existing HTTPS listener you want to use, you can just modify it under Actions > Modify Container Listener and change its client certificate requirements.

For more information about setting up an HTTPS listener, see About Listeners. For information about creating and managing trusted CA certificates in Policy Manager, see Trusted CA Certificates.

  1. In the Inbound Listeners portlet, select the Network Director container instance you plan to host the service on.
  2. Click Add Container Listener.

  3. From the drop-down, select HTTPS and click Next.
  4. From the Client Certificates drop-down, select Accept Client Certificates.
  5. Fill out the rest of the fields to your preference and click Finish.

  6. Go to Actions > Manage PKI Keys.
  7. Create or import PKI Keys and certificate for HTTPS Inbound Listener.

  8. On the Select Key Management Option screen, select from two options.
  9. Option 1: Generate Your Own PKI keys and an X.509 certificate. Use this option if you do not have your own certificate and PKI keys. Policy Manager will create them for you and display the information after. Note that Policy Manager must be configured as a Certificate Authority in order to complete the following steps.
  10. Select Generate PKI Keys and X.509 Certificate and click Next.
  11. Select the key length value (2048 is recommended).
  12. Fill out the Certificate Details and click Finish.
  13. Option 2: Import your already existing certificate and keys. Use this option if you have purchased a certificate from a CA and want to use it.
  14. Select Import PKI Keys and X.509 Certificate and click Next.
  15. Specify the Keystore Type.
  16. Specify the Keystore Path.
  17. Enter the password for the selected keystore.
  18. Click Load Aliases.
  19. Select the Key Alias you want to import and click Finish.

Add Trusted Client Certificates to Policy Manager

Add any additional trusted client certificates to the Trust CA Store in Policy Manager.

  1. Go to Configure > Security > Certificates > Trusted CA Certificates.
  2. To import the certificate for the client, click Add Trusted CA Certificate and click Apply.
  3. Go to Security > Users.
  4. Assign PKI Keys and X.509 certificate to desired user(s).
  5. Select user(s).
  6. Click Manage PKI Keys.
  7. Import PKI Keys and X.509 Certificate and click Next.
  8. Select a valid .jks file and click Finish.

Test

You can test to be sure that mutual authentication is working properly by testing it with SOAPUI. You just need to export the Private Key and X.509 Certificate from the HTTPS Inbound Listener and add them to your SOAPUI.

  1. Navigate to the Network Director.
  2. Locate your HTTPS Listener created earlier in this guide under Inbound Listeners portlet.
  3. From the Actions drop-down, select Manage PKI Keys.
  4. Under Key Management Options, select Export Private Key and X.509 Certificate and click Next.
  5. Confirm that Keystore Type is set to Java.
  6. Fill out the Keystore Details fields and click Finish.

  7. Inside SOAP UI, go to File > Preferences > SSL Settings.
  8. Inside the Keystore field, browse to where you saved the exported file.
  9. Under KeyStore Password, enter the same password you made when you exported the keys and click OK.
  10. SOAPUI should now be able to successfully test services with mutual authentication.