How to Configure and use Two Factor Authentication on K5

When moving to any cloud platform, it is imperative that your data and environment is secured at all times, with only authorised trusted users having access. The consequences of loss or compromise of user credentials or other access token could result in major issues for your organisation, ranging from loss or theft of data, through to the service becoming non-functional, to complete deletion of your cloud environment.

By default, K5 uses a domain, username and password combination for authorising access to both the K5 portals and API functionality. Whilst suitable for most circumstances, there may be those customers who require a greater level of security in order to meet compliance needs, security guidelines and/or policies in place within their organisation. For this reason, K5 provides an optional two factor authentication method, requiring the use of a client certificate (combination of a private key an public key certificate), in conjunction with the domain/username/password combination.

It is recommended that your decision to enable two factor authentication is made as part of a wider security review across your organisation, involving the identification of security risks and a strategy for managing against them. For some customers, the decision to use 2 factor authentication may have been made to limit the number of PCs from which a successful login attempt can be established, whilst others may want to enforce multiple layers of authentication, to protect against a single breach or compromise of login details. In addition, whilst the client certificate is saved to the certificate store on the individual users PC, it is up to the individual/organisation to decide what level of protection is necessary to protect, restrict and use that certificate.

Two factor authentication can be enabled individually for each user, by logging into the central portal as that user and changing the authentication type. It is not currently possible to enable/enforce two factor authentication across all users at one time.

For details of this simple process, please see chapter 6 of the K5 Portal User Guide When choosing a passphrase, I strongly recommend that you use a complex password that is different to the password associated with your K5 domain username. Remember to consult your own organisations corporate password policies when deciding this password, although it is recommend to adopt an even stronger standard to protect all production or sensitive environments. For the purposes of this blog, this passphrase will be referenced as <PASSPHRASE1> below.

Once submitted, this request will result in an email being sent to the requesting user, containing a link to their certificate.

On Receipt of the Certificate Email

  1. Once the ‘Your New Certificate is Ready’ email arrives, scroll down to the ‘English’ body of text. Locate the ‘User ID of this certificate:’ section of the email and copy the random string of text immediately below it
  2. Click on the link below this, to open up a page within your web browser in which to download the certificate from. Within here paste in your ‘User ID’ from above into the box and then enter the passphrase you provided during the certificate request process, then click ‘Download’certa
  3. When prompted with what to do with the certificate, click ‘Save As’ and save it to a suitable location. The default file name is ‘EndUser.p12’
  4. Double click the downloaded file to open the ‘Certificate Import Wizard’
  5. On the ‘Welcome’ screen, click ‘Next’
  6. On the ‘File to Import’ screen, click ‘Next’
  7. Next, enter <PASSPHRASE1> as provided as above, when requesting the certificate+key
    • You may wish to allow the certificate+key to be exported from the certificate store. This has some advantages to allow the certificate to be used on several devices, but also has some security disadvantages. You should consider whether the advantages outweigh the risks before selecting this option. To allow the certificate to be exported, tick ‘Mark this key as exportable’. <PASSPHRASE1> will be required to export the certificate at a later date. The ability to export may be useful if you want to transfer files to another PC in the future or if you want to back the file up. Leave this box unticked if you want to ensure this certificate can’t be exported, to be used anywhere else.
    • Tick the ‘Enable strong private key protection’ box if you want to enforce that <PASSPHRASE1> must be entered each time the certificate is accessed. This will improve security, stopping anyone with PC level access from locating the domain/username/password and freely using the certificate, but at the expense of ease of use by the end user. Generally, restricting access to the PC via a username/password combination and/or encrypted system drive is considered sufficient for most circumstances, but customers wanting to impose the highest level of security, may want to consider ticking this option.certb
  8. Click ‘Next’ to accept the default options on the ‘Certificate Store’ screen,           followed by ‘Finish’
  9. Click ‘Next’ to accept the default options on the ‘Certificate Store’ screen
  10. If choosing ‘Enable Strong Private Key Protection’, you will next be promoted to set the Security Level for a protected item. Click ‘Set Security level’, then tick ‘High’ followed by ‘Next’certc
  11. Next, enter a further complex password (of your choosing) twice to confirm and click ‘Finish’. You will then be prompted for this password each time the certificate is used, so ensure you keep it safe. You also have the option here of renaming the key if you want to give it a more meaningful name.certd
  12. Click ‘Ok’ if prompted to acknowledge the successful import of the certificate into your local certificate store.
  13. Next, change your K5 authentication to ‘Certificate + Password Authentication’ as per Chapter 6 of the K5 Portal User guide If prompted to login with a certificate, select ‘No’ as use of the certificate is not yet enabled.cert5
  14. This takes care of logging into each of the K5 Portals, as you will now be required to ‘Ok’ your certificate, as well as supplying your domain/username/password combination when you log in. If the optional ‘Enable strong private key protection’ box was enabled as above, you will also be prompted for a password each time a new browser session requests access to the private key.
  15. Select the ‘Grant Permission’ radio button and enter the password you specified in step 4 above.


Configuring the API to use 2 Factor Authentication

Next, we need to configure your API environment to also use the certificate in conjunction with domain/username/password credentials, to allow your session authentication token to be obtained.

