Prerequisites

To implement V-OS Cloud seamless OpenID Connect (OIDC) authentication for services such as Salesforce, you need to have the followings ready in advance:

Exposed Directories: A directory for user authentication. The directory must be accessible from an external network. Currently, V-OS Cloud supports the following directories:

Note: You must configure your firewall settings on your directory server to allow external access to the LDAP TCP ports, i.e., 389 and/or 636. If you do not wish to open the said TCP ports publicly accessible to all, you can update your NAT configurations to only allow (whitelist) V-OS Cloud from the IP address 20.197.118.1 to access your directory.

  • Microsoft Active Directory (on-premises): The directory that is installed in an on-premises environment. If you use this directory service, you must make sure that the directory can be integrated with V-OS Cloud from outside of the enterprise network
  • Azure Active Directory (AAD): The AAD service associated with your Office 365 subscription. Because AAD only supports Secure LDAP (LDAPS), to integrate with V-OS Cloud, your AAD must activate AAD Domain Name Services (AAD DNS). See price and details of enabling and configuring AAD DNS in your AAD tenant from Microsoft
  • Online 3rd-Party Directory Services: If you use other 3rd-party directory services, you must configure your directory to allow external LDAP queries from V-OS Cloud
  • V-Key LDAP: If you do not have an existing directory service in place or wish to use a separate directory service for your V-OS Cloud usage, you can choose to use V-Key LDAP as the directory service provider
  • Other LDAPs: V-OS Cloud is compatible with other directory services that support LDAP authentication, such as OpenLDAP. You should configure the LDAP service to allow integration with V-OS Cloud

Note: If your organization uses both local AD and AAD to manage user credentials, you need to synchronize credentials between your local AD and AAD tenant. You need to install AAD connector, the Microsoft component for synchronizing user accounts from local AD to AAD.

Salesforce Subscription: The necessary subscription with a Sandbox license that allows OIDC integration.

Salesforce Admin Account: The Salesforce admin account that manages the Salesforce users of your organization.

Note: You shall also make sure that the firewall rules are in place to allow HTTP(s) communication with V-OS Cloud IDM.

Step 1: Configure Directory Connector

Firstly, setup directory connectors that can be used by the V-OS Cloud IDM to connect to the directories for authenticating the users. This is the 1st factor authentication. If you use different directories for different services, you can setup multiple directory connectors that connect to different directories. You shall have a directory connector that can be used for authenticating user login of the V-Key app and a directory connector for authenticating user access of the 3rd-party services such as Office 365, VPN, Salesforce, etc. It is fine to have just one directory connector for both the V-Key app and all services if they are sharing the same directory for different purposes.

Note: By default, one template directory connector is generated for you to configure. If you are reusing the same connector with other services that you have already configured in V-OS Cloud Dashboard previously, you can skip this step.

Setting Up Directory Connector for V-Key LDAP Directory

To set up the V-Key LDAP directory connector, do the following steps:

Note: If you already have your directory service in place and wish to configure a directory connector for your existing directory, go to Setting Up Directory Connector for 3rd-party Directories.

  1. Log in to the V-OS Cloud Dashboard with an admin account.
  2. Click Directories on the left sidebar.
  3. Click + CREATE at the upper-right corner of the page to create a new connector from scratch.

  4. Assign a Name to the directory connector for easy identification, e.g., V-Key Directory Connector. This can be any name.

    Create V-Key Directory Connector
    Fig 1: Create V-Key Directory Connector

  5. Select V-Key LDAP from the Type drop-down.

  6. Click Save to create the V-Key directory connector.
  7. Click the "pencil" icon next to the new directory connector that you have just created.

  8. You can choose to create users one by one or in batches.

    Add Users
    Fig 2: Add Users

  9. To create users one by one, do the following steps:

    1. Click the "+ user" icon at the middle-right of the page to show the add user popup.

      Add User - Single
      Fig 3: Add User - Single

    2. Key in the Username, Email, First Name, and Last Name of the user.

    3. Click SAVE. This triggers the creation of the user in the directory and sends an email to the user's email address. This email contains the username, temporary password, and login link to V-OS Cloud.

      Single User Entry
      Fig 4: Single User Entry

      Note: User logs in to V-OS Cloud for the first time will require the setting of a new password. The users must reset their password before the account is activated and can be used for V-Key app onboarding.

    4. Repeat the steps to continue creating another user.

  10. To create users in a batch, do the following steps:

    1. Click the "+ CSV" icon at the middle-right of the page to show the add user popup.

      Add User - Batch
      Fig 5: Add User - Batch

    2. Open the template and follow the format of the sample data to populate the user details. Only Username is mandatory in this CSV.

      CSV Template
      Fig 6: CSV Template

    3. After the CSV has been populated, drag the CSV file into the add user popup that you have opened in the previous step and click IMPORT. Similar to creating single users, the user entries in the CSV file will be automatically created in the directory. An email will also be sent to each user in the CSV file. If there is any error during this batch creation, a file containing the error that occurred during the process will be automatically generated.

  11. After the users are created in the directory, the directory connector is ready to be consumed by V-OS Cloud IDM.

