Josimar Hedler
Índice
Credenciais de aplicativos expiram em silêncio, um client secret criado há dois anos por alguém que já saiu da empresa vence numa sexta-feira e, na segunda, uma integração parou, um pipeline falhou e o chamado chega como “o Entra está com problema”. Na maioria das vezes, o problema é uma credencial vencida que ninguém estava acompanhando.
Para reduzir esse tipo de surpresa, o Microsoft Entra Recommendations identifica aplicativos com credenciais próximas do vencimento e leva o administrador direto ao local de correção, na API do Microsoft Graph, essa recomendação é chamada de applicationCredentialExpiry.
Neste artigo, será demonstrado como consultar essa recomendação e renovar um client secret via Microsoft Graph e PowerShell, validando o uso da nova credencial antes de remover a antiga.
Atenção: As implementações apresentadas em nossos artigos foram desenvolvidas com base em documentações oficiais e nas boas práticas recomendadas pela Microsoft. Entretanto, enfatizamos que qualquer implementação deve ser previamente testada em ambientes de homologação ou testes para garantir a segurança e a estabilidade do ambiente de produção.
Como a recomendação identifica credenciais expirando
Credenciais de aplicativo podem ser certificados ou segredos registrados no app, usados para provar a identidade dele, uma credencial é considerada expirando quando está em um registro de aplicativo e vence nos próximos 30 dias.
Ficam fora da recomendação:
- credenciais que foram identificadas como expirando, mas removidas do registro do aplicativo depois;
- credenciais que já expiraram, que aparecem como concluídas em Impacted resources.
Cada recomendação possui Status (Active, Completed, Dismissed ou Postponed) e Prioridade (Low, Medium ou High), a conclusão é automática quando todos os recursos impactados são resolvidos, e não é possível marcar como Completed manualmente. os dados são atualizados a cada 24 horas, com um dia de atraso, e em casos raros podem levar até 72 horas.
Nota: por estar em preview, a recomendação pode não aparecer em todos os tenants no portal, mesmo com a função correta, dependendo de licenciamento ou de não haver credenciais expirando dentro da janela de 30 dias. Por isso, o hands on deste artigo usa diretamente o Microsoft Graph, que funciona independente disso.
Por que e quando renovar
Renovar a credencial antes do vencimento evita interrupções e reduz o risco de downtime, a recomendação é especialmente útil em tenants com muitos aplicativos e sem um dono claro para cada credencial, porque entrega o nome do aplicativo, o ID e o caminho direto para a correção.
Boas práticas
- Mantenha pelo menos dois owners por aplicativo.
- Armazene os valores em cofres seguros, como o Azure Key Vault, o valor de um client secret só é exibido na criação.
- Sempre que possível, prefira certificados, federated credentials ou Managed Identity a client secrets. Tenho um artigo completo sobre como bloquear client secret.
- Nunca remova a credencial antiga antes de validar o uso da nova.
Permissões necessárias
Para visualizar e atualizar a recomendação:
- Somente leitura: Reports Reader, Security Reader ou Global Reader.
- Leitura e atualização: Security Administrator, Authentication Policy Administrator ou Exchange Administrator.
- Microsoft Graph:
DirectoryRecommendations.Read.All(leitura) eDirectoryRecommendations.ReadWrite.All(leitura e atualização).
Além da recomendação em si, este artigo usa outros escopos do Microsoft Graph ao longo do hands on:
Application.Read.Allpara listar aplicativos e identificar credenciais próximas do vencimento.Application.ReadWrite.Allpara criar e remover credenciais.AuditLog.Read.Allpara validar, nos sign-in logs, que a credencial nova está em uso.
Esta recomendação especificamente exige a licença Microsoft Entra Workload ID, conforme indicado na coluna “Required licenses” do próprio portal de recomendações não basta ter Entra ID P1/P2. Isso explica por que ela pode não aparecer mesmo em tenants com boas licenças, mas sem o Workload ID especificamente.
Importante: para renovar a credencial, você precisa ser owner do aplicativo ou ter função de gerenciamento de aplicativos, ou a permissão Application.ReadWrite.All no Graph. Isso é diferente de apenas visualizar a recomendação, trate essas funções como privilégios sensíveis, porque quem pode adicionar credenciais a um aplicativo pode assumir o controle dele.
Vamos para o Hands On
- Acesse Entra ID > Overview > Recommendations
- Localize “Renew expiring application credentials” na lista
- Confira a coluna “Required licenses” esta recomendação exige Microsoft Entra Workload ID
Ao abrir “Renew expiring application credentials“, a tela mostra os Impacted resources neste caso, o Entra identificou 1 aplicativo ativo com credencial expirando.
Na tela que abrir ao lado, você poderá ver qual App precisa estar com a credencial expirando
A partir daqui, o restante do processo criar a nova credencial, validar e remover a antiga pode ser feito clicando em Update credential (que leva direto para Certificates & secrets no portal). Se o seu tenant não tiver a licença Microsoft Entra Workload ID e a recomendação não aparecer na interface, o mesmo processo pode ser feito via Microsoft Graph, que é o caminho detalhado neste artigo a partir da próxima seção.
Módulos do PowerShell necessários
Este artigo usa o Microsoft Graph PowerShell SDK. Antes de começar, verifique se os módulos abaixo estão instalados e atualizados:
Get-InstalledModule Microsoft.Graph.Authentication, Microsoft.Graph.Applications |
Select-Object Name, VersionSe algum módulo não aparecer na lista, instale:
Install-Module Microsoft.Graph.Authentication -Scope CurrentUser -Force
Install-Module Microsoft.Graph.Applications -Scope CurrentUser -ForceSe já estiverem instalados, mas em versões diferentes entre si, atualize:
Update-Module Microsoft.Graph.Authentication
Update-Module Microsoft.Graph.ApplicationsAtenção: módulos do Microsoft Graph em versões diferentes entre si costumam gerar o erro Assembly with same name is already loaded ao executar comandos que dependem de módulos distintos na mesma sessão, depois de instalar ou atualizar, feche o terminal completamente e abra uma nova janela antes de continuar o PowerShell mantém em cache os assemblies já carregados, e isso não é resolvido apenas rodando o Update-Module.
Todo o hands on abaixo é feito via Microsoft Graph PowerShell SDK, com o Microsoft Entra ID aberto em paralelo apenas para conferência visual.
Verificando rapidamente pela interface
Mesmo quando a recomendação applicationCredentialExpiry não está disponível no tenant, o Entra ID sinaliza credenciais vencendo direto na lista de aplicativos:
- Acesse Entra ID > App registrations
- Observe a coluna Certificates & secrets
- Aplicativos com credencial vencendo em breve mostram o aviso ⚠️ Expiring soon
Esse aviso é nativo da tela de App registrations e não depende de licença nem do preview de Recommendations é o ponto de partida mais rápido antes de ir para o Graph.
Nota: O “Expiring soon” no portal é útil para conferir poucos aplicativos, mas não escala nem permite ordenar por data, para tenants com muitos apps, o script abaixo consulta tudo de uma vez via Microsoft Graph e já traz ordenado pela data de expiração.
Consultando a recomendação via Microsoft Graph
A recomendação nativa applicationCredentialExpiry pode ser consultada diretamente via Microsoft Graph, o endpoint de recomendações está disponível apenas em beta em v1.0 ele retorna erro “Resource not found for the segment ‘recommendations’.
Connect-MgGraph -Scopes "DirectoryRecommendations.Read.All", "Application.Read.All" -NoWelcome
# Localiza a recomendação de credenciais expirando (endpoint em beta)
$uri = "https://graph.microsoft.com/beta/directory/recommendations?`$filter=recommendationType eq 'applicationCredentialExpiry'"
$rec = (Invoke-MgGraphRequest -Method GET -Uri $uri).value
if ($rec) {
# Lista todos os recursos impactados
$impacted = Invoke-MgGraphRequest -Method GET `
-Uri "https://graph.microsoft.com/beta/directory/recommendations/$($rec[0].id)/impactedResources"
$impacted.value | Select-Object displayName, id, status
} else {
Write-Host "Nenhuma recomendação retornada para applicationCredentialExpiry neste tenant." -ForegroundColor Yellow
}Observação: neste tenant, mesmo consultando diretamente o endpoint beta, applicationCredentialExpiry não retornou nenhum item confirmado inclusive ao listar todas as recomendações do tenant sem filtro, que trouxe outros tipos ativos (como mfaRegistrationV2 e blockLegacyAuthentication), mas nenhum desta. Isso indica que a recomendação ainda não foi liberada para todos os tenants durante o preview.
Identificando credenciais próximas do vencimento (sem depender da recomendação)
Caso a recomendação não retorne nenhum item, é possível varrer os próprios aplicativos e listar quem tem credencial vencendo:
$limite = (Get-Date).AddDays(30)
Get-MgApplication -All | ForEach-Object {
$app = $_
$todasCredenciais = @($app.PasswordCredentials) + @($app.KeyCredentials)
$todasCredenciais | Where-Object { $_.EndDateTime -lt $limite -and $_.EndDateTime -gt (Get-Date) } |
ForEach-Object {
[PSCustomObject]@{
Aplicativo = $app.DisplayName
AppObjectId = $app.Id
KeyId = $_.KeyId
Tipo = if ($_.PSObject.Properties.Name -contains "SecretText") { "Client Secret" } else { "Certificado" }
Expira = $_.EndDateTime
}
}
} | Sort-Object Expira
Nota: a conexão acima já inclui os escopos usados pelos dois scripts anteriores, a recomendação nativa e varredura manual. Se for executar só o segundo, sem passar pelo primeiro, conecte separadamente com Connect-MgGraph -Scopes "Application.Read.All".
Criando a nova credencial
Observação: aqui é necessário conectar novamente, agora com Application.ReadWrite.All, as seções anteriores usaram apenas permissões de leitura, e criar uma credencial exige escopo de escrita o Microsoft Graph segue o princípio de least privilege e não permite ação de escrita com um token de sessão que só pediu leitura.
Connect-MgGraph -Scopes "Application.ReadWrite.All"
# Object ID do app registration (não é o Application/Client ID)
# Troque pelo Object ID do SEU aplicativo — não reutilize um ID de outro tenant
$appObjectId = "<Object ID do aplicativo>"
# IMPORTANTE: este comando NÃO renova o secret existente, ele CRIA um novo,
# mantendo o antigo ativo em paralelo. É assim que se evita downtime:
# nunca remova o antigo antes de validar que o novo está em uso.
$novo = Add-MgApplicationPassword -ApplicationId $appObjectId -PasswordCredential @{
displayName = "rotacao-2026-09"
endDateTime = (Get-Date).AddMonths(6)
}
$novo.SecretText # Exibido só agora. Armazene direto em um cofre seguro (Key Vault).
A execução retornou o valor do novo client secret, que deve ser armazenado imediatamente em um cofre seguro esse é o único momento em que ele fica visível.
A tela de Certificates & secrets confirma a criação, agora existem dois client secrets ativos o antigo, ainda dentro do prazo, e o novo (rotacao-2026-09), válido até 3/24/2027.
Atenção: nunca imprima nem registre o valor do secret (SecretText) em logs de pipeline ou de console. Não remova a credencial antiga neste momento a ordem correta é criar a nova, atualizar o serviço, validar o uso e só então remover a antiga.
Atualizando o serviço
Atualize o código ou a configuração do serviço que consome o aplicativo (pipeline, automação, script, integração) para usar o novo segredo ou certificado, esta etapa depende do ambiente de cada aplicação e deve ser feita pelo responsável pelo serviço.
Validando a nova credencial
Consulte os sign-ins do service principal via Graph para confirmar que o Key ID usado é o da credencial nova, aqui é necessário conectar novamente, agora com o escopo AuditLog.Read.All. As etapas anteriores usaram Application.ReadWrite.All para criar a credencial, consultar sign-in logs exige uma permissão diferente, específica para logs de auditoria.
Connect-MgGraph -Scopes "AuditLog.Read.All"
$appId = "<Application (client) ID do aplicativo>"
# Filtro de service principal sign-ins só existe no endpoint beta
$headers = @{ ConsistencyLevel = "eventual" }
$uri = "https://graph.microsoft.com/beta/auditLogs/signIns?`$filter=appId eq '$appId' and signInEventTypes/any(t: t eq 'servicePrincipal')&`$count=true&`$top=5"
$resultado = Invoke-MgGraphRequest -Method GET -Uri $uri -Headers $headers
$resultado.value | Select-Object createdDateTime, appDisplayName, servicePrincipalId, servicePrincipalCredentialKeyId
Observação: o servicePrincipalCredentialKeyId retornado nesta consulta corresponde ao KeyId da credencial criada na etapa anterior (rotacao-2026-09), confirmando que o sign-in do aplicativo já está utilizando a nova credencial, e não a antiga.
Removendo a credencial antiga
Só depois de confirmar que a nova credencial está em uso:
Connect-MgGraph -Scopes "Application.ReadWrite.All"
$appObjectId = "<Object ID do aplicativo>"
$keyIdAntigo = "<Key ID do secret antigo>"
Remove-MgApplicationPassword -ApplicationId $appObjectId -KeyId $keyIdAntigo
A lista de Client secrets agora mostra apenas 1 credencial ativa (rotacao-2026-09), confirmando que a credencial antiga foi removida com sucesso e que o aplicativo está operando somente com a credencial nova.
Nota: ao longo deste hands on, você deve ter percebido que reconectamos várias vezes com escopos diferentes leitura de recomendações, leitura de aplicativos, escrita de credenciais e leitura de logs de auditoria. Isso é o princípio de least privilege em ação: cada ação usa apenas a permissão mínima necessária, em vez de uma única conexão com acesso amplo a tudo.
Renovar credenciais não deve ser uma reação ao incidente, e sim uma rotina, a recomendação do Entra mostra o que está perto de vencer quando disponível, mas quem garante a continuidade é o ciclo completo, identificar, criar a nova credencial, atualizar o serviço, validar o uso e remover a antiga.
Neste tenant, a recomendação applicationCredentialExpiry não esteve disponível durante os testes nem na interface, nem via Microsoft Graph em beta o que reforça por que vale conhecer o caminho manual, via Microsoft Graph e PowerShell, independente do que aparecer (ou não) no seu ambiente.
Links de referência:
Recomendação para renovar credenciais de aplicativos expirando
Recomendação do Microsoft Entra: Renovar credenciais de aplicativos expiradas (versão prévia)
Como usar as recomendações do Microsoft Entra
Renovar credenciais expirando de service principals
Visão geral do Microsoft Entra Recommendations
Recurso recommendation no Microsoft Graph
Objetos de aplicativo e service principal
Chegamos ao final deste artigo!
O que você achou dessa recomendação do Microsoft Entra para credenciais expirando?
Como sua empresa controla o vencimento de secrets e certificados de aplicativos hoje: inventário próprio, automação ou só quando algo quebra?
Compartilhe sua experiência com a comunidade e deixe sua opinião nos comentários.