An Azure Service Principal iClient stores your Microsoft Entra ID (Azure AD) app registration credentials so you can authenticate Azure connections — including Azure Data Lake Storage Gen2, Azure Blob Storage, Azure DevOps, Microsoft Dynamics 365, and Microsoft SQL — without re-entering credentials for each connection. Use this article if you're setting up an Azure connection or a Microsoft SQL service principal.
You can create an iClient at Resources → iClients, or directly during setup of any Azure connection that uses this iClient type.
Tip
Open the Microsoft Entra admin center in a separate window so you can locate and copy your Tenant ID, Client ID, and Client secret or certificate without switching contexts.
You need an app registration (service principal) already created in Microsoft Entra ID, with a client secret or certificate generated, or permissions to create one. If you don't have an app registration, register one in the Microsoft Entra admin center before continuing.
- Name * — Enter a clear and distinguishable name.
- Type * (read-only) — Set to Azure service principal.
Note
The Auth method field, and certificate-based authentication, are available only when you create or edit this iClient from a Microsoft SQL Cloud connection. For all other connections that use this iClient type — including Azure Data Lake Storage Gen2, Azure Blob Storage, Azure DevOps, and Microsoft Dynamics 365 — this section shows only Tenant ID, Client ID, and Client secret.
- Auth method * (MS SQL only) — Select an authentication method for Microsoft Entra ID. Use Client secret for an application secret, or Certificate for one registered on your Entra ID application. Defaults to Client secret.
- Client ID * (Client secret and Certificate) — The application (client) ID of your app registration.
- Tenant ID * (Client secret and Certificate) — The directory (tenant) ID of your Microsoft Entra ID instance. Identifies which Entra ID directory your app registration belongs to.
- Client secret * (Client secret only) — The client secret value generated for your app registration. integrator.io stores the credential encrypted. This field is never displayed again after you save — to update the credential, generate a new secret in Entra ID and re-enter the full value.
-
Client certificate * (Certificate only) — Paste the PEM-encoded certificate registered on your Entra ID application. Include the private key in the same file. If the key is encrypted, enter its password in the Client certificate password box. For security, this value isn't shown again — re-enter it whenever you update the certificate.
Note: for security reasons this field must always be re-entered. -
Client certificate password (Certificate only, optional) — If your client certificate's private key is encrypted, enter the password that protects it. Leave blank if your private key isn't encrypted. For security, this value isn't shown again — re-enter it whenever you update the certificate.
Note: for security reasons this field must always be re-entered.
Note
Client secrets and certificates are encrypted at rest, never returned in API responses, and never logged. Existing service principal iClients that don't yet have an Auth method value default to Client secret and continue to authenticate with no action required.
Note
The following steps reflect the Microsoft Entra admin center UI at time of writing. Microsoft periodically updates this UI — see Register an application, How to find your tenant ID, and Add and manage app credentials for the current version if these steps don't match what you see.
- Sign in to the Microsoft Entra admin center as at least an Application Developer.
- To find your Tenant ID: go to Entra ID → Overview → Properties, and copy the Tenant ID shown there.
- To find your Client ID: go to Entra ID → App registrations, select the app registration you want to use (or select New registration to create one), and on the Overview page copy the Application (client) ID.
- To create a Client secret: on the same App registration, go to Certificates & secrets → Client secrets → New client secret. Enter a description and expiration, then select Add. Copy the Value immediately — Entra ID only displays it once.
- To upload a Client certificate: on the same App registration, go to Certificates & secrets → Certificates → Upload certificate, and select your certificate file. See Add and manage app credentials for the current steps.
- Paste the Tenant ID, Client ID, and Client secret or Client certificate into the corresponding fields in integrator.io.
Note
The Client certificate value must be PEM-encoded and include both the certificate and the private key in the same file. PFX/PKCS#12 bundles aren't supported — see Convert PFX certificates to PEM format to convert one first. The value can't exceed 20 KB. The private key can be encrypted or unencrypted; if it's encrypted, enter its password in Client certificate password.
Troubleshooting certificate authentication
| Error | What it means | What to do |
|---|---|---|
| "This certificate's private key is encrypted. Enter the client certificate password." | The private key needs a password you haven't supplied. | Enter the password in Client certificate password. |
| "The client certificate password is incorrect. Enter the password used when the private key was encrypted." | The password doesn't match the one used to encrypt the key. | Re-enter the password used when the private key was encrypted. |
| "This certificate's private key is not encrypted. Clear the client certificate password." | A password was entered, but the private key doesn't need one. | Clear the Client certificate password field. |
- Set up an Azure Data Lake Storage Gen2 connection
- Set up a connection to Azure Blob Storage
- Set up a connection to Microsoft Azure DevOps
- Set up a connection to Microsoft Dynamics 365
- Set up a connection to Microsoft SQL
- Convert PFX certificates to PEM format
- Microsoft Entra ID app registration documentation