Venafi Platform supports a number of popular SAML single sign-on (SSO) identity providers for modern SSO user authentication.
Configuring SAML single sign-on (SSO) is a multi-step process that involves getting your Venafi instance ready, configuring your identity provider, and then incorporating your identity provider's data in Venafi Configuration Console.
This topic is part of Phase
Phase One of SAML SSO configuration can be broken down into the following processes:
- Configure your FQDN in Venafi Platform's Platform tree so it knows what URL people are using to access its services. This is required because the signed SAML Response is linked to the FQDN, and if this isn't configured properly, SSO won't work.
- Ensure you have an LDAP or Active Directory (AD) connection to an identity directory that is connected to your SAML Identity Provider (IDP).
- Configure the User Search Expression for you identity store (LDAP or AD). This step uniquely links users in your directory with users in Venafi Platform via a specific user identifier, like UPN.
- Export your Venafi Service Provider Metadata XML file. This file (or the data it contains) will be required for phase two: configuring your IDP.
Each of these processes is described in the sections below.
A secure SAML SSO process requires you provide the FQND (fully-qualified domain name) users enter to access Venafi Platform. Most organizations use multiple Venafi Platform servers to provide redundancy and load balancing. The server doesn't know the URL (of, for example, the load balancer) but the FQDN is required for secure communication between your Venafi server and the IDP. Use the following procedure to configure your FQDN in the web console.
To configure your FQDN in Venafi Platform
- From the Platform menu bar, click Policy Tree.
Click the Platforms tree.
You will be taken to the Platforms root, Platforms tab.
- Click the Engine sub-tab.
In Trust Protection Platform URL HostNames, locate Aperture (/Aperture), and enter the FQDN or IP address used to access Venafi Platform. The value you enter should match the FQDN found in the common name or DNS Subject Alternative Name of your CA-issued Venafi Operational Certificate so users don't encounter a certificate error.
NOTE Do NOT include the protocol (
https://), or the
/Aperturedirectory. Just enter the FQDN itself. So, if your Aperture URL is
https://platform.venafi.com/Aperture, you would enter:
- Click Save.
In Venafi Platform version 23.3, there is no support for just-in-time account creation, so you need to have Venafi Platform accounts for all users who will be logging in via the SAML identity provider as Active Directory (AD) or LDAP users.
It is important that your users are queryable by the value put in the NameID parameter of the Subject section of the SAML assertion. For example:
- For AD users, if the SAML IDP is using the e-mail address of the authenticated user as the NameID, then the Venafi Platform AD identity provider User Search properties should be configured to customize the user lookup to the email address. For details on customizing the user lookup to the email address, see Phase 1.3: Configure SAML user search expression.
For LDAP users, if the SAML IDP is using the UPN (User Principle Name) of the authenticated user as the
NameID, then the Venafi Platform LDAP identity driver User Search properties should be configured to add
userPrincipalName(or whatever the corresponding attribute is in your LDAP directory) as described in Phase 1.3: Configure SAML user search expression.
Whatever the attribute is, you want to follow these guidelines:
- The attribute is something that the SAML IDP can provide.
- The attribute is something that Venafi Platform has access to and can query against.
- The attribute uniquely identifies one (and only one) user. If more than one user is returned in the query, authentication will fail an ambiguity security check.
Regardless of the identity provider, you need to export Venafi Platform data that you will use to connect to the identity provider.
When configuring a SAML-based identity provider configuration for logging in to Venafi Platform, you need to ensure the identity driver is configured to customize the user lookup to correctly and uniquely identify users.
You need to work with your identity management team to determine what type of unique identifier you are able to pass into the user assertion. We recommend using UPN, but you can use any unique attribute that is available to be put as the
Name ID of the SAML assertion, and is available for query via your AD or LDAP connection.
To customize the user lookup in Venafi Configuration Console
- Use Remote Desktop to connect to the Venafi Platform host machine, and open the Venafi Configuration Console.
- Click the Connectors node.
- Click the identity connector used by Active Directory.
- In the actions panel, click Properties.
[Conditional] If necessary, log in to Venafi Platform as a master administrator.
The next step depends on whether you are connecting with AD or LDAP.For Active Directory
- Click the User Search tab.
- Click Use Custom Expression.
Change the value from:
Unless your IDP is not sending the UPN of the user within the
userID, in which case you should enter the following to search by e-mail address:
TIP Since this string uses the e-mail address of the user, and since an email address may not be unique in some systems, this is not the preferred option.
- Click OK.
Open a command window, and reset IIS using the following command:
- Click the Search Resolution tab.
- From Available Attributes, add both the following:
- Click Add.
- Click OK to save.
Open a command window, and reset IIS using the following command:
Log in to Aperture, and find an identity field, and verify that you can find one (and only one) user, searching with sample data that will be put in the
Name IDof the SAML assertions.
For example, if you're using UPN with Active Directory, log in as an AD user, and in a contact field search for a known email address in your organization (e.g. firstname.lastname@example.org) to make sure that one, and only one result is returned.
Now that you have configured the user lookup search expression, you're ready to move on to retrieving your Service Provider Metadata XML file.
In SAML authentication, the service provider (in this case Venafi Platform) publishes an XML metadata file, which is used for making the connection between the service provider and the identity provider. You need to export that file from Venafi Configuration Console using the following procedure.
To retrieve the service provider metadata XML file
- Use Remote Desktop to connect to your Venafi server, and open Venafi Configuration Console.
- Click the Authentication node.
- Click the SAML component.
- In the Actions panel, click Properties.
- [Conditional] If requested, enter a master administrator username and password for Venafi Platform.
Select your IdP Vendor from the drop-down list.
The settings window will populate based on your selection with the specific fields and terms for your identity provider.
If you are using a non-tested IdP vendor, select Other, then enter the IdP name. This name will be used to identify the SAML configuration and for placing the certificate in the policy tree.
[Optional] Configure the Default Return URL. This is the default URL users will be taken to upon successful login through the SAML provider. Most organizations use
aperture, as that is the most common starting place for users of the platform.
[Optional] Configure the Log out URL. If supported by your IdP, this is the URL that will trigger a log out of a session. As far as we know, Azure is the only tested IdP that supports a log-out URL.
If your IdP does not support a Log out URL, and nothing is entered in this field, then Venafi Platform will not have a log-out option in the menu. After configuring this setting you need to restart IIS before you will see the change in the menu.
In the Export and import SAML metadata section, click Export service provider file and save the file to a location you'll be able to access during Phase 2.
- Most identity providers can import the SP metadata XML file directly.
- If your identity provider (including Okta) cannot import the SP metadata XML file, refer to the Service provider details for the URLs you will need when configuring your identity provider.
When you've completed all four steps in phase one, you're ready to move on to phase two where you will configure your IDP.
While you should be able to connect Venafi Platform with any IDP that supports the SAML 2.0 standard, Venafi has tested and is providing guidance on using the following identity providers:
- How to configure ADFS for SSO
- How to configure Azure for SSO
- How to configure Okta for SSO
- How to configure PingFederate for SSO
- How to configure PingOne for Enterprise for SSO
NOTE Venafi Platform23.3 only supports a single identity provider connection at a time. Multiple IDP connections may be considered for a future release.