Type: Technical Documentation
Affects Version/s: None
Component/s: Application Security > SAML
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
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.
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.
List the steps a developer needs to take to implement this feature, or a user needs to perform in order to use this feature.
- The admin navigates to the SAML Admin portlet and presses the "Replace Certificate" button
- In the popup that gets shown, the admin selects the "Import Certificate" tab
- The admin can now drag and drop or browse for a PKCS12 formatted keystore file to upload
- If successful, a password must be provided to decrypt the entries within the keystore
- The admin is provided with a selection of keystore entries to choose from to import.
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
Any specific implementation details that helps understanding how it works, provides hints for debugging and fixing.
Serves both steps of the import process.
- Upload and validate a PKCS12 keystore file to hold as a temp file. Also prompt for Keystore password.
- Allow selection of keystore entry to import
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/>
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.
Validates uploads as PKCS12 keystore format.
Creates a temp file from the upload if valid.
Writes file upload success & failure JSON messages expected by the Liferay.Upload JS component.
A decorator for TempFileEntryUtil to isolate SAML temp files & centralize all temp file CRUD activities.