Setting Up Directory Connector for 3rd-party Directories

To set up directory connectors, do the following steps:

  1. Log in to the V-OS Cloud Dashboard with an admin account.
  2. Click Directories on the left sidebar.
  3. Click the "pencil" icon of the template directory connector from the list on the Directories page or click + CREATE at the upper-right corner of the page if you want to create a new connector from scratch.

  4. Assign a Name to the directory connector for easy identification, e.g., XYZ Directory Connector. This can be any name.

    Edit Directory Connector - Part 1
    Fig 7: Edit Directory Connector - Part 1

  5. Select the type of directory connector from the Type drop-down, i.e., Azure AD, Local AD, Open LDAP, etc. If your directory type is not in the list, select Other.

  6. Key in your directory IP Address/Domain Name and Port.

    Note: The default ports are 389 (standard) and 636 (secured).

  7. If you use secured LDAP, enable the Secured LDAP option.

  8. Fill the Base DN field with the base distinguished name (DN) of your directory, e.g., dc=xyz,dc=com.

    Edit Directory Connector - Part 2
    Fig 8: Edit Directory Connector - Part 2

  9. Fill the User DN and Password fields with the DN and password of the directory admin account, respectively.

  10. Fill the Login Property.

    Note: This is the corresponding directory property that the user will use to log in, e.g., if a DN of the user John Doe is cn=john.doe,ou=users,dc=xyz,dc=com and John will be using the username john.doe to login. Then the Login Property shall be cn.

  11. Fill the Email Mapping Field with the email field in your directory, e.g., email.

  12. Fill the Display Name Mapping Field with the display name field in your directory, e.g., displayName.
  13. Fill the Phone Mapping Field with the phone field in your directory, e.g., telephoneNumber. This field is optional.
  14. Click Save to confirm the directory connector creation.
  15. You can test the connection by clicking on the "signal" icon at the right of the connection that you just created. You will be prompted with the error when V-OS Cloud IDM fails to establish the connection. Correct the error and test again until you see Connection successful!.
  16. Repeat the above steps if you have a separate directory for user authentication. Otherwise, the directory connector setup is done.

Note Integration step for different types of directories can be different. You should confirm with the directory provider for more details related to the directory that you use.

  • If you use Azure AD, you may refer to this page to know how to get connected with Azure AD
  • If your use on-premises AD, make sure that it can be accessed from an external network through the specified ports

Step 2: Configure OIDC Connector

After you have created the necessary directory connectors, you need to set up an OIDC connector that can be used by the V-OS Cloud Identity Management (IDM) to connect to the service for account access.

To create an OIDC connector, do the following steps:

  1. Log in to the V-OS Cloud Dashboard with an admin account.
  2. Click Connectors > OpenID Connect on the left sidebar.
  3. 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.
  4. Assign the Client Name to the OIDC connector, e.g., OIDC Connector.
  5. Fill the Redirect URL with some dummy value. This value of this field will be replaced in Step 5b: Setting Up Custom Domain.
  6. Click Save to create the OIDC connector.
  7. 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.
  8. Click on the OpenID Endpoint Configuration link to show the endpoint configuration.
  9. Make note of the values of Client ID, Client Secret, and the values of endpoint configuration. The values will be used in Step 5a: Configure Salesforce Login.

