App Support.

We're here to help.


  1. Knowledge Base
  2. Features
  3. Using macOS Keychain Certificates and Identities for OpenVPN Connections

Using macOS Keychain Certificates and Identities for OpenVPN Connections

Viscosity supports authenticating OpenVPN connections using certificates and identities stored in the macOS Keychain. This capability is provided by Viscosity’s System Identity authentication feature, allowing you to use existing Keychain items without managing separate certificate and key files.

This article will guide you through the process configuring a system identity from the Keychain for use in Viscosity, and using it for authentication when connecting to an OpenVPN server.

What is a System Identity?

If you’ve previously configured an OpenVPN connection in Viscosity, you’ve likely selected a certificate and a private key to use when authenticating with your VPN server. An "identity" refers to a matched pair of both of these files. When utilising the macOS Keychain, the certificate and private key are combined into a single secure "identity".

A "system identity" specifically describes an identity securely stored using the operating system. On macOS this means in the Keychain (while on Windows it means in the Windows Certificate Store). Viscosity’s System Identity authentication feature lets you use system identities for authentication for OpenVPN connections.

System identities can be stored and accessed from the machine-wide System Keychain, the User's Keychain (also known as the login Keychain), as well as from external hardware tokens.

Selecting an Identity in the Keychain

Viscosity makes it easy and straightforward to select an identity stored in Keychain, both for end-users configuring a connection as well as for VPN administrators with complex selection requirements.

This section assumes the identity you want to use is already stored in the macOS Keychain. If this isn't the case, please first skip ahead to the [#loading-an-identity-into-the-keychain Loading an Identity into the Keychain] section below, before continuing with this section.

Manually Selecting an Identity

The most straightforward way to use a system identity is to simply use Viscosity's editor to select the identity you'd like to use for authentication. This can be done like so:

  1. From Viscosity's menu, select the "Settings..." item, select your VPN connection, and then click the Edit button.
  2. Under the "Authentication" tab, when the Authentication Type to "SSL/TLS Client (System Identity)".
  3. Make sure the System Identity Retrieval option is set to "Use selected identity" and then click the "+" button.

  4. Select the identity you'd like to use, and then click the "Select" button.
  5. Click the Save button and connect your VPN connection.

Manual selection of an identity is not recommended for deployments to multiple users or machines with unique identities, as it will require configuration for each user or machine. Instead we recommend following the using a Match DN as documented in the selection below to dynamically select the correct identity to use.

Dynamically Selecting Identities Using a Match DN

Viscosity's System Identity authentication feature also supports dynamic matching. This allows a single VPN configuration connection/file to be provided to all users, which will automatically match the correct identity to use when connecting. This is the recommended approach for deployment in enterprise environments.

This works by providing a "Match DN", which can be thought of as search criteria for Viscosity to use when searching the Keychain for an identity to use for authentication. If an identity is found that matches the search criteria, it'll be used for authenticating with the OpenVPN server.

Configuring a Match DN to use for dynamic identity selection can be done like so:

  1. From Viscosity's menu, select the "Settings..." item, select your VPN connection, and then click the Edit button.
  2. Under the "Authentication" tab, when the Authentication Type to "SSL/TLS Client (System Identity)".
  3. Change the System Identity Retrieval option to "Use any identity that matches".

  4. Enter a Match DN string (further information below) to use.
  5. Click the Save button and connect your VPN connection.

Please see the sections below for how to construct a Match DN string to use.


Creating a Match DN

A Match DN string allows you to specify what details from the identity (technically the certificate) must match for it to be used for authentication. This match is performed against the certificate's Distinguished Name (DN), which is a string consisting of the certificate's attributes.

For example, a certificate issued to a VPN user may have a DN of "CN=John Smith, OU=Engineering, O=SparkLabs Pty Ltd, L=Sydney, ST=NSW, C=AU". Here the certificate has the common name "John Smith", with the department set to "Engineering", organisation set to "SparkLabs Pty Ltd", location set to "Sydney", state set to "NSW", and the country code is "AU".

You can view the DN of a certificate using the following command in the Terminal. However please note that OpenSSL uses slashes (/) instead of commas (,). Replace the slashes with commas if using the output as part of a Match DN.
openssl x509 -in path/to/cert.crt -noout -subject

