SSO Using Okta
Since v6.2.5/2
This section describes the steps to set up Single Sign-On (SSO) for HVR using Okta with SAML authentication.
The setup procedure involves configuring the HVR, setting up a custom SAML application in Okta, and completing the configuration on the HVR.
Prerequisites
Before setting up SSO for HVR using Okta, ensure you have the following:
- HVR Hub installed with HTTPS enabled
- HVR Hub initial setup is completed
- Okta and HVR accounts with administrative access
Setup instructions
Set Up HVR
Prepare the HVR environment for Single Sign-On (SSO) by configuring essential settings and generating metadata.
Configure Public Hostname
Set the fully qualified domain name (FQDN) for the HVR Hub Server to ensure it is publicly accessible for SAML-based authentication.
To set the public hostname, use the command hvrhubserverconfig:
hvrhubserverconfig Public_Host=fully-qualified-hostname
(Optional) Configure SP Key Pair
By default, the HVR Hub Server automatically generates and configures the Service Provider (SP) key pair and X.509 certificate required to establish secure communication between the SP and the Identity Provider (IdP). This automatic generation is done when downloading the SP metadata or when the user tries to authenticate using SAML for the first time.
Perform this step only if you want to manually configure the SP key pair instead of using the automatically generated one.
Instructions to manually configure the SP key pair for SAML
You can configure the HVR Hub Server to use your own key pair and X.509 certificate or generate a new one.
Configure using your own key pair (e.g.,
saml-sp.pub_cert,saml-sp.priv_key) and certificate using the hvrhubserverconfig command:Configure without password:
hvrhubserverconfig Saml_SP_Public_Certificate=@saml-sp.pub_cert Saml_SP_Private_Key=@saml-sp.priv_keyOptionally, you can set a password for the key pair.
Configure with password:
hvrhubserverconfig Saml_SP_Public_Certificate=@saml-sp.pub_cert Saml_SP_Private_Key=@saml-sp.priv_key Saml_SP_Private_Key_Password=password
Configure using a new key pair and certificate:
Generate a new key pair and certificate using the hvrsslgen command:
hvrsslgen saml-sp hvrhubserver-samlSample output:
hvrsslgen saml-sp hvrhubserver-saml hvrsslgen: Fivetran HVR 6.2.6/0 (linux_glibc2.17-x64-64bit) hvrsslgen: Generating SSL key pair... hvrsslgen: Generating SSL key pair completed. hvrsslgen: Certificate subject: 'HVR hvrhubserver-saml' hvrsslgen: Certificate contains 2048 bit RSA Public Key. hvrsslgen: Certificate valid from Jan 6 18:03:18 2025 GMT hvrsslgen: Certificate valid until Jan 1 18:03:18 2045 GMT hvrsslgen: Public Certificate written to 'saml-sp.pub_cert'. hvrsslgen: Private key written to 'saml-sp.priv_key'. hvrsslgen: Private key password: rEscC7Lo3GihLb4HODNhX9xIJPR3yD6RCQU+JsJ/ hvrsslgen: Example to configure High Volume Agent: hvragentconfig Agent_Server_Public_Certificate=@saml-sp.pub_cert Agent_Server_Private_Key=@saml-sp.priv_key Agent_Server_Private_Key_Password=rEscC7Lo3GihLb4HODNhX9xIJPR3yD6RCQU+JsJ/ hvrsslgen: Example to configure Hub Server: hvrreposconfig Agent_Client_Public_Certificate=@saml-sp.pub_cert Agent_Client_Private_Key=@saml-sp.priv_key Agent_Client_Private_Key_Password=rEscC7Lo3GihLb4HODNhX9xIJPR3yD6RCQU+JsJ/ hvrsslgen: Example to configure SAML to Hub Server: hvrhubserverconfig Saml_SP_Public_Certificate=@saml-sp.pub_cert Saml_SP_Private_Key=@saml-sp.priv_key Saml_SP_Private_Key_Password=rEscC7Lo3GihLb4HODNhX9xIJPR3yD6RCQU+JsJ/ hvrsslgen: Finished. (elapsed=0.238508s)From the hvrsslgen command's output, copy the example command line after
Example to configure SAML to Hub Serverand execute it:hvrhubserverconfig Saml_SP_Public_Certificate=@saml-sp.pub_cert Saml_SP_Private_Key=@saml-sp.priv_key Saml_SP_Private_Key_Password=password
Download SP Metadata
Retrieve the SP metadata file, which contains essential configuration details, to use in the Okta setup.
To download the SP metadata file, use the URL - https://fully-qualified-hostname:https_port/auth/latest/saml/metadata
Enter the URL https://fully-qualified-hostname:https_port/auth/latest/saml/metadata in the address bar of your browser.
Get SP Entity ID and Single sign-on URL
Extract key identifiers from the SP metadata file, such as the Entity ID and single sign-on URL, which are required for configuring the SAML application in Okta.
Open the downloaded SP metadata file in a text viewer.
Make a note of the following values, they are required for setting Up Okta (step 2.1.6):
The entityID attribute of the EntityDescriptor element. This is the SP Entity ID in Okta.
The Location attribute of the AssertionConsumerService element with Binding="urn:oasis:names:tc:SAML:2.0:bindings:HTTP-POST". This is the Single sign-on URL in Okta.
Set Up Okta
Create and configure a custom SAML application in Okta to integrate with HVR.
Create a Custom SAML Application
Add a new custom SAML application for HVR in Okta and configure its basic details.
Log in to your Okta Admin Console and go to Applications - Applications.
Click Create App Integration.
Select SAML 2.0 and click Next.
Enter a name for the application (e.g., HVR).
Click Next to switch to the Config SAML tab.
Under General, in the Single sign-on URL and Audience URI (SP Entity ID) fields, enter the values you that you had noted down step 1.4.
Set Name ID format to EmailAddress.
Click Next.
Select This is an internal app that we have created.
Click Finish.
Enable User Access to the Custom SAML Application
Grant access to the custom SAML application for HVR users in Okta.
Go to the Assignments tab.
Click Assign and select Assign to People.
Find the users to be assigned and click Assign.
Click Save and Go Back.
Click Done.
Download the IdP metadata
To complete setup in HVR, you need the IdP metadata. Follow these steps to get it:
Go to the Sign On tab.
Click View SAML setup instructions.
Copy the Idp metadata file content and save it as saml-idp-metadata.xml.
This file required to set the Saml_IDP_Metadata hub server property, while completing the HVR configuration (step 3.1).
Complete HVR Configuration
Finalize SAML authentication on the HVR Hub Server by uploading IdP metadata, enabling authentication methods, and adding SAML users.
Upload IdP Metadata
Upload the metadata file downloaded from Okta to the HVR server to establish trust with the Identity Provider (IdP).
Copy the saml-idp-metadata.xml that you downloaded (in step 2.3) to the server running the HVR Hub Server.
Configure the IdP metadata using the hvrhubserverconfig command:
hvrhubserverconfig Saml_IDP_Metadata=@saml-idp-metadata.xml
(Optional) Rename IdP Name
Configure the IdP Name using the command hvrhubserverconfig:
hvrhubserverconfig Saml_IDP_Name="Okta"
The default text for the SAML login button in the HVR UI is Sign in with SSO. The above command with the Saml_IDP_Name hub server property changes it to Okta.
Enable SAML Authentication
Enable SAML as the authentication method on the HVR Hub Server using the command hvrhubserverconfig:
hvrhubserverconfig Authentication_Method.saml=true
This explicitly enables the SAML authentication. By default, password authentication is the only method implicitly enabled. When you explicitly enable any (e.g, SAML) authentication method, all others will be disabled unless explicitly re-enabled.
To explicitly re-enable password authentication, run:
hvrhubserverconfig Authentication_Method.password=true
Few more commands related to enabling/disabling the authentication methods
To disable SAML authentication, run:
hvrhubserverconfig Authentication_Method.saml=falseTo restore the default authentication method (i.e., password authentication), run:
hvrhubserverconfig Authentication_Method=
Create SAML Users
Add SAML-based user in HVR to grant access via Single Sign-On.
Login into the HVR UI using an administrator account.
On the left sidebar, click System.
On the System page, go to the Users tab.
Click Add User.
In the New User dialog, choose SAML user as AUTHENTICATION.
Specify the USERNAME and FULL NAME.
The USERNAME must match the Okta email address.
Click Save.