Step 3: Configure Service Instance

After the OIDC connector is created, you can assign the directory and OIDC connector to the service instance that comes with your subscription package. The assigned connector will be used for authenticating the service access.

To add connectors to the OIDC service instance, do the following steps:

  1. Log in to the V-OS Cloud Dashboard with an Admin account.
  2. Click Services on the left sidebar.
  3. Click the OIDC service instance that you want to edit from the list.
  4. Replace the Icon of the service instance, if desired.
  5. Edit the Instance Name and Description.
  6. Select the OIDC connector that you have created from the OpenID Connect Connector drop-down. Click the "pencil" icon at the right of the selected directory connector to edit the connector, if necessary.
  7. Click Save to save the changes.
  8. Click START, if available, at the upper-right corner to start the OIDC service instance.

Step 4: Configuring Token Pack

After the service instance is set up and started, you can start creating a token pack, which can be sent to the V-Key app users, in the form of a QR code, for onboarding purpose.

To create and send a token pack, do the following steps:

  1. Log in to the V-OS Cloud Dashboard with an admin account.
  2. Click Token Packs on the left sidebar.

  3. Click the "pencil" icon of the pre-generated token pack from the list.

    Token Packs
    Fig 9: Token Packs

  4. Assign a Name to the token pack for easy identification, e.g., Service Token Pack. This can be any name.

    Edit Token Pack - Connector
    Fig 10: Edit Token Pack - Connector

  5. Click the icon field and assign an icon to the token pack, if desired.

  6. 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 V-Key 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.

  7. Pick the desired Service that you want to enable in the token pack.

    Service Selection
    Fig 11: 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.

  8. Click Save to create the token pack.

  9. If you wish to allow users connected to the selected network to be exempted from manual token provisioning, continue with the following steps. Otherwise, the created token pack is ready to be tested before being sent to app users for onboarding.
  10. Click the TRUSTED NETWORKS tab.
  11. Click + CREATE at the upper-right corner.

  12. Assign a Name to the trusted network entry for easy identification. This can be any name.

    Create Trusted IP
    Fig 12: Create Trusted IP

  13. Key in the IP Address that you want to add as the trusted network.

  14. Key in the Description, as desired. This is optional.

  15. Click Save to add the trusted IP address for the token pack.

    Trusted Networks
    Fig 13: Trusted Networks

  16. Go back to the INFO tab and click Save to save the token pack.

Step 5a: Configure Salesforce Authentication Provider

After the token pack is configured, it is ready to be sent to the users for onboarding using the V-Key app. However, to use OIDC with Salesforce, you need to do the necessary setup at Salesforce.

To configure Salesforce to allow authentication through OIDC, do the following steps:

Note: It is recommended to do the configurations first on a Salesforce sandbox organization before applying the same to the production organization.

  1. Log in to Salesforce with an admin account.
  2. Click the Setup button under the "gear" icon at the upper-right corner to go to the Setup page.
  3. Key in Auth. Providers in the Quick Find box, then select Auth. Providers.
  4. Click New to create a new authentication provider.
  5. Set Provider Type to Open ID Connect.
  6. Fill in Name as desired. URL Suffix is generated automatically.
  7. Refer to the values on the Edit OpenID Connect page that you have noted down in Step 2: Configure OIDC Connector. If you don't have the value in hand, go to the Edit OpenID Connect page of the V-OS Cloud Dashboard and get the necessary values.
  8. Fill the Consumer Key field with the Client ID value obtained from Edit OpenID Connect page.
  9. Fill the Consumer Secret field with the Client Secret value obtained from Edit OpenID Connect page.
  10. Fill the Authorize Endpoint URL with the value of authorization_endpoint key from the OpenID Endpoint Configuration on the Edit OpenID Connect page.

  11. Fill the same value onto the Token Endpoint URL and User Info Endpoint URL fields and replace auth at the end of the URL with token and userInfo, respectively. The result will look something like https://░░░░░░░░/token and https://░░░░░░░░/userInfo.

    Auth. Provider Configurations
    Fig 14: Auth. Provider Configurations

  12. Fill the Token Issuer field with the value of issuer key from the OpenID Endpoint Configuration on the Edit OpenID Connect page.

  13. The rest of the information is optional, fill in as desired.

  14. After the fields are filled, click Save. A list of Salesforce configurations is then shown at the bottom of the page.

    Note: The URLs at the Salesforce Configuration section at the bottom of the page will be refreshed after the customer domain is applied. Only use the URLs after the customer domain is successfully configured. See Step 5b: Setting Up Custom Domain.

