LeadSoft.Adapter.Google.Workspace 10.1.0

← Voltar ao repositório

LeadSoft® Google Workspace Integration Adapter

LeadSoft.Adapter.Google.Workspace

Adapter .NET para integrar com os serviços de autenticação do Google Workspace — Single Sign-On via OAuth2 e consulta ao perfil expandido do usuário via People API.
Fornece uma camada leve, testável e orientada a interfaces para validação de ID Tokens e recuperação de dados de perfil, encapsulando o SDK do Google, validação de JWT e tratamento de erros de forma consistente para aplicações .NET 10.

Este pacote é um tributo independente e não é afiliado oficialmente ao Google.
Somos gratos pela disponibilização das APIs públicas do Google Identity e do Google People API. Ao utilizar este pacote, você concorda automaticamente com os Termos de Serviço do Google.

NuGet.Org: LeadSoft.Adapter.Google.Workspace

GitHub Repo: leadsoft-adapter-google

Principais características

• Compatível com .NET 10.0.
• Autenticação SSO via Google OAuth2 com validação de ID Token JWT.
• Suporte a lista de domínios permitidos (Workspace e/ou contas pessoais @gmail.com).
• Consulta ao perfil expandido do usuário via Google People API (nome, foto, telefone, aniversário).
• Autorização opcional por grupo de e-mail via Google Admin Directory API.
• Renovação de Access Token via Refresh Token, sem exigir novo login pelo usuário.
• Chamadas assíncronas com async/await.
• Fácil integração com injeção de dependência (IServiceCollection).
• Interface IGoogleSSO para facilitar testes e mocking.
• Suporte a registro como Scoped ou Singleton.
• Tratamento centralizado de erros com AppException e derivações — mensagens amigáveis para o chamador.
• Logging integrado via ILogger<T> com suporte opcional por DI — sem logs quando não configurado.
• Stack traces nos logs apenas em ambientes não-produtivos (ASPNETCORE_ENVIRONMENT != Production).
• Open Source (MIT License).

Variáveis de ambiente

Detalhes de GOOGLE_SSO_HOSTED_DOMAIN

Aceita um ou mais domínios separados por vírgula. Inclua gmail.com para aceitar contas pessoais do Google.

Nota técnica: contas @gmail.com não possuem o campo HostedDomain no token JWT do Google. O adapter identifica essas contas pelo campo email do token — que é assinado e verificado pelo Google, portanto não é spoofável.

Métodos disponíveis

IGoogleSSO

• Task<DTOGoogleUserResponse?> GetOAuthSSOAsync(string idToken, CancellationToken cancellationToken = default)

  • Valida o ID Token JWT emitido pelo Google após o login do usuário.
  • Verifica assinatura, expiração e Client ID automaticamente via SDK do Google.
  • Opcionalmente restringe login a uma lista de domínios (Workspace e/ou @gmail.com).
  • Lança UnauthorizedAppException quando o token é inválido ou expirou.
  • Lança ForbiddenAppException quando o domínio do usuário não é permitido.
  • Lança BadRequestAppException para erros de entrada inesperados.

• Task<DTOGoogleUserResponse?> GetOAuthSSOAsync(string idToken, IList<string> requiredEmailGroups, string accessToken, CancellationToken cancellationToken = default)

  • Executa o mesmo fluxo do overload acima, exigindo adicionalmente que o usuário pertença a pelo menos um dos grupos de e-mail em requiredEmailGroups.
  • A checagem de grupo consulta a Google Admin Directory API através de IsUserInGroupAsync — exige um accessToken do usuário com o escopo admin.directory.group.readonly concedido no consentimento (escopo sensível/restrito do Google, nem sempre disponível para consentimento de usuário comum — ver nota abaixo).
  • Lança ForbiddenAppException quando o usuário não pertence a nenhum dos grupos requeridos (além dos casos do overload simples).
  • Lança BadRequestAppException quando accessToken não é informado.

• Task<bool> IsUserInGroupAsync(string userEmail, IList<string> requiredEmailGroups, string accessToken, CancellationToken cancellationToken = default)

  • Verifica isoladamente se um usuário pertence a pelo menos um dos grupos de e-mail informados, sem passar pelo fluxo completo de login.
  • Útil para revalidar associação a grupo a qualquer momento (ex.: em cada requisição sensível), sem reemitir o ID Token.
  • Nunca lança exceção — falhas de comunicação com a Directory API (rede, escopo ausente, etc.) são registradas em log e tratadas como "usuário não pertence ao grupo", retornando false.

• Task<DTOGoogleRefreshTokenResponse> RefreshAccessTokenAsync(string refreshToken, CancellationToken cancellationToken = default)

  • Troca um Refresh Token por um novo Access Token junto ao Google, sem exigir que o usuário passe novamente pela tela de login.
  • O Refresh Token precisa ter sido obtido previamente pelo seu fluxo de autorização com access_type=offline (e prompt=consent na primeira vez) — este método não gera um Refresh Token novo, apenas troca um já existente.
  • Lança UnauthorizedAppException quando o Refresh Token é inválido, expirado ou foi revogado pelo Google (nesses casos é necessário um novo login completo).
  • Lança BadRequestAppException para erros de entrada inesperados.

Nota sobre admin.directory.group.readonly: é um escopo restrito do Google Workspace. Em muitos casos, o Access Token de um usuário comum obtido via consentimento OAuth simples não terá esse escopo — pode ser necessário que o app OAuth passe por verificação do Google, ou que o usuário autenticado seja administrador do Workspace. Teste esse fluxo no seu ambiente antes de depender dele em produção.

