Details

    • Type: Technical Documentation
    • Status: Closed
    • Priority: Minor
    • Resolution: Completed
    • Affects Version/s: None
    • Fix Version/s: 7.3.X, Master
    • Labels:
      None
    • Sprint:
      Iteration 32, Iteration 33, Iteration 34, Iteration 35, Iteration 36, Iteration 37, Iteration 38, Iteration 39, Iteration 40, Iteration 41, Iteration 42
    • Type of Documentation:
      Deployment

      Description

      Background

      It is required for our SaaS environment, but also useful for other deployments. Prior to this feature, the only way to use a CA signed, or existing self signed certificate & private key in SAML messages exchange was to use the command-line to import the certificate into the keystore configured for SAML use.
      Not only does this require shell access (not available in SaaS), but it can also be quite fiddly to achieve as there are numerous file formats and the commandline tool isn't always so forgiving.

      Features

      The feature allows Instance Admins to upload a PKCS12 formatted keystore containing one or more certificate + private key entries. The keystore itself is merely a transport mechanism and will not be persisted in Liferay.

      We choose to base the import feature on the PKCS12 file format for the following reasons:

      • It is the default file format used by Java 9+
      • It is a widely used interoperable format, meaning it will be easier for customers to extract/migrate certificates used in other technology stacks than Java. This is especially important with our SaaS offering, because we do not expect these customers to necessarily be invested in Java technology (we don't allow code deployment).
      • The PKCS12 file format only supports one password for protecting both the keystore and entries within. This means the feature requires less input from the admin and is simpler.

      If the admin uploads a file which is not in the PKCS12 file format, an error will be displayed.
      The feature will prompt the admin for the keystore password after they have uploaded a valid keystore file.
      Only one entry can be imported, but the feature inspects the keystore and allow the admin to select the desired one. For every keystore entry a preview of the certificate is shown to help with making the selection.
      The selected entry is imported into the keystore used by SAML, using the entity ID of the SAML provider as the entry alias (same as if you use Liferay to create a certificate & private key entry).
      The imported entry is encrypted using the same keystore password provided earlier. Meaning the SAML provider configuration will be updated to remember the password.

      Steps

      List the steps a developer needs to take to implement this feature, or a user needs to perform in order to use this feature.

      1. The admin navigates to the SAML Admin portlet and presses the "Replace Certificate" button
      2. In the popup that gets shown, the admin selects the "Import Certificate" tab
      3. The admin can now drag and drop or browse for a PKCS12 formatted keystore file to upload
      4. If successful, a password must be provided to decrypt the entries within the keystore
      5. The admin is provided with a selection of keystore entries to choose from to import.

      Code

      Provide example code illustrating an example of this feature. Explain what the code does and how it works.

      No custom code is necessary to leverage this feature.

      Some customers might want to import an entry from a JKS formatted keystore because this is the default keystore used by Liferay's SAML implementation. For example they might be migrating from another environment: dev/test/production etc. Simple steps to convert the keystore can be found here: https://knowledge.digicert.com/solution/SO17389.html

      Key related classes/methods and modules, configuration interfaces

      Any specific implementation details that helps understanding how it works, provides hints for debugging and fixing.

      JSPs

      import_certificate.jsp
      Serves both steps of the import process.

      1. Upload and validate a PKCS12 keystore file to hold as a temp file. Also prompt for Keystore password.
      2. Allow selection of keystore entry to import

      update_certificate.jsp

      This JSP was modified to introduce tabs for switching between generating certificates (as avaiable before), and importing. The later delegates to the above mentioned JSP through <liferay-util:include/>

      MVC Commands

      com.liferay.saml.web.internal.portlet.action.UpdateCertificateMVCResourceCommand
      Provides an endpoint for temp file CRUD requests demanded by the Liferay.Upload JS component.
      It wires the default UploadHandler implementation provided by file upload API together with bespoke services implementing UploadFileEntryHandler and UploadResponseHandler (see below).

      Upon receiving temp file CRUD requests, it delegates to the UploadHandler service as described above.

      Note: Upon the Liferay.Upload component initializing on the client side, a request is sent to this command to get the filename of the current uploaded file. This is used to handle "back" navigation in the import process.

      Implementation of wired com.liferay.upload API services.

      com.liferay.saml.web.internal.upload.CertificateUploadFileEntryHandler
      Validates uploads as PKCS12 keystore format.
      Creates a temp file from the upload if valid.

      com.liferay.saml.web.internal.upload.CertificateUploadResponseHandler
      Writes file upload success & failure JSON messages expected by the Liferay.Upload JS component.

      Other

      com.liferay.saml.web.internal.util.SamlTempFileEntryUtil
      A decorator for TempFileEntryUtil to isolate SAML temp files & centralize all temp file CRUD activities.

        Attachments

          Issue Links

            Activity

              People

              Assignee:
              stian.sigvartsen Stian Sigvartsen
              Reporter:
              nora.szel Nóra Szél
              Recent user:
              Nóra Szél
              Participants of an Issue:
              Votes:
              0 Vote for this issue
              Watchers:
              1 Start watching this issue

                Dates

                Created:
                Updated:
                Resolved:

                  Packages

                  Version Package
                  7.3.X
                  Master