Obter uma entidade de serviço existente

  • Artigo

Listar as entidades de serviço

Se você já tiver uma entidade de serviço existente que deseja usar, esta etapa explica como recuperar a entidade de serviço existente.

Uma lista das entidades de serviço em um locatário pode ser recuperada com o comando az ad sp list. Por padrão, esse comando retorna as 100 primeiras entidades de serviço do locatário. Para obter todas as entidades de serviço de um locatário, use o parâmetro --all. Obter essa lista pode levar muito tempo, portanto, é recomendável que você filtre a lista com um dos seguintes parâmetros:

  • --display-name envia solicitações às entidades de serviço que têm um prefixo que corresponda ao nome fornecido. O nome de exibição de uma entidade de serviço é o valor definido com o parâmetro --name durante a criação. Se você não definiu --name durante a criação da entidade de serviço, o prefixo do nome será azure-cli-.
  • --spn filtra a correspondência do nome exato da entidade de serviço. O nome da entidade de serviço sempre começa com https://. se o valor usado para --name não era um URI, esse valor é https:// seguido do nome de exibição.
  • --show-mine só envia solicitações às entidades de serviço criadas pelo usuário conectado.
  • --filter usa um filtro OData e realiza a filtragem do lado do servidor. Esse método é recomendado para a filtragem do lado do cliente com o parâmetro --query da CLI. Para saber mais sobre os filtros do OData, confira Sintaxe de expressão do OData para filtros.

As informações retornadas para objetos da entidade de serviço são detalhadas. Para obter apenas as informações necessárias para entrar, use a cadeia de consulta [].{id:appId, tenant:appOwnerOrganizationId}. Aqui está um exemplo que obtém as informações de entrada de todas as entidades de serviço criadas pelo usuário atualmente conectado:

az ad sp list --show-mine --query "[].{SPname:displayName, SPid:appId, tenant:appOwnerOrganizationId}" --output table

Se você estiver trabalhando em uma organização de grande porte com muitas entidades de serviço, experimente estes exemplos de comando:

# get service principals containing a keyword
az ad sp list --display-name mySearchWord --output table

# get service principals using an OData filter
az ad sp list --filter "displayname eq 'myExactServicePrincipalName'" --output json

# get a service principal having a certain servicePrincipalNames property value
az ad sp list --spn https://spURL.com

Importante

O usuário e o locatário podem ser recuperados com az ad sp list e az ad sp show, mas os segredos de autenticação ou o método de autenticação não estão disponíveis. Segredos para certificados no Azure Key Vault podem ser recuperados com az keyvault secret show, mas nenhum outro segredo é armazenado por padrão. Se você esquecer o método de autenticação ou o segredo, redefina as credenciais da entidade de serviço.

Propriedades da entidade de serviço

Quando você obtém uma lista de entidades de serviço usando az ad sp list, há muitas propriedades de saída que você pode referenciar em seu script.

[
  {
    "accountEnabled": true,
    "addIns": [],
    "alternativeNames": [],
    "appDescription": null,
    "appDisplayName": "myServicePrincipalName",
    "appId": "00000000-0000-0000-0000-000000000000",
    "appOwnerOrganizationId": "00000000-0000-0000-0000-000000000000",
    "appRoleAssignmentRequired": false,
    "appRoles": [],
    "applicationTemplateId": null,
    "createdDateTime": null,
    "deletedDateTime": null,
    "description": null,
    "disabledByMicrosoftStatus": null,
    "displayName": "myServicePrincipalName",
    "homepage": "https://myURL.com",
    "id": "00000000-0000-0000-0000-000000000000",
    "info": {
      "logoUrl": null,
      "marketingUrl": null,
      "privacyStatementUrl": null,
      "supportUrl": null,
      "termsOfServiceUrl": null
    },
    "keyCredentials": [],
    "loginUrl": null,
    "logoutUrl": null,
    "notes": null,
    "notificationEmailAddresses": [],
    "oauth2PermissionScopes": [
      {
        "adminConsentDescription": "my admin description",
        "adminConsentDisplayName": "my admin display name",
        "id": "00000000-0000-0000-0000-000000000000",
        "isEnabled": true,
        "type": "User",
        "userConsentDescription": "my user description",
        "userConsentDisplayName": "my user display name",
        "value": "user_impersonation"
      }
    ],
    "passwordCredentials": [],
    "preferredSingleSignOnMode": null,
    "preferredTokenSigningKeyThumbprint": null,
    "replyUrls": [],
    "resourceSpecificApplicationPermissions": [],
    "samlSingleSignOnSettings": null,
    "servicePrincipalNames": [
      "00000000-0000-0000-0000-000000000000",
      "https://myURL.com"
    ],
    "servicePrincipalType": "Application",
    "signInAudience": null,
    "tags": [
      "WindowsAzureActiveDirectoryIntegratedApp"
    ],
    "tokenEncryptionKeyId": null,
    "verifiedPublisher": {
      "addedDateTime": null,
      "displayName": null,
      "verifiedPublisherId": null
    }
  }
]

Use o parâmetro --query para recuperar e armazenar propriedades da entidade de serviço em variáveis.

# Bash script
spID=$(az ad sp list --display-name myServicePrincipalName --query "[].{spID:appId}" --output tsv)
tenantID=$(az ad sp list --display-name myServicePrincipalName --query "[].{tenant:appOwnerOrganizationId}" --output tsv)
userConsentDescr=$(az ad sp list --display-name myServicePrincipalName --query "[].{ucs:oauth2PermissionScopes.userConsentDescription[0]}" --output tsv)
echo "Using appId $spID in tenant $tenantID for $userConsentDescr"

Próximas etapas

Agora que você aprendeu a recuperar a entidade de serviço existente, prossiga para a próxima etapa para saber como gerenciar as funções da entidade de serviço.

Gerenciar as funções da entidades serviço