Instalação

Pelo CLI do .NET:

dotnet add package LeadSoft.Adapter.Google.Workspace

Ou via NuGet Package Manager no Visual Studio (pesquise por LeadSoft.Adapter.Google.Workspace).

Uso básico (exemplo)

Abaixo um exemplo genérico de como registrar e usar o adapter em uma aplicação ASP.NET Core / Console com DI.

// Program.cs (exemplo)
using LeadSoft.Adapter.Google.Workspace;

WebApplicationBuilder builder = WebApplication.CreateBuilder(args);

// Google SSO
builder.Services.AddGoogleSSO();        // scoped (padrão)
// builder.Services.AddGoogleSSO(true); // singleton

WebApplication app = builder.Build();
app.Run();

Exemplo de uso via injeção de dependência — validação de ID Token (SSO):

// Em um Controller, Service ou Minimal API endpoint:
public class AuthService(IGoogleSSO googleSSO)
{
    public async Task<DTOGoogleUserResponse?> LoginAsync(string idToken)
    {
        // Valida o token e retorna os dados básicos do usuário
        return await googleSSO.GetOAuthSSOAsync(idToken);
    }
}

Exemplo de uso — perfil expandido (após autenticação OAuth2 completa):

public class PerfilService(IGoogleSSO googleSSO)
{
    public async Task<DTOGoogleUserExpandedResponse?> ObterPerfilAsync(string accessToken)
    {
        // Retorna dados detalhados do usuário via People API
        return await googleSSO.GetUserProfileAsync(accessToken);
    }
}

Exemplo de uso — login restrito a grupos de e-mail:

public class AuthService(IGoogleSSO googleSSO)
{
    private static readonly string[] GruposPermitidos = ["equipe-interna@empresa.com"];

    public async Task<DTOGoogleUserResponse?> LoginRestritoAsync(string idToken, string accessToken)
    {
        // Lança ForbiddenAppException se o usuário não pertencer a nenhum dos grupos
        return await googleSSO.GetOAuthSSOAsync(idToken, GruposPermitidos, accessToken);
    }
}

Exemplo de uso — renovação de Access Token via Refresh Token:

public class SessaoService(IGoogleSSO googleSSO)
{
    public async Task<DTOGoogleRefreshTokenResponse> RenovarSessaoAsync(string refreshToken)
    {
        // Troca o Refresh Token por um novo Access Token, sem novo login
        return await googleSSO.RefreshAccessTokenAsync(refreshToken);
    }
}

DTOs de retorno

DTOGoogleUserResponse — GetOAuthSSOAsync

DTOGoogleUserExpandedResponse — GetUserProfileAsync

DTOGoogleRefreshTokenResponse — RefreshAccessTokenAsync

Logging

O adapter emite logs via ILogger<GoogleSSO> quando disponível. Ao registrar via DI (AddGoogleSSO()), o ILogger é resolvido automaticamente. Sem DI configurado, new GoogleSSO() funciona normalmente sem nenhum log.

O comportamento dos logs varia conforme ASPNETCORE_ENVIRONMENT:

Tratamento de erros

GetUserProfileAsync e IsUserInGroupAsync nunca lançam exceção — erros são registrados no log e retornam, respectivamente, null e false.

Configuração recomendada

• Configure GOOGLE_SSO_CLIENT_ID via variáveis de ambiente ou cofre seguro (Azure Key Vault, AWS Secrets Manager) — nunca em código-fonte.
• Defina GOOGLE_SSO_HOSTED_DOMAIN para restringir o login. Use vírgula para múltiplos domínios; inclua gmail.com para aceitar também contas pessoais do Google.
• Configure o logging padrão do ASP.NET Core (builder.Logging) para capturar os logs do adapter.
• Propague CancellationToken em todas as chamadas assíncronas.

Boas práticas de integração

• Valide o ID Token no servidor imediatamente após recebê-lo do frontend — nunca confie apenas na validação client-side.
• Não exponha diretamente os DTOs HTTP ao seu domínio — mapeie para modelos de domínio quando necessário.
• Use GetUserProfileAsync apenas quando precisar de dados adicionais (telefone, aniversário) além dos fornecidos pelo ID Token.
• Prefira o overload simples de GetOAuthSSOAsync para fluxos de login sem restrição por grupo — é mais rápido e não requer um Access Token separado.
• Trate a expiração/revogação do Refresh Token (UnauthorizedAppException em RefreshAccessTokenAsync) como sinal para forçar um novo login completo — não há como "reviver" um Refresh Token inválido.

Versionamento e Compatibilidade

• Destinado a .NET 10.0. Verifique a compatibilidade do pacote com seu projeto.
• Siga versionamento semântico: breaking changes → major, novas features → minor, correções → patch.

Documentação de referência

Licença

Consulte o arquivo de licença no repositório para detalhes sobre uso e redistribuição.

LeadSoft.Adapter.Google.Workspace — adapter simples e testável para autenticação via Google SSO e acesso ao perfil do usuário em aplicações .NET 10.

Development

Desenvolvido pelo time da LeadSoft® Soluções Web.

• Lucas Resende Tavares

Nossa empresa

LeadSoft Soluções Web Ltda
CNPJ 38.043.762/0001-48

Como nos encontrar:

• Nosso Site
• GitHub
• LinkedIn

INFORMAÇÕES DE CONTATO — Se você tiver alguma dúvida sobre estes Termos ou Serviços, entre em contato conosco em

developers@leadsoft.inf.br.