Azure / Azure/azure-rest-api-specs
Copy Blob From URL doc incorrectly states cross-account source cannot use Microsoft Entra ID authorization
- Dominant language
- TypeSpec
- Stars
- 3.1k
- Forks
- 5.9k
- Avg merge
- 2d 22h
- Merged PRs (30d)
- 444
Description
## Copy Blob From URL doc incorrectly states cross-account source cannot use Microsoft Entra ID authorization
**Doc URL:** https://learn.microsoft.com/en-us/rest/api/storageservices/copy-blob-from-url?tabs=microsoft-entra-id
### Description
The "Copy Blob From URL" documentation contains several contradictions regarding whether Microsoft Entra ID (OAuth 2.0) can be used to authorize the **source blob** in a cross-account copy operation. The Remarks section correctly states Entra ID is supported (since version 2020-10-02), but multiple other sections explicitly say it is not, causing confusion and wasted troubleshooting time.
### Specific issues
**1. Introduction paragraph**
Current text:
> "The source for a Copy Blob From URL operation can be any committed block blob in any Azure storage account that's either public or authorized with a shared access signature."
**Problem:** Omits that the source can also be authorized via a Microsoft Entra ID Bearer token using the `x-ms-copy-source-authorization` header (version 2020-10-02+).
**2. `x-ms-copy-source` request header description**
Current text:
> "The source blob must either be public or be authorized via a shared access signature."
**Problem:** Same omission — does not mention the `x-ms-copy-source-authorization` Bearer token option.
**3. Authorization table**
The table currently shows Microsoft Entra ID as **"No"** for "Source blob in another storage account". This is incorrect. Cross-account source blobs **can** be authorized via Entra ID using `x-ms-copy-source-authorization: Bearer ` (version 2020-10-02+).
**4. Authorization note below the table**
Current text:
> "Note that a source blob in a different storage account must be authorized separately via SAS token with the Read (r) permission."
**Problem:** Omits the Bearer token option as an alternative to SAS.
**5. Remarks section — correct but buried**
> "In version 2020-10-02 and later, Microsoft Entra authorization is supported for the source of the copy operation."
This is the only correct statement, but it directly contradicts points 1–4 above and is buried at the bottom of the page.
### Suggested fixes
1. **Intro paragraph:** Add ", or authorized with a Microsoft Entra ID Bearer token via the `x-ms-copy-source-authorization` header (version 2020-10-02 and later)"
2. **`x-ms-copy-source` header:** Add ", or be authorized via a Microsoft Entra ID Bearer token provided in the `x-ms-copy-source-authorization` header"
3. **Authorization table:** Change source blob in another storage account / Microsoft Entra ID from "No" to "Yes (via `x-ms-copy-source-authorization` header, version 2020-10-02+)"
4. **Authorization note:** Update to: "A source blob in a different storage account must be authorized separately, either via a SAS token with the Read (r) permission, or via a Microsoft Entra ID Bearer token in the `x-ms-copy-source-authorization` header. The identity must have Storage Blob Data Reader (or higher) on the source."
5. **Add a cross-account example** showing both `Authorization` and `x-ms-copy-source-authorization` headers with Bearer tokens, plus the required `x-ms-requires-sync: true` header.
### Verified behavior
I confirmed that cross-account Copy Blob From URL with Entra ID Bearer tokens works correctly when:
- `x-ms-requires-sync: true` is set
- Token is acquired with the `https://storage.azure.com/.default` scope
- The identity has **Storage Blob Data Reader** on the source and **Storage Blob Data Contributor** on the destination
Without `x-ms-requires-sync: true`, the `x-ms-copy-source-authorization` header is silently ignored, resulting in a `401 CannotVerifyCopySource` error. This critical relationship is also not documented.
Contributor guide
Research direction
Open the Copy Blob From URL documentation page and review the introduction, x-ms-copy-source header description, authorization table and note, and Remarks section. Update the contradictory cross-account authorization text and add the requested example using both Bearer headers and x-ms-requires-sync; the page should consistently document Microsoft Entra ID support and required permissions.
Written by the indexing model from the issue text.
Assessment
- Tech stack
- azure, openapi
- Domain
- api, documentation
- Issue type
- Documentation
- Difficulty
- 2/5
- Estimated time
- 1-3 hours
- Activity status
- Quiet
- Clarity
- Clearly specified
- Newbie friendliness
- 72/100