Viscosity allows you to match on a whole DN, or on just some of the attributes. For example, let's say we wanted to exactly match the example DN above, then we would specify our Match DN as:
CN=John Smith, OU=Engineering, O=SparkLabs Pty Ltd, L=Sydney, ST=NSW, C=AU

However, in most cases we want the Match DN to also work for identities generated for other users, not just for John Smith. So in this case we remove the CN from the list of attributes we want to match against:
OU=Engineering, O=SparkLabs Pty Ltd, L=Sydney, ST=NSW, C=AU

We can also be more broad in our match criteria. For example, we may also want to match identities for people from all departments, and from other cities and states, but still in Australia. In which case we can use:
O=SparkLabs Pty Ltd, C=AU


Using Wildcards

Viscosity also supports wildcards, specified using an asterisk (*), allowing partial matches of attributes. A wildcard can be specified at the start of any attribute (to match any prefix), at the end of any attribute (to match any suffix), or both (to match any attribute that contains the specified text).

For example, imagine we have a certificate with a very simple DN of "[email protected]". We don't want to just match for John Smith, we also want to match other staff. This can be accomplished using a wildcard in the Match DN like so:
CN=*@sparklabs.com

As another example, let's say we have a certificate with a simple DN of "CN=SparkLabs John Smith". To match for all employees we can use a wildcard in the Match DN like so:
CN=SparkLabs *

As a final wildcard example, let's say we have a certificate with a DN of "[email protected] VPN Access 123" (where in this example 123 is the employee ID). We can match on this using two wildcards in the Match DN like so:
CN=*@sparklabs.com VPN Access *


Matching Against an Issuer

Viscosity also lets you match on the issuing certificate's DN. The issuing certificate is the certificate that was used the generate the client certificate, which is typically the Certificate Authority (CA) certificate. This can be helpful when it's difficult to uniquely match an identity in the Keychain based on its DN (for example, there may be multiple certificates with the same DN, or the certificate may lack matchable attributes).

To have a Match DN apply to the issuing certificate's DN (instead of the certificate's own DN) prefix the Match DN with "issuer:". For example:
issuer:CN=VPN CA, O=SparkLabs Pty Ltd, L=Sydney, ST=NSW, C=AU

You can view the issuer's DN of a certificate using the following command in the Terminal. However please note that OpenSSL uses slashes (/) instead of commas (,). Replace the slashes with commas if using the output as part of a Match DN.
openssl x509 -in path/to/cert.crt -noout -issuer

Using External Hardware Tokens

Viscosity's System Identity feature also allows identities that are stored on external tokens to be used. As this is utilising macOS's inbuilt token support no third-party PKCS#11 driver is needed, which makes setup and support much easier for supported tokens.

When selecting an identity, Viscosity will automatically list any identities on supported connected tokens. If you wish to select an identity on a token, simply make sure it's connected before following the Selecting an Identity in the Keychain instructions above.



If an identity from a token was configured, and the token isn't connected when attempting to connect the VPN connection, Viscosity will automatically prompt to connect the token.

When using dynamic matching, Viscosity will also search for matching identities on any connected tokens when connecting. If you know in advance that the identity is stored on a token, and you would like the user to be prompted to connect the token if the identity isn't found, the "Identity is on an external token" checkbox should be ticked.

Loading an Identity into the Keychain

To load an identity into the Keychain it's first necessary to create a PKCS#12 file (typically referred to as a .p12 file, also known as a .pfx file on Windows). This is a file format that allows both the private key and certificate to be stored in a single encrypted file. Once you have the .p12 file it can be loaded into the Keychain using Keychain Access, the Terminal, or MDM.

Creating a PKCS#12 file

If you have seperate certificate (.crt) and private key (.key) files for your VPN connection (which is the most common configuration), you will need to turn them into a .p12 file. Some OpenVPN connections may already be configured to directly use a .p12 file, in which case this section can be skipped.

A PKCS#12 file can be created using the following Terminal command:
openssl pkcs12 -export -legacy -inkey key.key -in cert.crt -out identity.p12

You will be prompted to encrypt the .p12 file with a password. Any password can be used, just make a note of it for later when importing the .p12 file into the Keychain.

