[Reference] freshness project: Profile (az account, az login)

[dbradish-microsoft]

This PR is part of the reference refresh project. This PR focuses on src/azure-cli/azure/cli/command_modules/profile/_help.py and any related file containing summaries or examples for these same command groups.

The updates in this PR are intended to freshen the following reference areas:

1. short-summary
2. long-summary
3. examples

Note: The testing of all examples is out of scope for this project and is part of the Content Quality Automation crew project.

This is work item https://dev.azure.com/mseng/TechnicalContent/_workitems/edit/1998772.

---

This checklist is used to make sure that common guidelines for a pull request are followed.

• The PR title and description has followed the guideline in Submitting Pull Requests.

• I adhere to the Command Guidelines.

• I adhere to the Error Handling Guidelines.

[yonzhan]

Reference

[dbradish-microsoft]

@jiasli, do I understand correctly that autogen content can only handle one line per code block? These are separate lines in the PY.

[jiasli]

Link to #24332

[jiasli]

@dbradish-microsoft, this is because one line break is converted to space in a > context:

  text: >
    az account show --query name
    az account show --query user.name

If you want to make a line break, use

  text: >
    az account show --query name

    az account show --query user.name

Also, you may use |:

  text: |
    az account show --query name
    az account show --query user.name

[jiasli]

Similar to #24332 (comment)

These lines can simply be done with

az account set --subscription OneOfMySubscriptionNames

[jiasli]

This example has little real-world usage, as it can be replaced by az account show. Only one subscription can have isDefault==True.

[jiasli]

We now recommend using tenant ID, instead of domain name, as domain name requires extra resolution (#10418):

azure-cli/src/azure-cli/azure/cli/command_modules/profile/_validators.py

Lines 12 to 31 in a7afdf1

	def validate_tenant(cmd, namespace):
	"""
	Make sure tenant is a GUID. If domain name is provided, resolve to GUID.
	https://docs.microsoft.com/azure/active-directory/develop/v2-protocols-oidc#fetch-the-openid-connect-metadata-document
	"""
	from azure.cli.core.util import is_guid
	if namespace.tenant is not None and not is_guid(namespace.tenant):
	import requests
	active_directory_endpoint = cmd.cli_ctx.cloud.endpoints.active_directory
	url = '{}/{}/.well-known/openid-configuration'.format(active_directory_endpoint, namespace.tenant)
	response = requests.get(url, verify=not should_disable_connection_verify())
	if response.status_code != 200:
	from knack.util import CLIError
	raise CLIError("Failed to resolve tenant '{}'.\n\nError detail: {}".format(namespace.tenant, response.text))
	# Example issuer: https://sts.windows.net/72f988bf-86f1-41af-91ab-2d7cd011db47/
	tenant_id = response.json()['issuer'].split("/")[3]
	logger.debug('Resolved tenant domain name %s to GUID %s', namespace.tenant, tenant_id)
	namespace.tenant = tenant_id

[jiasli]

returning results in your default format

This applies to all commands, not only az account show.

[jiasli]

Same as https://github.com/Azure/azure-cli/pull/24633/files#r1069113853

[jiasli]

Suggested change

	text: >
	az account get-access-token --resource MyResourceID
	text: az account get-access-token --resource https://management.azure.com/

https://management.azure.com/ is a more concrete example compared to MyResourceID.

[jiasli]

Failed to connect to MSI... is a Cloud Shell bug. It is not related to non-existing resource.

Suggested change

	- name: Get an access token information for a particular resource. If you receive a `Failed to connect to MSI...` error, your resource may not exist.
	- name: Get an access token information for a particular resource.

[jiasli]

Suggested change

	- name: Get only the access token for a particular resource returning results in plain text. This script is useful when you want to store the token in a variable.
	- name: Get only the access token for a particular resource returning results in plain text. This command is useful when you want to store the token in a variable.

[jiasli]

Suggested change

	- name: Get an access token for a particular scope
	- name: Get an access token information for a particular scope

We may make it consistent with other examples.

[jiasli]

Suggested change

	- name: Log in using a VM's system assigned identity.
	- name: Log in using default managed identity.

Not only VM has managed identity.

Also, if no system-assigned identity is configured, but a user assigned identity is, this command uses the user-assigned identity as the default one.

If both system-assigned identity and user-assigned identity are configured, system-assigned identity is chosen as the default.

[jiasli]

As discussed in #24332 (comment), I am hesitating on whether we want to add examples for generic argument --query.

[jiasli]

Suggested change

	text: aaz login --service-principal --user http://azure-cli-2016-08-05-14-31-15 --password ~/MyCertfile.pem --tenant contoso.onmicrosoft.com
	text: az login --service-principal --user http://azure-cli-2016-08-05-14-31-15 --password ~/MyCertfile.pem --tenant contoso.onmicrosoft.com

[jiasli]

Suggested change

	- name: Log in using a VM's user assigned identity. Client or object ids of the service identity also work.
	- name: Log in using a VM's user-assigned identity. Client ID or object ID of the user-assigned identity also works.

There should be a hyphen in user-assigned: https://learn.microsoft.com/en-us/azure/active-directory/managed-identities-azure-resources/overview

[jiasli]

Suggested change

	text: az login --identity --user /subscriptions/MySubscriptionID/resourcegroups/MyResourceGroup/providers/Microsoft.ManagedIdentity/userAssignedIdentities/myID
	text: az login --identity --username /subscriptions/MySubscriptionID/resourcegroups/MyResourceGroup/providers/Microsoft.ManagedIdentity/userAssignedIdentities/myID

[jiasli]

Suggested change

	text: >
	az account show --query user.name
	text: az account show --query user.name

[jiasli]

Extra line break is needed as L84 uses >, not |.

We can test the rendered help message by running az account show --help.

[jiasli]

This will no longer be the case once CAE is enabled. We'd better not mention such implementation detail. The user should always check the expiresOn property of the returned JSON.

Also see #19700

[dbradish-microsoft]

I am giving the methodology for freshening azCLI autogen reference content, and consequently this PR, a necessary ending in order to make way for new beginnings.