ManagedIdentityCredentialBuilder.resourceId/clientId/objectId Javadoc says "user-assigned or system-assigned"; an ID always selects a user-assigned identity

Library name

com.azure:azure-identity

Describe the bug

sdk/identity/azure-identity/src/main/java/com/azure/identity/ManagedIdentityCredentialBuilder.java:

    /**
     * Specifies the resource ID of a user-assigned or system-assigned managed identity.
     *
     * Only one of clientId, resourceId, or objectId can be specified.
     *
     * @param resourceId the resource ID
     * @return the ManagedIdentityCredentialBuilder itself
     */
    public ManagedIdentityCredentialBuilder resourceId(String resourceId) {

clientId(String) and objectId(String) directly above and below it have the
same first sentence ("Specifies the client ID / object ID of a user-assigned or
system-assigned managed identity").

That's not how the credential behaves. Setting any of these IDs selects a
user-assigned identity; the system-assigned identity is what you get when
you set none of them. From IdentityClientBase:

            managedIdentityId = ManagedIdentityId.userAssignedClientId(clientId);
            ...
            managedIdentityId = ManagedIdentityId.userAssignedResourceId(resourceId);
            ...
            managedIdentityId = ManagedIdentityId.userAssignedObjectId(objectId);
            ...
            managedIdentityId = ManagedIdentityId.systemAssigned();

ManagedIdentityCredential itself also has the comment "Not having a
managedIdentityId at this point means it is a system-assigned managed identity",
and its error message for unsupported hosts tells users to "remove the configured
client ID" to use system-assigned. The class-level Javadoc already
gets this right too ("... objectId(String) to select a user-assigned identity").

Why it matters

Someone with a system-assigned identity reads this and passes the resource ID of
their VM/App Service (or the system identity's principal ID as objectId),
expecting that to target the system identity. The request then goes out as a
user-assigned lookup and fails with an "identity not found / not assigned"
error that is hard to connect back to this. The correct guidance for
system-assigned is just "don't call any of these", and right now the Javadoc
doesn't say that anywhere on these methods.

Suggested fix

     /**
-     * Specifies the client ID of a user-assigned or system-assigned managed identity.
+     * Specifies the client ID of a user-assigned managed identity. If none of clientId, resourceId, or objectId
+     * is set, the system-assigned managed identity is used.
      *
      * Only one of clientId, resourceId, or objectId can be specified.
@@
     /**
-     * Specifies the resource ID of a user-assigned or system-assigned managed identity.
+     * Specifies the resource ID of a user-assigned managed identity. If none of clientId, resourceId, or objectId
+     * is set, the system-assigned managed identity is used.
      *
      * Only one of clientId, resourceId, or objectId can be specified.
@@
     /**
-     * Specifies the object ID of a user-assigned or system-assigned managed identity.
+     * Specifies the object ID of a user-assigned managed identity. If none of clientId, resourceId, or objectId
+     * is set, the system-assigned managed identity is used.
      *
      * Only one of clientId, resourceId, or objectId can be specified.

DefaultAzureCredentialBuilder.managedIdentityClientId /
managedIdentityResourceId open with similar wording ("Specifies the resource ID
of user assigned or system assigned identity ..."), although their next sentences
do say that leaving it unset "will only work with system assigned managed
identities". Worth tidying the first sentence there in the same pass.

Upstream reference

The .NET SDK clarified the same point in Azure/azure-sdk-for-net@da94df7bf3
("Clarify when system vs. user-assigned managed identity is used",
Azure/azure-sdk-for-net#43802, 2024-05-01):

--- a/sdk/identity/Azure.Identity/src/Credentials/ManagedIdentityCredential.cs
+++ b/sdk/identity/Azure.Identity/src/Credentials/ManagedIdentityCredential.cs
@@ -33,11 +33,11 @@
         /// <summary>
-        /// Creates an instance of the ManagedIdentityCredential capable of authenticating a resource with a managed identity.
+        /// Creates an instance of <see cref="ManagedIdentityCredential"/> capable of authenticating a resource with a user-assigned or a system-assigned managed identity.
         /// </summary>
         /// <param name="clientId">
-        /// The client ID to authenticate for a user-assigned managed identity. More information on user-assigned managed identities can be found at
-        /// <see href="https://learn.microsoft.com/entra/identity/managed-identities-azure-resources/overview#how-a-user-assigned-managed-identity-works-with-an-azure-vm"/>.
+        /// The client ID to authenticate for a <see href="https://learn.microsoft.com/entra/identity/managed-identities-azure-resources/overview#how-a-user-assigned-managed-identity-works-with-an-azure-vm">user-assigned managed identity</see>.
+        /// If not provided, a system-assigned managed identity is used.
         /// </param>
@@ -47,11 +47,10 @@
         /// <summary>
-        /// Creates an instance of the ManagedIdentityCredential capable of authenticating a resource with a managed identity.
+        /// Creates an instance of <see cref="ManagedIdentityCredential"/> capable of authenticating a resource with a user-assigned managed identity.
         /// </summary>
         /// <param name="resourceId">
-        /// The resource ID to authenticate for a user-assigned managed identity. More information on user-assigned managed identities can be found at
-        /// <see href="https://learn.microsoft.com/entra/identity/managed-identities-azure-resources/overview#how-a-user-assigned-managed-identity-works-with-an-azure-vm"/>.
+        /// The resource ID to authenticate for a <see href="https://learn.microsoft.com/entra/identity/managed-identities-azure-resources/overview#how-a-user-assigned-managed-identity-works-with-an-azure-vm">user-assigned managed identity</see>.
         /// </param>

The same commit added "If neither ... is set, then a system-assigned managed
identity is used" remarks to DefaultAzureCredentialOptions.ManagedIdentityClientId
and ManagedIdentityResourceId. Java's builder setters map one-to-one onto these,
so the same wording applies: an ID means user-assigned, no ID means
system-assigned.

I can submit a PR for this.