This document contains detailed information relating to V-Key's
various Products / Services, for which all copyright, trademark(s),
patent(s) and/or trade secrets belong to V-Key Inc / Pte Ltd. TAKE
NOTICE that this should not be circulated to competitors or
disclosed to third parties (other than directors, officers,
employees, and agents of the Customer).
Note: Due to low popularity of CDMA mobile
devices and mobile network operators are phasing out CDMA network,
V-Key does not test any V-Key software product on mobile devices
that run on CDMA network. The compatibility of the V-Key software
products on CDMA mobile devices is unknown.
Dismiss
Revision History
Ver.
Date
Description/Changes
1.0
2026-03-26
Initial release
Dismiss
VSA SAML
Integration Guide
Introduction
V-OS Cloud provides many services that will help organizations to implement secure authentication mechanisms to protect their services easily and effortlessly.
VSA SAML (Security Assertion Markup Language) solution is based on the V-OS PKI Token solution hosted by the key components on V-OS Cloud, the Identity Management (IDM) portal, and the V-Key Smart Authenticator app that is available on both Android and iOS. These cloud components are used for integrating the third-party services that you wish to implement secure authentication and authorization through directory services and authentication protocol connectors.
The services that have been verified to be compatible with the VSA SAML solution are:
VSA SAML solution consumes the cloud-hosted V-Key PKI suite, VSA IDM, and V-Key Smart Authenticator (VSA) app that are available to your users to connect from anywhere, anytime.
The following architecture diagram shows how VSA interacts with SAML enabled services.
Fig 1: VSA SAML Solution Architecture
VSA IDM acts as an IdP server and uses a SAML2.0 connector that enables service providers, such as Office, to send requests for SAML2.0 authentication.
VSA IDM provides directory connectors that allow you to authenticate users through existing directory credentials, both online directories, such as Microsoft Entra ID and on-premises directories, such as Active Directory in the local network for primary authentication before raising the secondary authentication to VSA app.
VSA Components
V-OS Cloud Portal
The V-OS Cloud Portal is the web interface where you can sign up, subscribe, manage subscriptions, services, payments, and orders. The URL to the Portal is https://cloud.v-key.com
V-OS Cloud Dashboard
The V-OS Cloud Dashboard is the client area restricted by access accounts. You can log in to the Dashboard with either a root, admin, or supervisor account. You can configure (environments, services, and connectors), deploy services, and manage service users of your organization through the Dashboard. Only root and admin users have the right to do configurations and modifications in the Dashboard. Users with supervisor access right have only view access to the Dashboard. The URL to login to the Dashboard is https://cloud.v-key.com/login.
VSA IDM
The VSA Identity Management (IDM) is the access gateway that handles communication between the V-OS Cloud and various components such as directories, RADIUS server, SAML server, etc. that are available in your organization for initiating and performing the authorization and authentication of end-users.
V-Key Smart Authenticator (VSA) App
The VSA app is a mobile app developed for V-OS Cloud that can be used to do 2nd factor authentication for service accesses. It serves as a virtual token to help end-users to manage accounts and do authentication approval. The VSA app is mandatory for end-users to utilize the VSA services if your organization subscribed to the Free or Professional plan. The VSA app can be downloaded from the Apple App Store and Google Play Store. It is recommended to always upgrade your VSA app to the latest version.
Organizational/Third-party Components
Directory
The directory service that the credentials of the end-users are stored. VSA IDM will communicate to this directory by LDAP protocol to authorize users during user login, VSA app activation, and first authentication. It is mandatory to expose this directory for VSA IDM to query during authorization and authentication.
Please refer [Directory Integration guide] for details.
Third-party Service Subscription
The application of your organization or third-party service that will be integrated with the VSA SAML2.0 solution.
Flow Diagram
The following diagram shows the communication flow in V-OS Cloud when a user tries to log in to the third-party service with VSA SAML solution integrated.
Fig 2: Flow of VSA SAML Solution
The sample flow of the VSA SAML solution is as follows:
Note: The primary directory is used for authenticating the user when logging in to the VSA app. The secondary directory is used for authenticating the user when trying to connect to the VPN service. The primary and secondary directories can be the same directory or different directories. When a user tries to log in to the VSA app, VSA IDM queries the primary directory to authenticate the user.
Steps 1.1 - 1.4: The user triggers the third-party service login session through the browser or app. The user is then redirected to the Login page on VSA IDM to input their credentials for authentication.
Steps 2.1 - 2.6: VSAd IDM does 1st factor authentication with the secondary directory, and triggers 2nd factor authentication request to VSA app on user’s mobile device.
Steps 3.1 - 3.6: The user confirms the 2FA request on the VSA app which will trigger the confirmation to be sent back to VSA IDM that responds to the third-party service to allow service access.
SAML Integration with Third Party Service
To implement VSA SAML authentication for third party service such as OKTA or Salesforce, you need to execute following steps as prerequisites.
Directory Connector Configuration
SAML Connector Configuration
Service Instance Configuration
Token Pack Configuration
Configure Directory Connector
Currently, VSA supports the following directories:
V-Key AD
Local AD
Open AD
Microsoft Entra ID (formerly Azure Active Directory)
After you have created the necessary directory connector, you need to set up a connector for SAML that can be used by the VSA IDM to connect to the SAML 2.0 server.
To create the SAML connector, do the following steps:
Log in to the IDM Dashboard with an admin account.
Click Connectors > SAML 2.0 connector on the left sidebar.
Fig 3: Create SAML Connector
Click the "pencil" icon of the template SAML connector from the list or click + CREATE on the upper-right corner if you want to create a new connector from scratch.
Choose Generic SAML 2.0 as connector type
Assign the Name to the SAML connector, e.g., OKTA-SAML Connector.
Fill the URL suffix with a url suffix value such as com or org.
Click Save to create the SAML 2.0 connector.
After the SAML connector is created, click the "pencil" icon of the SAML connector that you just created. You should see the Identity Provider information auto-generated.
Make note of the values of endpoint configuration from Identity Provider section.
Configure Service Instance
After the SAML connector is created, you can create the third party service instance and assign the directory and SAML connector to the third party service instance. The assigned connector will be used for authenticating the third party service access.
To create the service instance and add connectors to it, do the following steps:
Log in to the VSA IDM portal with an Admin account.
Click Services on the left sidebar.
Click Create to add new service and select Generic SAML2.0 SSO Service Service.
Select relevant Subscription and Token Pack.
Add the Service Name.
Select the SAML connector that you have created from the SAML 2.0 drop-down.
Click Save to save the changes.
Add the Service Instance Description.
The service will be already started. Click Save to save the description.
Configure Token Pack
After the service instance is set up and started, you can check token pack configurations. A token pack is a QR code that contains the primary directory connector that is used for authenticating the users while they logging in to the VSA app. The token pack also contains the configurations of the server environment that you have set up and the service instances that you have subscribed to. Token Pack is created at the time of creation of subscription for Tenants.
To check token pack configuration, do the following steps:
Log in to the VSA IDM portal with an admin account.
Click Token Packs on the left sidebar.
Click the "pencil" icon of the pre-generated token pack from the list.
Fig 4: Configure Token Pack
Check Token Pack Configurations.
Fig 5: Edit Token Pack
Click the icon field and assign an icon to the token pack, if desired.
Select the Primary Directory and Theme to be assigned to the token pack from the respective dropdown.
Note: The Primary Directory is the directory used for authenticating users of the VSA app. It can be the same or different directory configured in the service instance. The Theme is the theme that you wish to apply to your VSA app when this token pack is used. You can configure different themes for different token packs.
Pick the desired Service that you want to enable in the token pack.
Fig 6: Service Selection
Note: A token pack can contain the 2FA services for multiple services. If you are intending to have multiple services under the same token pack, select the service accordingly by toggling the "power plug" icon.
Click Save if you have made changes to token pack.
OKTA - SAML Configuration
After the token pack is configured, it is ready to be sent to the users for onboarding using the VSA app. However, to use SAML with OKTA, you need to do the necessary setup at OKTA.
To configure OKTA to allow authentication through SAML2.0, execute the following steps.
Log in to OKTA with an admin account.
Navigate to Security → Identity Providers.
Select Add Identity Providers
Select SAML 2.0 IdP & click next
Fig 7: OpenID Connect IdP
General Settings are as follows.
Input any SAML provider name
IdP Usage: select Factor only
Select Use Persistent Name ID
Enter SAML Protocol Settings.
Get IdP Issuer URI & IdP Single Sign-On URL from created VSA IDM SAML 2.0 Connector.
Copy Assertion Consumer Service URL value from OKTA and paste it in the field Assertion Consumer Service URL field on IDM portal.
Copy Audience URI and paste it in Entity ID field.
Select other parameter values as shown in following figure. These parameters include NameID Format NameID Attribute, SendAttribute, Signature Algorithm.
Save the SAML Connector settings on IDM portal.
Fig 10: SAML Connector Settings on IDM
Open OKTA Admin account and navigate to Security → Authenticators
Select Add Authenticator
Select IdP Authenticator
Select created SAML Provider & save
Fig 11: OKTA OIDC Provider
Now, test login with provided configuration.
a. Login OKTA by providing username & password. You should see new 2FA login option for SAML.
Fig 12: 2FA Login
b. Click SAML Authenticator Setup to continue.
Fig 13: 2FA Login
c. Click Verify. You will be redirected to SAML login page of V-Key.
Fig 14: V-Key Login
Create IdP Signature Certificate File
To create IdP Signature Certificate file from Certificate data field of created VSA IDM SAML 2.0 Connector, execute below steps.
To create a X.509 certificate from SAML metadata, copy the certificate data from VSA IDM SAML 2.0 Connector and paste this data into a plain text editor (like Notepad), ensuring it is formatted correctly.
Add Headers/Footers: Add the following lines to the file:
This section describes the process of configuring Office 365 Login using SAML IDM Connector. With this configuration, the IDM system functions as external Identity Provider (IdP) and verifies user identities using your Microsoft Entra ID tenant.
Prerequisites
An IDM tenant that has Microsoft Entra ID Directory and has completed integrating and syncing the users from Microsoft Entra ID tenant.
In the created SAML connector configuration, select Connector Type as O365 SAML2.0
Enter Name & URL Suffix as required
Fig 15: Sample configuration
Switch on the Enable Federate Configuration
Enter the Domain for federation (eg: dev-cloud.v-key.com)
Fig 16: Domain Federation
In the Advance fields:
- NameID Attribute should be email / username
- Other fields should be as default
Fig 17: Advance Fields
Click on SAVE to save the configuration
To prepare configuration for Microsoft Entra ID, you should collect following data from the SAML connector configuration:
- Issuer
- Login url
- Logout url
- Certificate
Fig 18: SAML Configurations
Microsoft Entra ID Tenant Configuration
Federate the custom domain in Microsoft Entra ID with your IDM SAML identity provider.
The custom domain(verified) on the Microsoft Entra ID tenant, which is being used when creating your users, should be federated with the SAML connector on IDM.
Install and connect the MgGraph module to connect your Microsoft Entra ID tenant, using PowerShell
Log in to the prompt / navigated page as Microsoft Entra ID Admin
Change the domain from managed to federated mode
Using Update-MgDomain to change from Managed to Federated is currently not supported.
You should use New-MgDomainFederationConfiguration and insert the URLs and certificate created during Configuration of the SAML connector
After federating the domain with IDM SAML connector, you can’t create a new user on the Microsoft Entra ID Portal UI anymore. You should create user using MgGraph via PowerShell Cmdlet:
Note: The immutableId (OnPremisesImmutableId) is created manually from client side and we will set it equal to the username/email. Currently, it is a limitation.
Redirect to the IDM QR code page, using VSA to scan and proceed to authenticate
Fig 22: Redirect to IDM
Completing these steps, you will be navigated to the Office 365 page to use the O365 services.
Update ImmutableID for Microsoft Entra ID users
If your custom domain contains users while it is configured as a managed domain in Microsoft Entra ID, those users will not have an ImmutableID after the domain is federated. You should set the ImmutableID for the first time, using:
If your domain is federated and your users already have an ImmutableID, you can’t update their ImmutableID in a normal way by Update-MgUser. To do that, the users should change the email domain to an un-federated one, then update the ImmutableID and re-establish federation by changing UPN back to original domain:
Example configuration:
$userUPN = “user1@dev-cloud.v-key.com"
$expectedImmutableId = “randomstring” #replace randomstring with the value you expected
# 2. Get the Entra ID User Object
$azureADUser = Get-MgUser -Filter "UserPrincipalName eq '$userUPN'"
# 3. Remove user federation.
# User must be unfederated before the Immutable ID can be updated.
# Assumes user2gmail.com is a non-federated domain in your tenant.
$newUPN = $userUPN.Replace("dev-cloud.v-key.com", "user2gmail.onmicrosoft.com")
Update-MgUser -UserId $azureADUser.Id -UserPrincipalName $newUPN
# 4. Re-fetch the Entra ID user after removing federation
$azureADUser = Get-MgUser -Filter "UserPrincipalName eq '$newUPN'"
# 5. Update OnPremisesImmutableId with the expected value.
Update-MgUser -UserId $azureADUser.Id -OnPremisesImmutableId $expectedImmutableId
# 6. Re-establish federation
# Change UPN back to original domain.
Update-MgUser -UserId $azureADUser.Id -UserPrincipalName $userUPN
Disable Microsoft Authenticator verification for the user’s first login
If you don’t want the users to do the verification step via Microsoft Authenticator app for 1st login attempt:
Go to Microsoft Entra ID > Security > Authentication Methods.
Disable 2 options : Microsoft Authenticator and Third-party software OATH tokens
Fig 23: Authentication Method Policies
Gaps and Limitations
Set the ImmutableID as the username/email on Microsoft Entra ID for mapping the NameID sent in the SAML response from IDM.
As the current mapping policy, Microsoft Entra ID is using the ImmutableID to compare with the NameID attribute sent from IDM.
On O365 V-key PROD , we can log in O365 successfully as the user from IDM side and Microsoft Entra ID side are both synced from a Window VM machine - V-Key local directory management. So objectGUID and ImmutableId will match together.
With our approach, we use Microsoft Entra ID (Azure) to manage the Directory, and configure an AzureAD type directory on IDM to sync the users. But the ObjectGUID synced is empty, even if it is get successfully (by using LocalAD type directory to sync), the ObjectGUID doesn’t match with the ImmutableID on Azure. So Azure doesn’t recognize the ObjectGUID sent in the SAML response and show this error:
Error: AADSTS51004: The user account does not exist in the directory.To sign into this application, the account must be added to the directory.
Fig 24: ErrorFig 25: Error-details
=> We should set the ImmutableID as the username/email and set the NameID attribute to username/email for successfully mapping.
Microsoft Entra ID type Directory on IDM cannot sync/generate the objectGUID value of the user:
(objectGUID is a required value in the SAML authentication process)
=> We should configure a LocalAD type directory with the same configuration info. Then the user sync has the objectGUID value.
LocalAD type:
Fig 26: Local AD Configuration
Microsoft Entra ID type:
Fig 27: Microsoft Entra ID Configuration
Palo Alto - SAML Configuration
This section describes the process of configuring Palo Alto Login using SAML IDM Connector. With this configuration, the IDM system functions as external Identity Provider (IdP) and verifies user identities using V-Key AD.
Later create a temporary SAML connector with placeholder values in the required fields. Retrieve the Login URL & certificate information as follows.
Fig 28: Create Temporary SAML Connector
Palo Alto Dashboard Configuration
Palo Alto requires importing the public certificate of SAML connector on IDM to verify SAML Responses, and a PKCS#12 certificate containing both the private and public keys for the signing of SAML authentication requests.
Go to Device → Certificate Management → Certificates → Device Certificates → Import
Add V-Key SAML Certificate
Certificate Type - local
File Format → PEM
Certificate Name → Enter a valid name
Certificate: Retrieve Certificate from SAML Connector page on IDM and Create certificate
Fig 29: SAML Certificate
After adding certificate, the system displays the details as illustrated below.
Identity Provider SSO URL & SLO URL get from created SAML Connector from IDM
Other fields keep as default
Fig 35: SAML IdP Server Profile
Configure an authentication profile for SAML.
Go to Device → Authentication Profile → Add -> Authentication tab:
Type: SAML
IdP Server Profile: <Select created SAML profile above>
Certificate for Signing Requests: <Select imported PKCS12 certificate>
Certificate Profile: <Select created Certificate Profile at Step 3>
Username Attribute: username
Fig 36: Authentication Profile-1
Allow all users in advanced tab.
Fig 37: Authentication Profile-2
Assign the authentication profile to users that require authentication.
Assign the authentication profile to administrator accounts that you manage locally on the firewall.
To Create an administrator account
Go to Device → Administrators → Add
Assign SAML authentication profile
Fig 38: Create Administrator
After adding an administrator account for use with SAML authentication profile
Fig 39: Administrators
Administrator accounts that you manage externally in the IdP identity store.
Select Device → SetupManagement
Edit the Authentication Settings
Select the Authentication Profile you configured.
Fig 40: Administrators
For externally managed users, “adminrole” attribute must be present in the IDP response and should be mapped to one of the existing roles in firewall (Device → Admin Roles).
Fig 41: adminrole
8: Firewall SAML Metadata to configure on V-KEY IDM
Once you have successfully configured SAML authentication profile, under Device → Authentication Profile, click on metadata link. Enter values as follows
Fig 42: metadata
Service → management
Choose authentication profile configured earlier.
Type → IP or HostName, Enter firewall IP.
Fig 43: SAML Metadata Export
After you click OK, you can download xml file containing metadata which can be used for configuring firewall on IDM side.
After completing all the above configurations, commit the changes for Palo Alto and proceed with the configuration on the IDM Cloud Portal as described in Part B below.
Limitations:
Unmanaged user flow doesn’t support, in both options mentioned below, due to that we can only support one user login into the Palo Alto systems.
V-Key AD doesn’t support mapping custom attribute(e.g Role),
If we use Customer AD, customer AD supports the custom attribute, but IDM doesn’t have mechanism to fetch the attribute.
Integration with V-Key IDM Cloud Portal
Setup IDM Portal & provision user
Configure SAML Connector
Open the temporary SAML connector created in the Prerequisites section above and update the following parameters:
Entity ID: <Retrieve from downloaded metadata file on Palo Alto>
Assertion Consumer Service URL: <get from downloaded metadata file on Palo Alto>