Also note that the "-legacy" flag is required when using the Terminal or MDM to import the file, as these macOS tools do not currently support modern OpenSSL algorithms. If this flag is not used, you'll likely receive a "SecKeychainItemImport: MAC verification failed during PKCS12 import" error message, or a valid password will be rejected, when attempting to import the file into the Keychain.

Using Keychain Access

An identity (as a .p12 file) can be loaded into the Keychain using the Keychain Access application and following the steps below:

  1. Open the Keychain Access application. The easiest way to do this is to search for "Keychain Access" from the Spotlight menu. It can also be found by manually navigating to /System/Library/CoreServices/Applications/Keychain Access.app
  2. Select the Keychain you wish to import the identity into. If you wish to import the identity into the user's Login Keychain, select "login" to the left. If you wish to import the identity into the System Keychain select "System" to the left.
  3. From the File menu select Import Items...
  4. Enter the password set on the .p12 file

You should now see the identity loaded in the section to the right (you may need to select the "Certificates" tab and/or search for it).

Using the Terminal

An identity (as a .p12 file) can also be loaded into the Keychain using Terminal commands. To load an identity (named identity.p12 here) into the user's login Keychain the following command can be used. Replace "password" with the password on the .p12 file.
security import /path/to/identity.p12 -k ~/Library/Keychains/login.keychain-db -P "password" -T /Applications/Viscosity.app

To load an identity into the System Keychain the following command can be used. Replace "password" with the password on the .p12 file.
sudo security import /path/to/identity.p12 -k /Library/Keychains/System.keychain -P "password" -T /Applications/Viscosity.app

Both of the above commands use the "-T" flag to grant Viscosity access to the identity. If this identity is shared with other applications, additional "-T" flags can be used, or "-A" can be used to grant all applications access.

Using Mobile Device Management (MDM)

Most MDM solutions provide a way to manage and deploy certificates and identities to the Keychain, or allow a macOS device to automatically obtain an identity via the Simple Certificate Enrolment Protocol (SCEP) as part of device enrolment. For information on how to do this via your MDM solution please refer to its corresponding documentation.

An identity can also be deployed using a manually crafted MDM Profile (known as a .mobileconfig file). To create a MDM Profile for an identity the following steps can be followed:

  1. Encode the PKCS#12 file created earlier as Base64 using the following command in the Terminal:
    base64 -b0 -i identity.p12 > identity.p12.b64
  2. Generate two UUIDs using the following command twice. These are unique identifiers that will be used to represent the profile and the PKCS#12 payload.
    uuidgen
  3. Open the TextEdit application and create a new file. From the "Format" menu select "Make Plain Text".
  4. Copy the following MDM Profile template into the text document:

    <?xml version="1.0" encoding="UTF-8"?>
    <!DOCTYPE plist PUBLIC "-//Apple//DTD PLIST 1.0//EN" "http://www.apple.com/DTDs/PropertyList-1.0.dtd">
    <plist version="1.0">
    <dict>
     <key>PayloadType</key>
     <string>Configuration</string>
     <key>PayloadVersion</key>
     <integer>1</integer>
     <key>PayloadIdentifier</key>
     <string>com.mycompany.identityprofile</string>
     <key>PayloadUUID</key>
     <string>UUID_1_GOES_HERE</string>
     <key>PayloadDisplayName</key>
     <string>Identity Certificate</string>
     <key>PayloadDescription</key>
     <string>Installs a client certificate and private key into the Keychain</string>
     <key>PayloadOrganization</key>
     <string>My Company Name</string>
     <key>PayloadRemovalDisallowed</key>
     <false/>
     <key>PayloadContent</key>
     <array>
      <dict>
       <key>PayloadType</key>
       <string>com.apple.security.pkcs12</string>
       <key>PayloadVersion</key>
       <integer>1</integer>
       <key>PayloadIdentifier</key>
       <string>com.mycompany.identityprofile.pkcs12</string>
       <key>PayloadUUID</key>
       <string>UUID_2_GOES_HERE</string>
       <key>PayloadDisplayName</key>
       <string>Client Identity</string>
       <key>PayloadCertificateFileName</key>
       <string>identity.p12</string>
       <key>Password</key>
       <string>PASSWORD_GOES_HERE</string>
       <key>KeyIsExtractable</key>
       <false/>
       <key>AllowAllAppsAccess</key>
       <true/>
       <key>PayloadContent</key>
       <data>
    BASE64_PKCS12_GOES_HERE
       </data>
      </dict>
     </array>
    </dict>
    </plist>
  5. Replace "UUID_1_GOES_HERE" with the first UUID created above. Replace "UUID_2_GOES_HERE" with the second UUID.
  6. Open the "identity.p12.b64" file created above with TextEdit, and replace "BASE64_PKCS12_GOES_HERE" with the contents of the file.
  7. Replace "PASSWORD_GOES_HERE" with the password set on the PKCS#12 file created above.
  8. Optionally replace "com.mycompany.identityprofile", "My Company Name", and "com.mycompany.identityprofile.pkcs12" strings with versions appropriate for your organisation.
  9. Save the file with the filename extension of ".mobileconfig", for example "identityprofile.mobileconfig".

