|
| 1 | +--- |
| 2 | +title: Authenticate with Microsoft Entra ID in bcp |
| 3 | +description: Use Microsoft Entra ID to authenticate the bulk copy program (bcp) utility against Azure SQL, Microsoft Fabric SQL database, or SQL Server 2022 and later versions. |
| 4 | +author: rwestMSFT |
| 5 | +ms.author: randolphwest |
| 6 | +ms.reviewer: davidengel |
| 7 | +ms.date: 04/19/2026 |
| 8 | +ms.service: sql |
| 9 | +ms.subservice: tools-other |
| 10 | +ms.topic: how-to |
| 11 | +ms.collection: |
| 12 | + - data-tools |
| 13 | +ms.custom: |
| 14 | + - linux-related-content |
| 15 | + - peer-review-program |
| 16 | +helpviewer_keywords: |
| 17 | + - "bcp utility [SQL Server], authentication" |
| 18 | + - "bcp utility [SQL Server], Microsoft Entra ID" |
| 19 | + - "Microsoft Entra ID, bcp" |
| 20 | + - "managed identity, bcp" |
| 21 | +monikerRange: ">=azuresqldb-current || =azure-sqldw-latest || >=sql-server-2016 || >=sql-server-linux-2017 || =fabric-sqldb" |
| 22 | +--- |
| 23 | +# Authenticate with Microsoft Entra ID in bcp |
| 24 | + |
| 25 | +[!INCLUDE [SQL Server Azure SQL Database Synapse Analytics FabricSQLDB](../../includes/applies-to-version/sql-asdb-asdbmi-asa-fabricsqldb.md)] |
| 26 | + |
| 27 | +The [bulk copy program utility (bcp)](bcp-utility.md) supports several Microsoft Entra ID authentication models when you connect to Azure SQL Database, Azure SQL Managed Instance, [!INCLUDE [fabric-sqldb](../../includes/fabric-sqldb.md)], Azure Synapse Analytics, or [!INCLUDE [sssql22-md](../../includes/sssql22-md.md)] and later versions. |
| 28 | + |
| 29 | +To check whether your installed **bcp** supports Microsoft Entra authentication, run `bcp --help` and verify that `-G` appears in the list of available arguments. |
| 30 | + |
| 31 | +## Platform restrictions |
| 32 | + |
| 33 | +Not all authentication modes are available on every platform: |
| 34 | + |
| 35 | +- Microsoft Entra interactive authentication is supported on Windows only. |
| 36 | + |
| 37 | +- Microsoft Entra integrated authentication on Linux and macOS requires [Microsoft ODBC Driver 18 for SQL Server](../../connect/odbc/download-odbc-driver-for-sql-server.md) (driver 17.6.1 or later if you can't move to driver 18) and a [properly configured Kerberos environment](../../connect/odbc/linux-mac/using-integrated-authentication.md#configure-kerberos). |
| 38 | + |
| 39 | +- Authentication with an access token file (`-P <token_file>`) is supported on Linux and macOS only. |
| 40 | + |
| 41 | +## Microsoft Entra username and password |
| 42 | + |
| 43 | +Provide `-G` together with `-U` (username) and `-P` (password). |
| 44 | + |
| 45 | +The following example exports table `bcptest` from database `testdb` on `contoso.database.windows.net` to file `c:\last\data1.dat`. Replace `<password>` with a valid password. |
| 46 | + |
| 47 | +```console |
| 48 | +bcp bcptest out "c:\last\data1.dat" -c -S contoso.database.windows.net -d testdb -G -U alice@contoso.onmicrosoft.com -P <password> |
| 49 | +``` |
| 50 | + |
| 51 | +The following example imports the same data: |
| 52 | + |
| 53 | +```console |
| 54 | +bcp bcptest in "c:\last\data1.dat" -c -S contoso.database.windows.net -d testdb -G -U alice@contoso.onmicrosoft.com -P <password> |
| 55 | +``` |
| 56 | + |
| 57 | +## Microsoft Entra integrated |
| 58 | + |
| 59 | +Provide `-G` without `-U` or `-P`. The current Windows account (or Kerberos identity on Linux/macOS) must be federated with Microsoft Entra ID. In the following examples, replace `<server>` with your server name. |
| 60 | + |
| 61 | +Export: |
| 62 | + |
| 63 | +```console |
| 64 | +bcp bcptest out "c:\last\data2.dat" -S <server>.database.windows.net -d testdb -G -c |
| 65 | +``` |
| 66 | + |
| 67 | +Import: |
| 68 | + |
| 69 | +```console |
| 70 | +bcp bcptest in "c:\last\data2.dat" -S <server>.database.windows.net -d testdb -G -c |
| 71 | +``` |
| 72 | + |
| 73 | +## Microsoft Entra Managed Service Identity |
| 74 | + |
| 75 | +Authenticate as either a system-assigned or user-assigned managed identity through a configured DSN. The same approach works for both `bcp in` and `bcp out`. |
| 76 | + |
| 77 | +> [!IMPORTANT] |
| 78 | +> **bcp** is tightly coupled to its driver. The major version of **bcp** must match the major version of the driver the DSN is created with. To determine your **bcp** version, run `bcp -v`. |
| 79 | +
|
| 80 | +### [Windows](#tab/windows) |
| 81 | + |
| 82 | +Configure a DSN through the **ODBC Data Source Administrator**: |
| 83 | + |
| 84 | +1. Press the Windows key on your keyboard. |
| 85 | +1. Type `ODBC` and select the appropriate version of the **ODBC Data Source Administrator**. |
| 86 | +1. Select either the **User DSN** or **System DSN** tab. |
| 87 | +1. Select **Add** and follow the prompts. |
| 88 | +1. When asked for an authentication type, select **Azure Managed Service Identity authentication**. |
| 89 | +1. For a User Assigned Managed Identity, paste the `Object (principal) ID` of the identity into the **Login ID** box on the authentication tab. |
| 90 | +1. Continue following the prompts to finish configuring the DSN. |
| 91 | + |
| 92 | +For a full walkthrough including screenshots, see [Creating and editing DSNs in the UI](../../connect/odbc/using-azure-active-directory.md#creating-and-editing-dsns-in-the-ui). |
| 93 | + |
| 94 | +Use the `-D` flag to indicate that the value passed to `-S` is a DSN. The `-D` and `-S` switches can appear in any order on the command line. |
| 95 | + |
| 96 | +```console |
| 97 | +bcp bcptest out "c:\last\data1.dat" -c -D -S myDSN -d testdb |
| 98 | +``` |
| 99 | + |
| 100 | +### [Linux and macOS](#tab/linux) |
| 101 | + |
| 102 | +Edit the user `.odbc.ini` file (typically at `~/.odbc.ini`). Run `odbcinst -j` to confirm the DSN file location. |
| 103 | + |
| 104 | +```bash |
| 105 | +vi /home/<user>/.odbc.ini |
| 106 | +``` |
| 107 | + |
| 108 | +Add an entry like the following. Omit the `LastUser` line for a system-assigned managed identity. Replace `<server>` and `<object_id_of_user_assigned_managed_identity>` with values for your environment. |
| 109 | + |
| 110 | +```ini |
| 111 | +[myDSN] |
| 112 | +Driver = ODBC Driver 18 for SQL Server |
| 113 | +Server = <server>.database.windows.net |
| 114 | +Database = testdb |
| 115 | +Encrypt = yes |
| 116 | +LastUser = <object_id_of_user_assigned_managed_identity> |
| 117 | +Authentication = ActiveDirectoryMSI |
| 118 | +``` |
| 119 | + |
| 120 | +Use the `-D` flag to indicate that the value passed to `-S` is a DSN. The `-D` and `-S` switches can appear in any order on the command line. |
| 121 | + |
| 122 | +```bash |
| 123 | +bcp bcptest out data1.dat -c -D -S myDSN -d testdb |
| 124 | +``` |
| 125 | + |
| 126 | +--- |
| 127 | + |
| 128 | +## Microsoft Entra ID access token |
| 129 | + |
| 130 | +**Applies to**: Linux and macOS only. Windows isn't supported. |
| 131 | + |
| 132 | +**bcp** 17.8 and later versions on Linux and macOS can authenticate with an access token. The following examples use the [Azure CLI](/cli/azure/install-azure-cli-linux) to retrieve the token and write it to a secure temporary file. |
| 133 | + |
| 134 | +> [!IMPORTANT] |
| 135 | +> The token file must be UTF-16LE without a BOM. Restrict file permissions and delete the file when it's no longer needed, as shown in the following examples. |
| 136 | +
|
| 137 | +### System-assigned managed identity |
| 138 | + |
| 139 | +Replace `<server>` with your server name. |
| 140 | + |
| 141 | +1. Sign in with your managed identity: |
| 142 | + |
| 143 | + ```bash |
| 144 | + az login --identity |
| 145 | + ``` |
| 146 | + |
| 147 | +1. Retrieve the token, write it to a secure temporary file, and run **bcp**: |
| 148 | + |
| 149 | + ```bash |
| 150 | + # Create a secure temporary file for the token |
| 151 | + tokenFile=$(mktemp) |
| 152 | + chmod 600 "$tokenFile" |
| 153 | + |
| 154 | + # Retrieve the access token and write it as UTF-16LE without BOM |
| 155 | + az account get-access-token --resource https://database.windows.net --output tsv | cut -f 1 | tr -d '\n' | iconv -f ascii -t UTF-16LE > "$tokenFile" |
| 156 | + |
| 157 | + # Run bcp with the token file |
| 158 | + bcp bcptest out data2.dat -S <server>.database.windows.net -d testdb -G -P "$tokenFile" -c |
| 159 | + |
| 160 | + # Clean up token file |
| 161 | + rm -f "$tokenFile" |
| 162 | + ``` |
| 163 | + |
| 164 | +### User-assigned managed identity |
| 165 | + |
| 166 | +1. Sign in with your user-assigned managed identity. Replace `<client_id>` with a valid value for your environment. |
| 167 | + |
| 168 | + ```bash |
| 169 | + az login --identity --username <client_id> |
| 170 | + ``` |
| 171 | + |
| 172 | +1. Retrieve the token, write it to a secure temporary file, and run **bcp**. Replace `<server>` with a valid value for your environment. |
| 173 | + |
| 174 | + ```bash |
| 175 | + # Create a secure temporary file for the token |
| 176 | + tokenFile=$(mktemp) |
| 177 | + chmod 600 "$tokenFile" |
| 178 | + |
| 179 | + # Retrieve the access token and write it as UTF-16LE without BOM |
| 180 | + az account get-access-token --resource https://database.windows.net --output tsv | cut -f 1 | tr -d '\n' | iconv -f ascii -t UTF-16LE > "$tokenFile" |
| 181 | + |
| 182 | + # Run bcp with the token file |
| 183 | + bcp bcptest out data2.dat -S <server>.database.windows.net -d testdb -G -P "$tokenFile" -c |
| 184 | + |
| 185 | + # Clean up token file |
| 186 | + rm -f "$tokenFile" |
| 187 | + ``` |
| 188 | + |
| 189 | +## Microsoft Entra interactive |
| 190 | + |
| 191 | +**Applies to**: Windows only. Linux and macOS aren't supported. |
| 192 | + |
| 193 | +Microsoft Entra interactive authentication uses a dialog to authenticate, and supports multifactor authentication (MFA). Interactive authentication requires **bcp** [version 15.0.1000.34](bcp-download-install.md#download-the-latest-version) or later, and [ODBC Driver 18 for SQL Server](../../connect/odbc/download-odbc-driver-for-sql-server.md) (or driver 17.2 or later). |
| 194 | + |
| 195 | +Provide `-G` with `-U` (username) only. Don't include `-P`. **bcp** prompts for the password (or for accounts with MFA enabled, completes the configured MFA flow). |
| 196 | + |
| 197 | +```console |
| 198 | +bcp bcptest out "c:\last\data1.dat" -c -S contoso.database.windows.net -d testdb -G -U alice@contoso.onmicrosoft.com |
| 199 | +``` |
| 200 | + |
| 201 | +For a Microsoft Entra user that's a Windows account from a federated domain, include the domain in the username (for example, `joe@contoso.com`): |
| 202 | + |
| 203 | +```console |
| 204 | +bcp bcptest out "c:\last\data1.dat" -c -S contoso.database.windows.net -d testdb -G -U joe@contoso.com |
| 205 | +``` |
| 206 | + |
| 207 | +If guest users in a Microsoft Entra tenant are part of a group that has database permissions in [!INCLUDE [ssazure-sqldb](../../includes/ssazure-sqldb.md)], use the guest user alias (for example, `keith0@adventure-works.com`). |
| 208 | + |
| 209 | +## Related content |
| 210 | + |
| 211 | +- [bcp utility](bcp-utility.md) |
| 212 | +- [Download and install the bcp utility](bcp-download-install.md) |
| 213 | +- [How to use the bcp utility](bcp-use-utility.md) |
| 214 | +- [Microsoft Entra authentication for Azure SQL](/azure/azure-sql/database/authentication-aad-overview) |
| 215 | +- [Authentication in SQL database in Microsoft Fabric](/fabric/database/sql/authentication) |
| 216 | + |
| 217 | +[!INCLUDE [get-help-options](../../includes/paragraph-content/get-help-options.md)] |
![learn-build-service-prod[bot]](https://avatars.githubusercontent.com/in/237442?v=4&size=40){kind=avatar}
0 commit comments