Obter um principal de serviço existente

  • Artigo

Listar entidades de serviço

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

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

  • --display-name Solicita entidades de serviço que tenham 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 durante a --name criação. Se você não definiu --name durante a criação da entidade de serviço, o prefixo do nome é azure-cli-.
  • --spn Filtra a correspondência exata do nome da entidade de serviço. O nome da entidade de serviço sempre começa com https://. se o valor usado não --name for um URI, esse valor será https:// seguido pelo nome para exibição.
  • --show-mine Solicita apenas entidades de serviço criadas pelo usuário conectado.
  • --filter usa um filtro OData e executa a filtragem do lado do servidor. Esse método é recomendado sobre a filtragem do lado do cliente com o parâmetro da --query CLI. Para saber mais sobre filtros OData, consulte Sintaxe de expressão OData para filtros.

As informações retornadas para objetos de entidade de serviço são detalhadas. Para obter apenas as informações necessárias para entrar, use a cadeia de caracteres de [].{id:appId, tenant:appOwnerOrganizationId}consulta . Eis um exemplo que obtém as informações de início de sessão para todas as entidades de serviço criadas pelo utilizador com sessão iniciada no momento:

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

Se você estiver trabalhando em uma grande organização com muitas entidades de serviço, tente 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. Os segredos para certificados no Cofre de Chaves do Azure podem ser recuperados com az keyvault secret show, mas nenhum outro segredo é armazenado por padrão. Se você esquecer um método de autenticação ou 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 listo , 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 --query parâmetro 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"

Passos Seguintes

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

Gerenciar funções principais de serviço