Step 1 – Converting the Cert+key to PEM format for use with the API

Your saved .p12 certificate+key must now be converted into PEM format for use with the K5 API. (If you no longer have your .p12 file, and your certificate is marked as exportable, then see Appendix 1 below for details of exporting your certificate first. Failing that you will need to request a new certificate, as per details in the K5 Portal User Guide.)

  1. Assuming the use of Cygwin, copy the .p12 certificate file into your Cygwin home folder. This can be renamed to a suitable name if required. e.g. MyK5Cert.p12
  2. Within Cygwin, ensuring you are in the home folder, enter the following command. (The same command can be used in any other environment you are using that includes the openssl command, if not using Cygwin):

openssl pkcs12 -in MyK5Cert.p12 -out MyK5Cert.pem

3. This will require you to enter the password <PASSPHRASE1>, as well as a password to encrypt/protect the resulting PEM file <PASSPHRASE2>. This can be the same or a different password as required. Enter the PEM password twice to verify you the password you have entered


(If you specify the command with ‘–nodes’ on the end, then it will be saved in an unencrypted form, requiring no password for the PEM file to be used. The decision to encrypt or not depends on whether access to the PC, and hence the stored file is considered secure enough to mitigate the potential risk of exposure of this certificate to the organisation. Remember also, that in most cases, the domain/username/password credentials will also likely to be stored in clear text somewhere within the PC, for use within by the API when obtaining the session authentication token.)

4. Next, the PEM file needs to be edited to remove the 3 lines before “—–BEGIN ENCRYPTED PRIVATE KEY—–” i.e.pem1.PNG

Followed by the deletion of block of text immediately below the “—–END ENCRYPTED PRIVATE KEY—–” line, including the second certificate block (Intermediate cert), up to and including the line before the second “—–BEGIN CERTIFICATE—–” line.


This should leave a certificate of the form:



















(NOTE: The above step is not required if using an certificate that has been exported as per Appendix 1. )

Step2 – Updating the get_token.ssh script to use the PEM file

  1. Ensure you have copied the PEM certificate into the same directory as your and scripts
  2. Browse to and open your script for editing
  3. Edit the header of the curl command that obtains the token, to include the following where <CERTNAME> is the name of your certificate. (If you are not using curl to wrap the API command, then you will need to consult the guides to see how to use a private key certificate in the header of the tool/language you are using, e.g. Python, C++ etc)

–cert <CERTNAME>.pem –cert-type pem


curl –cert MyK5Cert.pem –cert-type pem -k -X POST -i -H “Content-Type: application/json” -H “Accept: application/json” -d ‘{“auth”:{“identity”:{“methods”:[“password”],”password”:{“user”:{“domain”:{“name”:”‘$DOMAIN_NAME'”}, “name”:”‘$USER_NAME'”, “password”:”‘$USER_PW'”}}}, “scope”: { “project”: {“id”:”‘$PROJECT_ID'”}}}}’ | awk ‘/X-Subject-Token/ {print $2}’ > tempfile.txt | tr -d ‘\r\n’

4. Next, run the script to request and obtain your session token. Note, you will be prompted to enter the passphrase for the PEM file you entered earlier e.g. <PASSPHRASE1>.


(It is also possible to embed the password for your PEM file into the file, but this is not recommended for production/sensitive environments.

To do this, include the password along with the certificate as shown below, where <PEM PASSWORD> is the password you entered above.

–cert <CERTNAME>.pem:<PEM PASSWORD> –cert-type pem


curl –cert MyK5Cert.pem:Password123 –cert-type pem -k -X POST -i -H “Content-Type: application/json” -H “Accept: application/json” -d ‘{“auth”:{“identity”:{“methods”:[“password”],”password”:{“user”:{“domain”:{“name”:”‘$DOMAIN_NAME'”}, “name”:”‘$USER_NAME'”, “password”:”‘$USER_PW'”}}}, “scope”: { “project”: {“id”:”‘$PROJECT_ID'”}}}}’ | awk ‘/X-Subject-Token/ {print $2}’ > tempfile.txt | tr -d ‘\r\n’


How to Export Your Private Key

To export your private key, please use the certificate Snap-in within MMC, as this allows the certificate to be exported in P12 format.

  1. Open MMC.exe, and add the certificate snap-in (File | Add/Remove Snap-in, Certificates | Add | My User account | Finish | Ok)
  2. Expand certificates – current user | personal | certificates and locate the certificate issued by “Servicer K5”. This will have a name that corresponds to the second half of the “User Id of this certificate” (i.e. after “-“)
  3. With the certificate selected, right click and choose ‘All Tasks | Export’
  4. In the resulting Wizard, on Welcome screen click ‘Next’
  5. On Export Private Key screen, select ‘Yes, export the private key” and click ‘Next’
  6. On Export File Format screen, ensuring Personal Information Exchange is selected with no other options and click ‘Next’cert2
  7. Enter a Password twice to confirm and click ‘Next’. This is a new password to protect the exported key, but can be the same as the password used during certificate registration request.
  8. Browse to a suitable location to save the file, give it a name and click ‘Save’, to save as a .pfx file
  9. Click ‘Next’, then ‘Finish’ and ‘Ok’ to success message. The MMC window can now be closed without saving it