Obter um service principal existente

Listar entidades de serviço

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

Uma lista dos principais 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 parâmetro --all. Obter essa lista pode levar muito tempo, portanto, é recomendável filtrar a lista com um dos seguintes parâmetros:

• --display-name solicita entidades de serviço que têm um prefixo que corresponde ao nome fornecido. O nome de exibição de uma entidade de serviço é o valor definido com o --name parâmetro durante a criação. Se você não definiu --name durante a criação da entidade de serviço, o prefixo de nome será 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 que você usou para --name não for um URI, esse valor será https:// seguido pelo nome de exibição.
• --show-mine solicita somente entidades de serviço criadas pelo usuário autenticado.
• --filter usa um filtro OData e executa a filtragem do lado do servidor . Este método é recomendado em vez de filtrar o lado do cliente com o parâmetro da --query CLI. Para saber mais sobre filtros OData, consulte a sintaxe de expressão 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 caracteres de consulta [].{id:appId, tenant:appOwnerOrganizationId}. Aqui está um exemplo que obtém as informações de entrada para todas as entidades de serviço criadas pelo usuário conectado 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 muitos principais de serviço, experimente estes comandos de exemplo:

# 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

Propriedades da entidade de serviço

Quando você obtém uma lista de princípios 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 --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"

# PowerShell 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)
Write-Host "Using appId $spID in tenant $tenantID for $userConsentDescr"

Próximas etapas

Agora que você aprendeu a recuperar seu principal de serviço existente, prossiga para a próxima etapa para aprender a gerenciar suas funções de principal de serviço.