LeadSoft.Adapter.Google.Workspace 10.0.5

← 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).
• 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<DTOGoogleUserExpandedResponse?> GetUserProfileAsync(string accessToken, CancellationToken cancellationToken = default)

  • Consulta o perfil detalhado do usuário autenticado via Google People API.
  • Retorna dados como telefone e data de nascimento, quando disponíveis.
  • Retorna null em caso de falha — erros são registrados em log, sem lançar exceções ao chamador.

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);
    }
}

DTOs de retorno

DTOGoogleUserResponse — GetOAuthSSOAsync

DTOGoogleUserExpandedResponse — GetUserProfileAsync

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 nunca lança exceção — erros são registrados no log e retorna null.

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 GetOAuthSSOAsync para fluxos de login simples — é mais rápido e não requer um Access Token separado.

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.