Importing a certificate into the portal

HTTPS is a means of encrypting communications to and from a web server. HTTPS also allows a client application the ability to confirm the identity of the web server. When using HTTPS, each web server where HTTPS is enabled must send a certificate to clients. The certificate contains a statement of identity (I am gis.mycity.gov) and a public key that the client can use to send encrypted information to the web server.

Portal for ArcGIS users often transmit information that needs to be encrypted; therefore, HTTPS is always enabled in the portal and HTTPS is required for your Web Adaptor. Your Web Adaptor is installed to work with a web server, which will have HTTPS enabled.

It’s strongly recommended that the web server’s certificate be signed by a certifying authority (CA). The portal itself comes with a self-signed certificate. A self-signed certificate means that a client can’t verify the identity of the server but can send content encrypted. Replacing the self-signed certificate with a CA-signed certificate improves the security of your deployment.

There are two ways to use a certificate with the portal. The first way is to generate a new certificate by generating a certificate signing request (CSR), having it signed by your CA and importing it into the portal. The second way is to import an existing certificate that has already been assigned to the machine where the portal is installed. Since most CAs charge for signing certificates, customers that have existing certificates for the same machine may prefer to import their existing certificate instead of generating new ones. Below are steps for both processes.

All of the steps below use a tool called keytool for managing your certificates. The keytool command can be found in <Portal for ArcGIS installation location>\arcgis\portal\framework\runtime\jre\bin. Your certificates will all be stored in a file called portal.ks, found in <Portal for ArcGIS installation location>\arcgis\portal\etc\ssl.

Generating a new certificate

These steps help you generate a certificate signing request (CSR), sign it, import your organization's root certificate, and import the signed certificate.

Generating a CSR and signing it

Steps:
  1. Open a command prompt window using the Run as administrator option.
  2. From the command line, browse to the <Portal for ArcGIS installation location>\framework\runtime\jre\bin directory.
  3. Run the following command:

    keytool –genkey –alias portalcert –keystore <Portal for ArcGIS installation location>/etc/ssl/portal.ks -keyalg RSA

    NoteNote:

    You can enter your own text for the -alias parameter; portalcert is provided as an example. The alias you choose is important, as you'll need to reuse it later when you generate the CSR and import the signed certificate into the portal.

    1. When prompted, enter portal.secret for the keystore password. Press Enter.
    2. When asked what your first name and last name is, put in the fully qualified domain name for your server (for example, portal.mycity.gov). Press Enter.
    3. For your organizational unit, enter a department name that would be meaningful to a user of your site. Press Enter.
    4. Specify the name of your organization. Press Enter.
    5. Specify the name of your city or locale. Press Enter.
    6. Specify the name of your state or province. Press Enter.
    7. Specify the two-letter country code where your organization resides. Press Enter.
    8. Verify the information you specified. Type yes and press Enter.
    9. Optionally, specify a keystore password for the certificate. If you want to use the default keystore password of portal.secret, do not specify anything. Press Enter.
  4. Run the following command:

    keytool –certreq –alias portalcert –file <Portal for ArcGIS installation location>/etc/ssl/portalcert.csr –keystore <Portal for ArcGIS installation location>/etc/ssl/portal.ks

  5. Specify the keystore password. The password is portal.secret if you used the default from above. Press Enter.

A file called portalcert.csr is generated in the <Portal for ArcGIS installation location>/etc/ssl directory. Send this file to your certifying authority to have it signed. Place the file they send back into the <Portal for ArcGIS installation location>\etc\ssl directory.

Importing your organization's root certificate

Steps:
  1. Open a command prompt window using the Run as administrator option.
  2. From the command line, browse to the <Portal for ArcGIS installation location>\framework\runtime\jre\bin directory.
  3. Import your organization's root certificate into the portal by running the following command:

    keytool –importcert –alias orgRootCert –file <file path to root certificate>/orgRootCert.cer –keystore <Portal for ArcGIS installation location>/etc/ssl/portal.ks

    Contact your system administrator to learn how to obtain the root certificate.

    NoteNote:

    You can enter your own text for the -alias parameter; orgRootCert is provided as an example.

  4. Specify the keystore password. The password is portal.secret if you used the default from above. Press Enter.
  5. When prompted to trust this certificate, type yes and press Enter.

Importing the signed certificate