You can then deploy the MDM Profile using your preferred MDM solution, or it can be locally deployed by double-clicking on the file or from macOS System Settings -> General -> Device Management.

When deploying via a MDM solution, deploying to a macOS "device" will deploy the identity to the System Keychain, while deploying to a macOS "user" will instead deploy it to the user's login Keychain. When deploying the profile locally, by default it will deploy to the user's login Keychain. To force it to instead deploy to the System Keychain add the following to the .mobileconfig file: 

<key>PayloadScope</key>
<string>System</string>

Finally, this example profile contains "AllowAllAppsAccess" set to "true". This allows Viscosity to use the identity for authentication without a prompt from macOS. If you'd prefer all apps not have access by default, this option can be set to false or removed. For more information please see the Avoiding macOS Permission Prompts section below.

Avoiding macOS Permission Prompts

macOS maintains a list of permissions on items in the Keychain. If an application has not been granted access to an item, macOS may display a prompt asking the user to approve access. Depending on the cause, these prompts may be a once-off permissions prompt, or a prompt that occurs every time VPN authentication takes place.

This section outlines the prompts that can occur, and how they can be avoided.

Viscosity wants to make changes. Enter an administrator's name and password to allow this. Viscosity wants to use the "System" keychain.



This dialog is typically displayed when Viscosity attempts to use an identity stored in the System Keychain when Viscosity hasn't been granted access. Despite what the text claims in the alert, this permissions prompt is not related to making changes.

To avoid this alert each time the identity is used for authentication, Viscosity should be granted access to use the identity. This can be done by following either the Setting Permissions Using Keychain Access, Setting Permissions Using the Terminal, or Setting Permissions Using Mobile Device Management (MDM) sections below.

Another potential cause for this prompt is when matching on an unexpected identity in the Keychain. For example, if the Match DN is too broad, or the identity is in multiple Keychains, or the user loads an additional identity with a similar DN into the Keychain, the wrong identity may be getting matched. If the permissions on this additional identity don't allow access, the prompt will get displayed even if the permissions on the intended identity are correct. If this is the case, the Match DN should be adjusted or the system-identity-domain command can be used to limit matching to just the desired Keychain.

If for some reason you're unable to adjust the permissions, a final workaround is to remove the identity from the System Keychain and load it into the User's login Keychain instead.

Viscosity wants to access key "identity" in your keychain. To allow this, enter the "login" keychain password.



This dialog is typically displayed when Viscosity attempts to use an identity stored in the login (aka User) Keychain when Viscosity hasn't been granted access.

A user can avoid this alert repeating by entering the password they use to log into their macOS account, and clicking the "Always Allow" button.

If their password is rejected, or they are asked again, it likely means their Keychain password is out of sync with their account password. This can typically be resolved by logging out of macOS and back in (making sure any directory servers are available).

To avoid this alert appearing the first time the identity is used, Viscosity should be granted access to use the identity. This can be done by following either the Setting Permissions Using Keychain Access, Setting Permissions Using the Terminal, or Setting Permissions Using Mobile Device Management (MDM) sections below.

