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-10
Initial release
Dismiss
VSA OIDC
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 OpenID Connect (OIDC) 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 V-OS Cloud OIDC solution are:
OKTA
Salesforce
Solution Architecture
VSA OIDC 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 OIDC enabled services.
Fig 1: VSA OIDC Solution Architecture
VSA IDM acts as the OIDC Provider and uses an OIDC connector that enables the OIDC proxy to send the authentication requests.
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 necessary subscription is required for the third-party service (such as Salesforce or OKTA) that needs to be seamlessly accessed through V-OS Cloud. The third-party service will be integrated with VSA IDM by OIDC protocol. The third-party service acts as an OIDC service provider, and VSA IDM acts as an OIDC Identity provider. VSA IDM receives an OIDC authentication request from the third-party service, and triggers an authentication request with the VSA app, then responds OIDC token to the third-party service.
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 OIDC solution integrated.
Fig 2: Flow of VSA OIDC Solution
The sample flow of the VSA OIDC 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.5: The user triggers the login request from the third-party service such as OKTA then redirected to the VSA IDM login page.
Steps 2.1 - 2.2: VSA IDM triggers authentication requests to the VSA app on the user’s mobile device.
Steps 3.1 - 3.6: The user confirms the login request on the VSA app that will respond to VSA IDM and then back to the third-party service to grant the login session.
OIDC Integration with Third Party Service
To implement VSA OpenID Connect (OIDC) authentication for third party service such as OKTA or Salesforce, you need to execute following steps as prerequisites.
Directory Connector Configuration
OIDC 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 OIDC that can be used by the VSA IDM to connect to the OIDC server.
To create the OIDC connector, do the following steps:
Log in to the IDM Dashboard with an admin account.
Click Connectors > OpenID Connect on the left sidebar.
Fig 3: Create OIDC Connector
Click the "pencil" icon of the template OIDC connector from the list or click + CREATE on the upper-right corner if you want to create a new connector from scratch.
Assign the Client Name to the OIDC connector, e.g., OKTA-OIDC Connector.
Fill the Redirect URL with some dummy value. The value of this field will be re-filled later.
Click Save to create the OIDC connector.
After the OIDC connector is created, click the "pencil" icon of the OIDC connector that you just created. You should see the Client ID and Client Secret auto-generated.
Click on the OpenID Endpoint Configuration link to show the endpoint configuration.
Make note of the values of Client ID, Client Secret, and the values of endpoint configuration.
Configure Service Instance
After the OIDC connector is created, you can create the third party service instance and assign the directory and OIDC 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 OpenID Connect SSO Service.
Select relevant Subscription and Token Pack.
Add the Service Name.
Select the OIDC connector that you have created from the OpenID Connect 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 V-Key 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 V-Key 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 - OIDC 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 OIDC with OKTA, you need to do the necessary setup at OKTA.
To configure OKTA to allow authentication through OIDC, execute the following steps.
