Prerequisites

To implement V-OS Cloud MFA for Microsoft 365 / SAML2.0 service, 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.43.189.122 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 priceand 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.

Note: V-Key LDAP is currently not supported on the Office 365 service. You shall avoid using V-Key LDAP as the directory for Office 365.

Microsoft Office 365 Service Tenant: The Office 365 tenant of the organization that needs to be protected by the 2FA service of V-OS Cloud. Microsoft Office 365 service will be integrated with V-OS Cloud IDM by SAML2.0 protocol. Office 365 is a SAML2.0 service provider, and V-OS Cloud IDM is a SAML2.0 Identity provider. V-OS Cloud IDM receives a SAML2.0 authentication request from Office 365, and triggers 2FA with V-Key app, then respond SAML2.0 assertion to Office 365 service.

Microsoft Office Global Administration Account: The Administration account provided while registering for Microsoft Office 365. The account credentials are necessary for connecting Office 365 servers and federating.

Verified Domain Name: The domain which will be federated between the Office 365 tenant and the V-OS Cloud Identity Management (IDM) Login page. You need to verify this domain on your Office 365 tenant. Go to this [link](https://docs.microsoft.com/en-us/Office 365/admin/setup/add-domain?view=o365-worldwide) for steps on how to add a domain to Office 365 tenant.

Note: Take note that the domain to federate cannot be the default domain of Microsoft Office 365 tenant, which is with the ‘.onmicrosoft.com’ postfix.

Enabled Modern Authentication: To support 2FA for Outlook and Skype apps, your organization must enable Modern Authentication on Microsoft Exchange servers of Office 365 tenant. Go to the following link for steps on how to enable Modern Authentication.

Window PC/Server, PowerShell, and MSOnline Module: To federate (the activity that binds Login page of Office 365 tenant to V-OS Cloud IDM Login page, or in other words Single-Sign-On settings), you need to run scripts or commands in PowerShell which uses MSOnline module to remotely connect to Microsoft Exchange from your local Window PC/server. Refer to Federation Guide for detail steps

Office 365 Client: The web, desktop, or mobile applications of Microsoft 365, such as Outlook, Teams, OneDrive, and Skype for Business, the ones that user needs to log in to.

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.

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 1: 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 2: 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 Propertyshall 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 SAML Connector

After you have created the necessary directory connectors, you need to set up a SAML connector that can be used by the V-OS Cloud IDM to connect to the SAML server for 2FA.

To create a SAML connector, do the following steps:

  1. Login to the V-OS Cloud Dashboard with an admin account.
  2. Select Connectors > SAML on the left navigation bar.
  3. Select the pre-generated directory connector from the list or select + CREATE on the upper-right corner if you want to create a new connector from scratch.
  4. Assign a name to the SAML connector, e.g., Office 365 Connector.
  5. Fill in all the fields on the page. All fields are required. Select Tooltip in each field for more explanation.
  6. Select Federation Script if you have not enabled domain federation of your Office 365 service.
  7. Select GENERATE SCRIPT to generate the script required to federate your Office 365 tenant domain.
  8. Copy or download the script and execute the script in PowerShell.
  9. Select Save to create the SAML connector.

Step 3: Configure Service Instance

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

To add connectors to the Office 365 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 navigation bar.
  3. Click the SAML service instance that you want to edit from the screen.
  4. Replace the Icon of the service instance, if desired.
  5. Edit the Instance Name and Description.
  6. Select the directory connector for Office 365 from the Directory dropdown. Select the pencil icon at the right to edit the connector if necessary.
  7. Select the SAML connector from the SAML Connector dropdown. Select the pencil icon at the right to edit the connector if necessary.
  8. Select Save to save the changes.
  9. Select START, if available, at the upper-right corner to start the 2FA 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 PacksFig 3: 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 4: 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 SelectionFig 5: 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 6: 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 7: Trusted Networks
  16. Go back to the INFO tab and click Save to save the token pack.

Step 5: 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, try to log in to your Office 365 account via the web browser or an Office app. You should be able to see the Office 365 sign-in page is redirected to the V-OS Cloud IDM login page. This means that the domain federation is successful.
  11. Continue to input your credentials on the V-OS Cloud IDM login page and login, you should receive a push notification popped up on your mobile device requesting for login approval.
  12. Tap Approve on the V-Key app popup to approve the login request. If you can be logged in to the Office 365 service 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

2FA for Office 365/SAML2.0 Flow Diagram

Office 365 2FA Flow Diagram
Fig 10: Office 365 2FA Flow Diagram
  1. End-user logs in to the Office 365 service.
  2. Primary authentication initiated to SAML service.
  3. An authentication request triggered to the SAML2.0 connector.
  4. Primary authentication using directory connector integrating with the organization’s directory service.
  5. Secondary authentication is triggered by V-OS Cloud’s PKI Suite.
  6. The end-user uses the V-Key app to approve the login request.
  7. V-OS Cloud IDM receives authentication respond.
  8. V-OS Cloud IDM replies to the SAML Service Provider (Office 365 server).
  9. Application or service access is granted.
Table of contents