We have observed instances where granting Viscosity access to items in the login Keychain has not prevented the prompt from appearing. In these instances using the "Always Allow" button still appears to work.

Setting Permissions Using Keychain Access

The Keychain Access application can be used to grant Viscosity access to use an identity without needing to prompt for permission using the following instructions:

  1. Open the Keychain Access application. The easiest way to do this is to search for "Keychain Access" from the Spotlight menu. It can also be found by manually navigating to /System/Library/CoreServices/Applications/Keychain Access.app
  2. Select the Keychain the identity is stored in ("System" or "login") from the left, and then select Certificates. You should then see the identity listed to the right. You can optionally use the Search field to search for the identity.
  3. Reveal the private key associated with the identity by clicking on the small arrow next to the certificate.

  4. Double-click on the private key to open the information window.
  5. Click on the Access Control tab.
  6. Click on the small "+" button, and select Viscosity (which will normally be located in the Applications folder) to grant Viscosity access.

  7. Click the Save Changes button. You will need to enter the credentials for an administrator to allow the change if using the System Keychain.
  8. Quit Keychain Access.
  9. If Viscosity is running, first quit Viscosity and then relaunch it. This step is often necessary for the permission changes to take effect.

Note: Keychain Access doesn't refresh Access Control permissions correctly. After making a change it's necessary to quit and open it again to see current permissions.

Setting Permissions Using the Terminal

If you'd rather use the Terminal, Viscosity can also be granted access when the identity is imported into the Keychain. Once imported, the permissions cannot be changed from the command line, so it's necessary to delete the identity from the Keychain and re-add it with the correct permissions.

If the original identity is not deleted from the System Keychain prior to using the commands below, the permissions will not change. If deleting the old item using Keychain Access it is important to note that the private key must be deleted separately before deleting the certificate. Selecting the identity and deleting it will cause the private key to remain in a detached state. Instead expand the identity item to reveal the private key, then delete the private key, followed by the certificate.

When importing the identity into the Keychain again, ensure that the "-T" flag with the path to Viscosity has been included (which grants Viscosity access).

For example, to import into the user's login Keychain:
security import /path/to/identity.p12 -k ~/Library/Keychains/login.keychain-db -P "password" -T /Applications/Viscosity.app

And to import into the System Keychain:
sudo security import /path/to/identity.p12 -k /Library/Keychains/System.keychain -P "password" -T /Applications/Viscosity.app

In the above examples "password" should be replaced with the PKCS#12 password.

Setting Permissions Using Mobile Device Management (MDM)

Most Mobile Device Management (MDM) solutions allow to you configure per-application access permissions for a Keychain certificate/identity. If you have deployed the identity using a MDM solution, please consult the relevant documentation for how to configure these permissions. Often this is known as configuring "approved" or "trusted" applications for a certificate.

If you have instead deployed the identity using a manually crafted MDM Profile (known as a .mobileconfig file), please ensure it contains the "AllowAllAppsAccess" key (in the "PayloadContent" section) with the value set to "true". An example of this can be seen in the Loading an Identity into the Keychain section above. Without this key macOS will prompt the end user for access.

A MDM Profile does not provide any properties to configure access on a per-application basis. So if allowing all applications to use the identity with the "AllowAllAppsAccess" key is not suitable, deployment by the Terminal is recommended instead.

Advanced Configuration Options

Viscosity supports further customisation of the System Identity feature using advanced commands. Advanced commands can be specified and customised in the Viscosity editor, or when directly editing the VPN configuration file provided to end users. For more information please see Advanced Configuration Commands.

The system-identity-domain command can be used to force Viscosity to only search a particular Keychain domain when using System Identity authentication with a Match DN. Valid domains include "user" (the user's login Keychain), "system" (the system-wide Keychain), "dynamic" (tokens and smartcards), and "all" (the default). For more information on how to use this command please see the system-identity-domain entry.

The system-identity command can be included in a VPN configuration file to enable System Identity authentication. Viscosity's editor will automatically configure this command, and so direct manipulation is only recommended if performing automated configuration generation. The format of this command is "#viscosity system-identity type:filter". The "type" text should consist of either "subject", "issuer", or "thumbprint", and the "filter" text should consist of the Match DN to use or the certificate thumbprint.