Vault Service (on-prem)
Omada Identity Vault Service helps companies that use Omada Identity comply with zero trust policies and address the security challenges of dynamic, cloud-based infrastructures.
A vault is a central, secure place that stores and manages the secrets (for example, API keys, passwords, and certificates) that an application needs to work with other applications and services. A vault gives access to these secrets only to authorized resources.
Instead of Omada Identity storing sensitive information locally, the Vault Service fetches secrets from vaults when:
- Onboarding a system and editing the connection details
- Pushing the connection details to Omada Provisioning Service (OPS)
- Omada Data Warehouse (ODW) pulls the data connection details
- Setting up the sending of mails
- Setting up log configuration
For the onboarding system functionality, the Vault Service supports only HashiCorp Vault and Azure Key Vault. Vaults from other vendors, for example, CyberArk, are not supported.
Configuration on-prem
Installation steps
To install the Omada Identity Vault Service:
-
Run Omada.Identity.Vault.Service.Installer.msi. When the Setup Wizard opens, click Next.
-
Choose the installation folder or keep the default one,
C:\Program Files\Omada Identity Suite\Vault Service\. Then, click Next.
-
Choose the credentials that the Omada Identity Vault Service uses: Local System Account or Service Account. If you select Service Account, enter the User Name and Password. Then, click Next.
-
Click Install to start the installation.
-
When the installation is complete, click Finish.
The Omada Identity Vault Service is now installed.
Connection
To create a connection to the Vault Service:
-
Go to Setup > Administration > System settings > Installed packages and install the Vault integration package.
-
Set the
VaultServiceUrlcustomer setting tohttp://localhost:5009.
on-prem Omada Identity Vault Service for an on-premises connection requires the newest versions of the following:
- ASP.NET Core Runtime 10.0.x
- .NET Runtime 10.0.x
Authentication with Omada Identity
To authenticate with Omada Identity, you can choose between Basic authentication and NTLM authentication. If you use a service account (not the local system account), NTLM (Windows) authentication is recommended.
The authentication parameter must be base64 encoded.
You can encrypt the basic authentication header to prevent unintended users from reading the appsettings.json file and getting the password of the service user account.
To set up basic authentication:
-
Open a command prompt and go to the following folder:
C:\Program Files\Omada Identity Suite\Enterprise Server\website\bin. -
From the
\binfolder, run the following command:StringEncrypter.exe -e <PswEncryptionKey> <StringToBeEncrypted>PswEncryptionKey- the encryption key for the environment, configured during installation and stored in the registry.StringToBeEncrypted- the service account name with domain and the password, separated by a colon andbase64encoded. For example:
Credentials = Domain\User:Password123Base64 encoded = RG9tYWluXFVzZXI6UGFzc3dvcmQxMjM=Command = StringEncrypter.exe -e DefaultEncryptionKey 'RG9tYWluXFVzZXI6UGFzc3dvcmQxMjM='Result = AES256:LAI4b+nRTFWqpU1iEpTYi0ggFlQYOFxlwE1U4hP/wY4juoiFt/7R6leqWY9Vztdt=AES256 -
The command returns the encrypted credentials, as shown in the
Resultline of the example. Copy the encrypted credentials, because you need them in the next step. -
Open the
appsettings.jsonfile in a text editor, and paste the encrypted credentials as follows:Basic authentication example
"AuthenticationHeader": {"Scheme": "Basic","Parameter": "the encrypted credentials go here!"}
To authenticate with NTLM, paste the following into the appsettings.json file:
NTLM example
"AuthenticationHeader": {
"Scheme": "NTLM"
}
Omada Identity logging
Omada Vault Service uses the Log configuration object to make sure that logs are written to the correct logging target.
To avoid overwriting your Log configuration XML, the Vault Service installation does not create a log target for the Vault Service. You must add the log target manually:
-
Go to Setup > Administration > More > Configuration objects.
-
Select the Log configuration object.
-
Add the following target and filter to the configuration data XML:
New target example
<target logTargetType="windowsEventLog" name="VaultEventLog"><targetParameters><targetParameter name="source" value="Omada Vault Service"/><targetParameter name="log" value="Application"/></targetParameters></target>New filter example
<filters><filter targets="VaultEventLog" component="Vault" logLevel="information"/></filters> -
Save your changes and restart the Vault Service.
The log entries from the Vault Service now appear in the log target.
Default logging
The following are the standard ASP.NET Core logging settings, as described in the Microsoft documentation:
"Logging": {
"LogLevel": {
"Default": "Information",
"Microsoft.AspNetCore": "Information"
},
"EventLog": {
"SourceName": "Omada Vault Service",
"LogLevel": {
"Default": "Information"
}
}
},
These settings are not related to the Log configuration object. They control how the Vault Service logs by default, which is useful for debugging.
When the Vault Service works as expected, consider changing the LogLevel to Warning so that verbose log information doesn't flood the event logs.
The SourceName must match the event log source created by the installer.
Example of the azureLogAnalytics configuration when using vault secrets on-prem
<target logTargetType="azureLogAnalytics" name="azureLog" disabled="false">
<targetParameters>
<targetParameter name="workspaceid" value="{workspace ID}"/>
<targetParameter name="logname" value="OIS"/>
<targetParameter name="applicationid" value="{application ID}"/>
<targetParameter name="sharedkey" value="VAULT:LOGANALYTICSSHAREDKEY=VAULT"/>
<targetParameter name="clientsecret" value="VAULT:APPLICATIONSECRET=VAULT"/>
<targetParameter name="azuretenantid" value="{tenant ID}"/>
</targetParameters>
</target>
Authorize communication using API Key
Omada Identity must be authorized against the Vault Service.
By default, all keys in the configuration file are empty.
The Vault Service must be authenticated so it can read the log configuration from Omada Identity. To authorize communication using the application programming interface (API) key:
-
Open the Vault Service's
appsettings.jsonconfiguration file. -
In the
Loggingsection:- Set the
LogLevel. UseDebugduring development andInformationduring operations.
- Set the
-
In the
ConfigurationServicesection:-
In
BaseAddress, enter the base URL of the Omada Identity environment. -
Keep the default path in
ConfigurationDataPath.
-
-
In the
AuthenticationHeadersection:-
Enter the
Scheme. -
Enter the
Parameterthat you obtained in Authentication with Omada Identity.
-
-
In the
ApiKeyAuthenticationsection:-
In
ApiSharedSecret, enter the shared secret for the Omada environment. It is the same as for other services, such as Role and Policy Engine (RoPE). -
In
PswEncryptionKey, enter the encryption key for the environment, configured during installation and stored in the registry.
-
The following is an example of the appsettings.json configuration file:
Example
{
"Kestrel": {
"EndpointDefaults": {
"Protocols": "Https"
},
"EndPoints": {
"Http": {
"Url": "http://localhost:5009"
}
}
},
"Logging": {
"LogLevel": {
"Default": "Debug",
"Microsoft.AspNetCore": "Debug"
},
"EventLog": {
"SourceName": "Omada Vault Service",
"LogLevel": {
"Default": "Debug"
}
}
},
"AllowedHosts": "*",
"ConfigurationService": {
"BaseAddress": "[base address of your Omada environment, for example, 'http://enterpriseserver/']",
"ConfigurationDataPath": "WebService/UIWebService.asmx/GetConfigurationData",
"AuthenticationHeader": {
"Scheme": "Basic",
"Parameter": "[encrypted string]"
}
},
"ApiKeyAuthentication": {
"ApiSharedSecret": "[shared secret for the Omada environment]",
"PswEncryptionKey": "[encryption key for the Omada environment]"
}
}
Create a connection to a vault
To create a connection to a vault:
-
Go to Administration > System settings > Vault connections.
-
Click New.
-
Name your vault connection object.
-
In the Onboarding values field, enter the XML that describes the connection to your vault provider. The parameters and examples for each supported vault are described below.
Encrypt secrets before savingSecret values in the vault connection XML, such as ClientSecret and X-Vault-Token, must be encrypted before you save the vault connection. Do not enter them in plain text.
To encrypt a value, use the StringEncrypter tool with the
PswEncryptionKeyof your environment:StringEncrypter.exe -e <PswEncryptionKey> <SecretValue>Then, paste the encrypted string returned by the tool, including the
AES256:and=AES256tags, into the<value>element of the corresponding parameter.-
HashiCorp Vault
-
Parameters
- Name - the supported secrets engine: HashiCorpKV2.
- AuthMethod - VaultToken, AzureAD, or AzureMI.
- Do not use token authentication in a production environment. For proper security, use AzureAD or AzureMI authentication.
- X-Vault-Token - the token used for VaultToken authentication. Enter the encrypted value.
- ClientId - the application (client) ID of the Microsoft Entra ID service principal. It acts like the service principal's username.
- TenantId - the ID of the Microsoft Entra ID tenant used to authenticate requests to the vault.
- ClientSecret - the client secret of the service principal. It acts like the service principal's password. Enter the encrypted value.
- Scope - the OAuth 2.0 scope.
- Role - the role created in HashiCorp Vault.
- Uri - the URI of the HashiCorp Vault service.
- Path - the path where the secrets engine is enabled. For more information, refer to the HashiCorp documentation.
Example with VaultToken authentication
<?xml version="1.0" encoding="utf-8"?><ConfigurationParameters xmlns="http://schemas.omada.net/ois/2016/SystemConfigurationValuesML"><configurationParameter Name="Name"><values><value>HashiCorpKV2</value></values></configurationParameter><configurationParameter Name="AuthMethod"><values><value>VaultToken</value></values></configurationParameter><configurationParameter Name="X-Vault-Token"><values><value>[encrypted vault token]</value></values></configurationParameter><configurationParameter Name="Uri"><values><value>[base address of the vault service you are connecting to]</value></values></configurationParameter><configurationParameter Name="Path"><values><value>[path to secrets engine]</value></values></configurationParameter></ConfigurationParameters>Example with AzureAD authentication
<?xml version="1.0" encoding="utf-8"?><ConfigurationParameters xmlns="http://schemas.omada.net/ois/2016/SystemConfigurationValuesML"><configurationParameter Name="Name"><values><value>HashiCorpKV2</value></values></configurationParameter><configurationParameter Name="AuthMethod"><values><value>AzureAD</value></values></configurationParameter><configurationParameter Name="ClientId"><values><value>!Client ID goes here!</value></values></configurationParameter><configurationParameter Name="TenantId"><values><value>!Tenant ID goes here!</value></values></configurationParameter><configurationParameter Name="ClientSecret"><values><value>!Encrypted client secret goes here!</value></values></configurationParameter><configurationParameter Name="Scope"><values><value>!Application scope goes here!</value></values></configurationParameter><configurationParameter Name="Role"><values><value>dev-role</value></values></configurationParameter><configurationParameter Name="Uri"><values><value>https://{vault-name}</value></values></configurationParameter><configurationParameter Name="path"><values><value>secret</value></values></configurationParameter></ConfigurationParameters>Example with AzureMI authentication
<?xml version="1.0" encoding="utf-8"?><ConfigurationParameters xmlns="http://schemas.omada.net/ois/2016/SystemConfigurationValuesML"><configurationParameter Name="Name"><values><value>HashiCorpKV2</value></values></configurationParameter><configurationParameter Name="AuthMethod"><values><value>AzureMI</value></values></configurationParameter><configurationParameter Name="Role"><values><value>dev-role</value></values></configurationParameter><configurationParameter Name="Scope"><values><value>{application scope}</value></values></configurationParameter><configurationParameter Name="Uri"><values><value>https://{vault-name}</value></values></configurationParameter><configurationParameter Name="path"><values><value>secret</value></values></configurationParameter></ConfigurationParameters> -
Resources
The vault connection for HashiCorp Vault must contain the properties described in the Azure auth login request. For more information, refer to the HashiCorp documentation:
-
-
Azure Key Vault
-
Parameters
The number of parameters in the XML depends on the authentication method you choose:
Parameter Microsoft Entra ID Azure MI Name AzureKeyVault AzureKeyVault AuthMethod AzureAD - Microsoft Entra ID access tokens obtained using OAuth 2.0.
When you use Azure Key Vault with Microsoft Entra ID authentication, make sure that the application's service principal has the Key Vault Reader and Key Vault Secrets User role assignments on the Azure Key Vault resource.
For more information, refer to the Azure documentation.AzureMI - Azure managed identities. ClientId The application (client) ID of the Microsoft Entra ID service principal. It acts like the service principal's username. Optional. TenantId The ID of the Microsoft Entra ID tenant used to authenticate requests to the key vault. Not applicable. ClientSecret The client secret of the service principal. It acts like the service principal's password. Enter the encrypted value. Not applicable. Scope https://management.azure.com/Not applicable. Uri The URI of the key vault: https://{vault-name}.vault.azure.netThe URI of the key vault: https://{vault-name}.vault.azure.netXML schema with Microsoft Entra ID authentication
<?xml version="1.0" encoding="utf-8"?><ConfigurationParameters xmlns="http://schemas.omada.net/ois/2016/SystemConfigurationValuesML"><configurationParameter Name="Name"><values><value>AzureKeyVault</value></values></configurationParameter><configurationParameter Name="AuthMethod"><values><value>AzureAD</value></values></configurationParameter><configurationParameter Name="ClientId"><values><value>!ClientID value goes here!</value></values></configurationParameter><configurationParameter Name="TenantId"><values><value>!TenantID value goes here!</value></values></configurationParameter><configurationParameter Name="ClientSecret"><values><value>!Encrypted ClientSecret value goes here!</value></values></configurationParameter><configurationParameter Name="Scope"><values><value>!Scope goes here!</value></values></configurationParameter><configurationParameter Name="Uri"><values><value>https://{vault-name}.vault.azure.net/</value></values></configurationParameter></ConfigurationParameters>XML schema with Azure MI authentication
<?xml version="1.0" encoding="utf-8"?><ConfigurationParameters xmlns="http://schemas.omada.net/ois/2016/SystemConfigurationValuesML"><configurationParameter Name="Name"><values><value>AzureKeyVault</value></values></configurationParameter><configurationParameter Name="AuthMethod"><values><value>AzureMI</value></values></configurationParameter><configurationParameter Name="ClientId"><values><value>!ClientID value goes here - optional!</value></values></configurationParameter><configurationParameter Name="Uri"><values><value>https://{vault-name}.vault.azure.net/</value></values></configurationParameter></ConfigurationParameters>For more information, refer to the Azure Key Vault documentation.
-
-
-
Click Save.
-
Click Test connection to verify the vault connection.
When a system administrator creates or modifies a vault connection, Omada Identity tests the connection through a call to the Omada Vault Service API to make sure that the service can connect and authenticate.
Create a vault secret
To create a vault secret:
-
Go to Administration > System settings > Vault secrets.
-
In the Name field, enter a name for the vault secret.
-
In the Vault connection field, select the vault connection you created in Vault connections.
-
Enter the Path to the secret in the vault.
-
Optional: If the secret is part of a JSON object or a dictionary object, enter the Key of the secret.
-
Select Test connection to validate the vault connection, path, and key.
-
Click OK.
Onboard a system with a vault secret
To onboard a system with a vault secret:
-
Go to Setup > Master Data > Systems.
-
Select the relevant registered system.
-
In the System definition section, click Connection details.
-
In the dialog, click the Vault configuration icon next to the Password field.
-
In the Password dialog, in the Vault field, select the vault secret object.
-
Select Test connection to validate the vault, path, and key.
-
Click OK.
-
In the parent dialog, the Password field now displays the Vault, Path, and Key values.
-
On the subsequent server-side call, Omada Identity retrieves the secret from the vault, encodes it, and stores it in the vault connection object of the system.
If the vault secret changes in the external vault, you must commit the Omada Provisioning Service (OPS) settings afterwards.