Prerequisites

Before starting, gather the following from your Venio environment:

-- Run on the VenioPCD database
SELECT [Key], [Value] FROM tbl_pj_ControlSetting
WHERE [Key] IN ('WEB_BASE_URL', 'VOD_API_URL')

You will need:

• WEB_BASE_URL — your Venio web application URL 
          (e.g., https://your-venio-host/VenioWeb)
• VOD_API_URL — your Venio OnDemand API URL
          (e.g., https://your-venio-host/VenioOnDemandAPI/vod/services)
• VenioSetup.ini location

  Common actual paths include:

  • C:\inetpub\wwwroot\VenioOnDemandAPI\VenioSetup.ini
  • C:\inetpub\wwwroot\VenioWebAPI\VenioSetup.ini

  Always verify the actual path. Creating the ini section in the wrong directory causes a NullReferenceException in OKTAMetaParser.GetMetaElements() with no descriptive error in the UI — only "Object reference not set to an instance of an object" in tbl_ex_exceptionloginfo.

• You will also need:
  • An RSA key pair for SAML token encryption
  • Global Administrator access to Azure portal

 Enterprise Application Registration

1. Register a New Enterprise Application

• Sign in to the Azure portal at https://portal.azure.com.
• In the left-hand menu, select Microsoft Entra ID (Azure Active Directory).

• Under Manage, click Enterprise applications.

• Click + New application.

• Choose Create your own application.

• Enter a descriptive Name (e.g., Venio Enterprise SSO App).
• Select the option Integrate any other application you don't find in the gallery (Non-gallery).

• Click Create.
• On the Application overview page, note the Object ID for future reference. This value will be used as Application ObjectId in VOD interface SAML IDP Server Setting later while configuring SAML setting in Venio.

 2. Configure SAML Single Sign-On

2.1. Enable SSO via SAML

1. In your new enterprise application, select Single sign-on from the left menu.
2. Choose SAML as the SSO method.

2.2. Basic SAML Configuration

1. Under Basic SAML Configuration, click Edit.

2. Set:

• Identifier (Entity ID): The value of your WEB_BASE_URL from tbl_pj_controlsettings

You can find the value of WEB_BASE_URL in the tbl_pj_controlsettings table within the VenioPCD database.
To retrieve it, run the following SQL query:

This will return the current value of the WEB_BASE_URL configuration used by the application.

• Reply URL (ACS): The value of your VOD_API_URL/idp-settings/handle-saml-response from tbl_pj_controlsettings

You can find the value of VOD_API_URL in the tbl_pj_controlsettings table within the VenioPCD database.
To retrieve it, run the following SQL query:

3. Click Save.

2.3. User and Group Claims

Add Individual Claims

1. Under Attributes & Claims, click Edit.
2. Click Add new claim.

3. 

   • Name: UserSID
   • Source attribute: user.objectid
   • Click Save.
4. Click Add new claim again.
   • Name: UserPrincipalName
   • Source attribute: user.userprincipalname 
     
   • Click Save.

Add Group Claim

1. Click Add a group claim.
2. On the panel, configure:
   • Group claim type: Groups assigned to the application
   • Source attribute: Cloud-only group display name
   • Name (Advanced Options): ADGroup
3. Click Save.

Note:

When configuring group claims in Azure AD, you have the option to choose which attribute to use as the source for group claims.

If your organization uses on-premises groups with a source type of Windows Server AD,

select  sAMAccountName as the group claim source

2.4. SAML Certificates & Encryption

Signing Certificate

1. Expand SAML Certificates.
2. Click Edit on the Signing section.
   • Signing option: Sign SAML response and assertion
   • Signing algorithm: SHA-1

3. Click Save.

4. Download the Federation Metadata xml. You will later need this xml in the Venio application.

2.5 Token Encryption Certificate

1. Scroll to Security > Token encryption.
2. Click Import to upload your public certificate (.cer)
3. Click Activate to enable encryption.

3. Assign Users and Groups

1. Navigate back to the Enterprise application overview.
2. Click Users and groups > Add user/group.
3. In the Add Assignment pane:
   1. Click Users and groups.
   2. Search for and select desired users or groups.
   3. Click Select, then Assign.

B. Application Registration

When you create an Enterprise application, it automatically creates the associated application registration. Therefore, if the application already exists, you can skip ahead to Step 4.

Steps to Register an Application

1. Sign in to the Azure Portal

1. Go to https://portal.azure.com
2. Sign in using a Global Administrator account.

2. Navigate to App Registrations

1. In the left menu, click Microsoft Entra ID (Azure Active Directory).

2. Under Manage, click App registrations.

3. Create a New App Registration

1. Click the + New registration button.

2. Enter a Name for the application.

3. Choose the appropriate Account types based on your use case.

4. Click Register.

💡 After registering, you’ll be redirected to the application’s Overview page. 

4. Copy and save the following:

• Application (client) ID
• Directory (tenant) ID

5. Create a Client Secret

1. In the left menu, click Certificates & secrets.
2. Under Client secrets, click + New client secret.
3. Add a Description and select an Expiration time.
4. Click Add.
5. Copy the Value immediately. It won’t be visible again.

⚠️ Be sure to store the client secret securely. The full value won't be retrievable later.

6. Set API Permissions

1. Click API permissions in the left menu.
2. Click + Add a permission > Microsoft Graph > Application permissions.
3. Select the following permissions:
   • Application.Read.All
   • Group.Read.All
   • User.Read.All
4. Click Add permissions.

7. Grant Admin Consent

1. In the API permissions section, click Grant admin consent for default directory.
2. Confirm the action when prompted.

C.  Configure Venio Web API for SAML

1. Locate the Configuration File

• Open the VenioSetup.ini file on the IIS-hosted machine.
• Default path: C:\inetpub\wwwroot\VenioWebAPI\VenioSetup.ini

2 Add IdP Settings

• Open VenioSetup.ini in a text editor.
• Add a new section:

[IDP SETTINGS]

Add or update the following keys:

• SP_Issuer: This should be your base VOD URL. It will be same as value of WEB_BASE_URL from tbl_pj_controlsetting table. For example:

SP_Issuer=https://aic.veniosystems.com/venioweb

• IdP_PrivateKey: Paste your private RSA key in PEM format.

IdP_PrivateKey=<Your RSA Private Key Content>

🔐 Ensure the private key is RSA-converted. See this KB article on Generating Keys if applicable.

3. Enable IdP in Venio UI

 You have:

• Client ID
• Tenant ID
• Client Secret

Use these values to authenticate and query users and groups from Azure AD using Microsoft Graph in VOD. Navigate to Admin Settings > System Admin > Login Management > SAML IdP Server Settings and set the values as shown in the screenshot below:

4. Import Users

In Admin Settings, navigate to Users > Create.
You will see the Import Users from IDP link — click on it.
If everything from the previous setup has been configured correctly, clicking the magnifying glass icon will display all your users from Azure. Select the user and hit import.

Once you hit import, assign appropriate User Role, Cases and click 'Create'.

If you prefer not to import users individually, you can use group mapping. Group mapping links Azure AD groups to Venio roles, allowing you to manage access through Azure rather than configuring each user separately. However, in Azure Active Directory, you must first create groups that match Venio roles and application permissions.

Steps to Map Groups

1. Navigate to Admin Settings > System Admin > Login Management > SAML IdP Server Settings and click Load Groups.(Assuming all SAML IdP settings have already been configured from a previous setup).
2. Check all the 4 access level check boxes.
3. Map all the Venio Admins Levels, Venio Applications, Venio User Groups, Venio Users groups with Idp Group and click 'Apply'. 

More details on user mapping on the following KB article. 

Common Errors and Solutions

Error: "Object reference not set to an instance of an object" (in OKTAMetaParser.GetMetaElements)

Cause: The [IDP SETTINGS] section is missing from VenioSetup.ini, or VenioSetup.ini is in the wrong directory.

Fix:

1. Find the correct ini path: Get-ChildItem -Path C:\ -Recurse -Filter "VenioSetup.ini"
2. Verify it contains the [IDP SETTINGS] section with SP_Issuer and IdP_PrivateKey
3. Run iisreset after editing

Error: "The input is not a valid Base-64 string" (in DecryptResponse.CreateRsa)

Cause: The IdP_PrivateKey value in VenioSetup.ini contains PEM headers (-----BEGIN...-----) or newlines.

Fix: Remove all PEM headers/footers and ensure the key is on a single line with no whitespace.

Error: "Bad Length" (in RSACryptoServiceProvider.ImportParameters)

Cause: The private key is in PKCS#8 format instead of PKCS#1.

Fix: Convert with OpenSSL: openssl rsa -in key.pem -out key-pkcs1.pem -traditional, then extract the single-line Base64.

How to tell: PKCS#8 keys start with MIIEvg; PKCS#1 keys start with MIIEpA (for 2048-bit RSA).

Error: "The SAML response does not have UserID assigned"

Cause: One of:

1. The UserSID and/or UserPrincipalName custom claims are not configured in Azure, OR
2. The claims have a namespace prefix that Venio doesn't expect (see Part A, Step 2.3 — the Namespace field must be blank), OR
3. The user doesn't exist in tbl_pj_UserInfo with IsIdPUser = 1 and a matching email/IdPUserSID

Fix:

1. In Azure → Enterprise App → Single sign-on → Attributes & Claims, verify UserSID and UserPrincipalName exist with blank namespace
2. Verify the user exists in Venio: SELECT UserID, Email, IsIdPUser, IdPUserSID FROM tbl_pj_UserInfo WHERE Email LIKE '%user%'
3. If the user doesn't exist, create them manually (see Air-Gapped Environments section)

Error: AADSTS50105 — "Your administrator has configured the application to block users"

Cause: The Azure Enterprise Application requires user/group assignment, and the user hasn't been assigned.

Fix: In Azure → Enterprise App → Users and groups → Add the user. Or set Properties → Assignment required → No (for testing only).

Error: Azure redirects succeed but Venio shows XML error page

Cause: The SAML assertion POST reached the ACS URL but the Venio API threw a 500 error.

Fix: Check tbl_ex_exceptionloginfo for the specific error. The most common causes are private key format issues (see above) or a mismatch between the Reply URL in Azure and the actual Venio API endpoint.

Quick Reference: All Values You Need