Step 5b: Set Up Custom Domain

After the authentication provider is created, it is necessary to set up a custom domain that will allow redirecting the Salesforce login page.

To set up a custom domain on Salesforce, do the following steps:

  1. Key in My Domain in the Quick Find box, then select My Domain.

  2. Apply for a domain of your choice, e.g., xyz-company.

    Note: The new domain takes a brief moment to be effective.

  3. After the domain is effective, you will see the Authentication Configuration section at the bottom of the page. Click Edit.

  4. Check the authentication provider that you have created in Step 5a: Configure Salesforce Authentication Provider in the Authentication Service section.
  5. If you wish to give your users the flexibility to choose from whether to log in using the default Salesforce Login form or V-OS Cloud, leave the Login Form checked. Otherwise, uncheck the Login Form.
  6. Update the rest of the settings, as desired.
  7. Click Save.
  8. This completes the custom domain setup. Verify the effectiveness of your custom domain configuration by going to the Salesforce login page (https://login.salesforce.com).
  9. Click on the Use Custom Domain link.

  10. Key in your custom domain, e.g., xyz-company and click Continue.

    Use Custom Domain
    Fig 15: Use Custom Domain

  11. You should see the default Salesforce login form and the V-OS Cloud login option on the page. Click on the V-OS Cloud button to go to the V-OS Cloud login page. If you did not enable the default Salesforce login form, you should have been directed to the V-OS Cloud login page directly after you click Continue in the previous step. This confirms that the custom domain works as expected.

  12. Go back to the Salesforce Setup page.
  13. Key in Auth. Providers in the Quick Find box, then select Auth. Providers.
  14. Click the authentication provider that you have created in Step 5a: Configure Salesforce Authentication Provider.
  15. Copy the value of Callback URL under the Salesforce Configuration section and paste it onto the Redirect URL field of the OIDC connector that you have created in Step 2: Configure OIDC Connector.

Step 5c: Adding Apex Class

After the custom domain is set up, you need to create an Apex class that will bridge between V-OS Cloud IDM and Salesforce after the user has been successfully authenticated by V-OS Cloud. A default Apex class created by V-Key will be supplied. You will only need to make a very minimal change to the default Apex class to get the service working.

Note: Due to the constraints set by Salesforce, you cannot create an Apex class in an active organization. You need to deploy the Apex class in a sandbox organization and migrate it to the production organization.

To add Apex class on Salesforce, do the following steps:

  1. Create a sandbox organization by following the steps provided by Salesforce at https://help.salesforce.com/articleView?id=data_sandbox_create.htm&type=5.
  2. Log in to the new sandbox organization that you have just created.
  3. Key in Apex Classes in the Quick Find box, then select Apex Classes.
  4. Click New.
  5. Open the Apex class file that is supplied by V-Key and copy all its contents.
  6. Paste the contents copied into the Apex Class Edit window.
  7. Change the value of ORG_SUFFIX to your directory email domain.

  8. Make other changes as desired.

    Note: If you are familiar with Apex development and wish to customize the Apex class to include more features, feel free to make necessary modifications to the default Apex class supplied by V-Key.

  9. Click Save after all the changes are done. Make note of the class name.

  10. Click the Compile all classes link to compile all the Apex classes.
  11. Key in Outbound Change Sets in the Quick Find box, then select Outbound Change Sets.
  12. Click New.
  13. Key in the Name, e.g., V-OS Cloud Change Set, and Description of this changeset and click Save.
  14. Click Add in the Change Set Components section.
  15. From the Component Type drop-down, select the Apex Class option.
  16. Check the checkbox of the new Apex class that you have created in the previous steps.
  17. Click Add To Change Set.
  18. Log back into your production organization.
  19. Key in Inbound Change Sets in the Quick Find box, then select Inbound Change Sets.
  20. Click Deploy next to the changeset you want to deploy, e.g., V-OS Cloud Change Set.
  21. After the changeset is successfully deployed, Key in Auth. Providers in the Quick Find box, then select Auth. Providers.
  22. Open on the authentication provider setting that you have created in Step 5a: Configure Salesforce Authentication Provider.
  23. Click Edit.
  24. Set the Registration Handler to the Apex class that you have just created.
  25. Set the Execute Registration As to the admin user account.
  26. Click Save. This completes the steps required on the Salesforce Setup page.

Step 6: Test Your Setup

In this step, all setups should have been done. You should test your setup before distributing the token pack to the app users.

To test your setup, do the following steps:

  1. Log in to the V-OS Cloud Dashboard with an admin account.
  2. Click Token Packs on the left sidebar.
  3. Click the "envelope" icon at the right of the token pack that you wish to test from the list.
  4. Input your email and click SEND. An email containing the QR code of the token pack is sent to your inbox.

  5. Download and install the V-Key app if you have not done so. Click or scan the applicable QR code to start the installation:

  6. Launch the V-Key app on your mobile device after installation and scan the token pack QR code that you have received.

  7. Type in your username and password. This username and password should be tagged to an account in the directory that you had specified during token pack creation.

    Note: The username is the value of the user entry attribute that you have specified as the Login Property in when you create/configure your directory. Go back to the directory connector page to confirm if you are uncertain about this. If you use V-Key LDAP, it will be the same username of your account in the directory.

  8. After you have successfully logged in, you will be prompted to provide an email address to receive the email that contains the QR code of the soft token.

  9. Upon receiving the QR code, scan the QR code with the V-Key app, and follow the prompts to complete the app activation.

  10. Once the app is activated, go to the Salesforce login page at https://login.salesforce.com.

  11. Click Use Custom Domain.
  12. Key in the custom domain that you have created in the previous steps and click Continue.
  13. If you are not directed to the V-OS Cloud login page directly, click on the V-OS Cloud button.
  14. Key in the username of your account on the V-OS Cloud login page and click Send Me A Push.
  15. You shall receive a push notification popped up on your mobile device requesting login approval.
  16. Tap Approve on the V-Key app popup to approve the login request. If you can connect to VPN successfully after tapping Approve on the popup, the token pack is correctly configured. You can proceed to distribute the token pack to the end-users.

For more details of the V-Key app, see V-Key User Guide. For more details of V-OS Cloud IDM, see the Docs. For technical support, contact V-OS Cloud via cloud-support@v-key.com

Salesforce Seamless Login Flow Diagram

Salesforce Seamless Login Flow Diagram
Fig 18: Salesforce Seamless Login Flow Diagram
  1. The user initiates a Salesforce login through the custom domain.
  2. Salesforce redirects the login to the V-OS Cloud Login page.
  3. V-OS Cloud IDM matches the user triggers the V-OS PKI Suite to send authentication push notification.
  4. V-OS PKI Suite sends a push notification to the user's registered device to verify the user.
  5. The user receives and approves the login request by tapping on the approve button on the push notification popup.
  6. The V-Key app responds to the V-OS PKI Suite.
  7. V-OS PKI Suite notifies V-OS Cloud IDM about the user's approval.
  8. V-OS Cloud IDM communicates to the Salesforce through the OIDC connector.
  9. OIDC connector sends the ID token to Salesforce.
  10. Salesforce receives the ID token and logs in the user.