Steps:
  1. Open a command prompt window using the Run as administrator option.
  2. From the command line, browse to the <Portal for ArcGIS installation location>\framework\runtime\jre\bin directory.
  3. Import the signed certificate you obtained from your certifying authority by running the following command:

    keytool –importcert –alias portalcert –file <Portal for ArcGIS installation location>/etc/ssl/signedCert.cer –keystore <Portal for ArcGIS installation location>/etc/ssl/portal.ks

  4. Specify the keystore password. The password is portal.secret if you used the default from above. Press Enter.
  5. Open the file <Portal for ArcGIS installation location>\framework\runtime\tomcat\conf\server.xml in a text editor.
  6. Locate the keystorePass="portal.secret" property and append keyAlias="portalcert" to the end of the property. For example
    keystorePass="portal.secret" keyAlias="portalcert"
  7. Save and close the file.
  8. Restart Portal for ArcGIS for the change to take effect. For instructions, see Stopping and starting the portal.

Importing an existing certificate

These steps help you import your organization's root certificate and then import an existing certificate into the portal. HTTPS performs encryption using a private and public pair of encryption keys. The public key is contained in the certificate and is shared with all users so that information can be encrypted. In order to decrypt, a private key is needed, and this private key must be provided to the portal.

Private keys and public certificates are transported either in *.p12 or *.pfx files, and these files are often protected by password. Before beginning, ensure that you have the *.p12 or *.pfx file and know the password.

Importing your organization's root certificate

Steps:
  1. Open a command prompt window using the Run as administrator option.
  2. From the command line, browse to the <Portal for ArcGIS installation location>\framework\runtime\jre\bin directory.
  3. Import your organization's root certificate into the portal by running the following command:

    keytool –importcert –alias orgRootCert –file <file path to root certificate>/orgRootCert.cer –keystore <Portal for ArcGIS installation location>/etc/ssl/portal.ks

    Contact your system administrator to learn how to obtain the root certificate.

    NoteNote:

    You can enter your own text for the -alias parameter; orgRootCert is provided as an example.

  4. Specify the keystore password. The password is portal.secret if you used the default from above. Press Enter.
  5. When prompted to trust this certificate, type yes and press Enter.

Importing an existing certificate

Steps:
  1. Place the *.p12 or *.pfx file in the <Portal for ArcGIS installation location>\etc\ssl directory. The rest of the steps will use an example of cert.p12.
  2. Open a command prompt window using the Run as administrator option.
  3. From the command line, browse to the <Portal for ArcGIS installation location>\framework\runtime\jre\bin directory.
  4. Look up the alias of the certificate you are trying to import:

    keytool -list -keystore <Portal for ArcGIS installation location>\etc\ssl\cert.p12 -storetype PKCS12

    When prompted for the keystore password, enter the password for the *.p12 or *.pfx file. The command prompt will display a message similar to the following:

    Keystore type: PKCS12
Keystore provider: SunJSSE

Your keystore contains 1 entry
la-620dfedf-681b-4fe0-af13-2d09b1c5515e, Dec 21, 2013, PrivateKeyEntry,
Certificate fingerprint (SHA1): 28:BB:ED:55:7C:5B:0F:F1:79:54:BF:FE:CC:14:82:20:E5:8F:BF:3D

    The string of letters and numbers following the Your keystore contains 1 entry text is the alias of your certificate.

  5. Import the certificate by defining the alias and change the alias of the certificate to portalcert:

    keytool -importkeystore -srckeystore <Portal for ArcGIS installation location>\etc\ssl\cert.p12 -destkeystore <Portal for ArcGIS installation location>\etc\ssl\portal.ks -srcstoretype PKCS12 -deststoretype JKS -alias la-620dfedf-681b-4fe0-af13-2d09b1c5515e -destalias portalcert

    When prompted, enter portal.secret for the destination keystore password. When prompted, enter the password for the *.p12 or *.pfx file. This will import the certificate and change the alias of the certificate to portalcert.

    NoteNote:

    You can enter your own text for the -destalias parameter; portalcert is provided as an example.

  6. Verify that the certificate was imported correctly:

    keytool -list -keystore <Portal for ArcGIS installation location>\etc\ssl\portal.ks

    When prompted, enter portal.secret for the destination keystore password. In the list of keystore entries, verify that the portalcert alias is listed.

  7. Change the password of the certificate you imported to match the password of the portal's keystore:

    keytool -keypasswd -keystore <Portal for ArcGIS installation location>\etc\ssl\portal.ks -alias portalcert -keypass passwordofp12orpfxfile -new portal.secret

    When prompted, enter portal.secret for the destination keystore password. The password of the certificate you imported is now the same as the portal's keystore.

  8. Open the file <Portal for ArcGIS installation location>\framework\runtime\tomcat\conf\server.xml in a text editor.
  9. Locate the keystorePass="portal.secret" property and append keyAlias="portalcert" to the end of the property. For example
    keystorePass="portal.secret" keyAlias="portalcert"
  10. Save and close the file.
  11. Restart Portal for ArcGIS for the change to take effect. For instructions, see Stopping and starting the portal.
Copyright © 1995-2015 Esri. All rights reserved.
5/5/2015