> For the complete documentation index, see [llms.txt](https://wiki.datadike.com/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://wiki.datadike.com/pt/pam/administration/identities/sso-google-workspace.md).

# Single sign-on com o Google Workspace

Permita que os usuários entrem no console com a conta do Google Workspace, por meio de um app SAML personalizado no Google Admin e do método SAML2 daqui.

## O que é isto e quando usar

Esta página liga o console ao Google Workspace por SAML 2.0. O Google é o provedor de identidade (IdP): é ele que confirma quem é a pessoa. A solução é o provedor de serviços (SP): confia nessa confirmação e abre a sessão. Concluída a configuração, a tela de login passa a mostrar um botão **SAML2**, e os usuários entram com a conta Google da empresa, sem senha local.

**A ordem importa.** Os metadados do provedor de serviços, de que o Google precisa, só existem depois que a chave e o certificado são salvos aqui. Por isso a configuração vai e volta entre os dois lados:

1. Gerar a chave e o certificado do provedor de serviços.
2. Salvá-los na aba **SAML2** daqui.
3. Ler o Entity ID e a URL do ACS nos metadados do provedor de serviços.
4. Criar o app no Google Admin com esses valores e baixar os metadados do Google.
5. Voltar aqui, colar os metadados do Google e ajustar o mapa de atributos e as configurações avançadas.
6. Liberar o acesso dos usuários no Google e testar.

O que passa de um lado para o outro:

| Valor                             | De onde vem                                                                       | Para onde vai                                    |
| --------------------------------- | --------------------------------------------------------------------------------- | ------------------------------------------------ |
| Metadados do IdP do Google (XML)  | Google Admin, **FAZER O DOWNLOAD DOS METADADOS**                                  | **IDP Metadata XML** aqui                        |
| URL do ACS                        | Metadados do provedor de serviços daqui, `Location` de `AssertionConsumerService` | **URL do ACS** no Google                         |
| Entity ID                         | Metadados do provedor de serviços daqui, `entityID`                               | **ID da entidade** no Google                     |
| Chave privada e certificado do SP | Você os gera                                                                      | Só aqui                                          |
| Nomes dos atributos               | **Mapeamento de atributos** no Google                                             | Chaves de **Mapear atributos dos usuários** aqui |

Para o funcionamento geral do single sign-on, consulte [Single sign-on](https://wiki.datadike.com/pt/pam/administration/identities/sso.md).

## Antes de começar

* A função **SYSADMIN**.
* Uma conta de superadministrador do Google Workspace para o Google Admin (`admin.google.com`).
* O endereço público desta instalação, por exemplo `https://pam.contoso.example`.
* O OpenSSL, no Linux, no macOS ou no Git Bash do Windows.
* Um login local de administrador que continue funcionando sem SSO. Não torne o SSO a única forma de entrar antes de testá-lo com vários usuários.

## Passos

### 1. Gerar a chave e o certificado do provedor de serviços

```bash
openssl req -x509 -newkey rsa:2048 -nodes -days 3650 \
  -keyout sp.key -out sp.crt \
  -subj "/O=Contoso/CN=pam.contoso.example"
```

Use o hostname da instalação no `CN`. O comando grava `sp.key` e `sp.crt`, válidos por dez anos. Confira que os dois existem com `ls -l sp.key sp.crt`. A chave privada fica só com esta instalação e nunca é enviada ao Google.

{% hint style="info" %}
No Git Bash do Windows, o shell reescreve argumentos que começam com `/`, o que estraga o `-subj`. Coloque `MSYS_NO_PATHCONV=1` na frente do comando. Cole com o botão direito do mouse ou com **Shift+Insert**, e não com **Ctrl+V**, que pode levar caracteres invisíveis junto.
{% endhint %}

### 2. Salvar a chave e o certificado aqui

1. Abra **Configurações do Sistema › Autenticações** e selecione a aba **SAML2**.
2. Ative **SAML2**.
3. Em **Chave SP**, informe o conteúdo de `sp.key`.
4. Em **Certificado SP**, informe o conteúdo de `sp.crt`.
5. Clique em **Salvar**.

Os metadados do provedor de serviços só ficam disponíveis depois deste salvamento. Abertos antes, devolvem um erro dizendo que a chave privada ou o certificado do SP não foi encontrado.

### 3. Ler o Entity ID e a URL do ACS

1. Abra os metadados do provedor de serviços no endereço `https://<your-server>/core/auth/saml2/metadata/`.
2. Copie o atributo `entityID` do elemento raiz. Esse é o **Entity ID**.
3. Copie o atributo `Location` do elemento `AssertionConsumerService`. Essa é a **URL do ACS**, e ela termina em `/saml2/callback/`.

Copie os dois valores do XML da sua instalação, nunca de um exemplo. Um proxy reverso ou um prefixo de caminho a mais os altera, e um Entity ID diferente em um único caractere é o que produz `Invalid audience` mais adiante.

### 4. Criar o app SAML personalizado no Google

Logado como superadministrador, abra **Apps › Apps da Web e para dispositivos móveis › Adicionar app › Adicionar app SAML personalizado** ("Apps › Web and mobile apps › Add app › Add custom SAML app").

1. Informe um nome para o app, por exemplo `DataDike PAM`, e clique em **Continuar**.
2. Em **Detalhes do provedor de identidade do Google** ("Google Identity Provider details"), clique em **FAZER O DOWNLOAD DOS METADADOS** ("DOWNLOAD METADATA") e guarde o arquivo XML. Clique em **Continuar**.
3. Em **Detalhes do provedor de serviços** ("Service provider details"), preencha:

   | Campo                                    | Valor                                                                            |
   | ---------------------------------------- | -------------------------------------------------------------------------------- |
   | URL do ACS ("ACS URL")                   | O `Location` do passo 3, terminado em `/saml2/callback/`                         |
   | ID da entidade ("Entity ID")             | O `entityID` do passo 3                                                          |
   | URL de início ("Start URL")              | Em branco                                                                        |
   | Resposta assinada ("Signed response")    | Marcado                                                                          |
   | Formato do ID do nome ("Name ID format") | `EMAIL`                                                                          |
   | ID do nome ("Name ID")                   | **Informações básicas › E-mail principal** ("Basic Information › Primary email") |
4. Em **Mapeamento de atributos** ("Attribute mapping"), crie estes mapeamentos. Sem eles, a asserção leva só o ID do nome, nenhum nome de usuário chega deste lado e o login falha.

   | Atributo do diretório do Google    | Atributo do app |
   | ---------------------------------- | --------------- |
   | E-mail principal ("Primary email") | `username`      |
   | E-mail principal ("Primary email") | `email`         |
   | Nome ("First name")                | `name`          |
5. Clique em **Concluir** ("Finish").

### 5. Liberar o acesso dos usuários no Google

1. Abra **Apps › Apps da Web e para dispositivos móveis** e selecione o app.
2. Abra **Acesso do usuário** ("User access"), escolha **ATIVADO para todos** ("ON for everyone") ou ative para a unidade organizacional que vai usá-lo, e clique em **Salvar**.

Sem isso, o Google recusa o login com `app_not_enabled_for_user`. A mudança pode levar alguns minutos para se propagar.

### 6. Concluir a configuração aqui

De volta à aba **SAML2**:

1. Em **IDP Metadata XML**, cole o conteúdo inteiro do arquivo baixado no passo 4.
2. Deixe **Endereço do IDP Metadata** em branco. Um app SAML personalizado do Google não publica uma URL de metadados estável e, quando **Endereço do IDP Metadata** está preenchido, ele tem prioridade sobre o XML.
3. Em **Mapear atributos dos usuários**, ligue os atributos do app nomeados no Google aos campos de usuário daqui:

   ```json
   {
     "username": "username",
     "email": "email",
     "name": "name"
   }
   ```

   No SAML2, a chave é o nome do atributo que o IdP envia e o valor é o campo daqui. Só `username`, `name`, `email`, `comment`, `phone` e `groups` são lidos; qualquer outro atributo é ignorado.
4. Em **Configurações avançadas**, informe o JSON abaixo. O Google assina a asserção, não a criptografa e ignora pedidos de autenticação assinados:

   ```json
   {
     "organization": {
       "en": {
         "name": "DataDike",
         "displayname": "DataDike",
         "url": "https://datadike.com/"
       }
     },
     "strict": true,
     "security": {
       "authnRequestsSigned": false,
       "wantAssertionsSigned": true,
       "wantAssertionsEncrypted": false,
       "wantMessagesSigned": false,
       "wantNameId": true,
       "requestedAuthnContext": false
     }
   }
   ```

   A chave dentro de `en` é `url`, e não `uri`. As configurações são validadas contra o esquema SAML, e uma configuração com `uri` é rejeitada.
5. Marque **Sempre atualizar dados do usuário**, para que nome e e-mail sejam atualizados a cada login.
6. Decida sobre **Sincronizar logout**. Marcado, sair daqui também desconecta o usuário do Google. Se as pessoas mantêm o Gmail aberto no mesmo navegador, desmarque, ou sair do console as desconecta do Gmail junto.
7. Em **Organização**, escolha a organização em que os novos usuários são criados.
8. Clique em **Salvar**.

## O que você deve ver

A tela de login mostra um botão **SAML2** ao lado do formulário de login local.

## Como verificar se funcionou

1. Confirme que os metadados são servidos com o seu certificado:

   ```bash
   curl -s https://<your-server>/core/auth/saml2/metadata/
   ```

   A resposta precisa ser um XML cujo `X509Certificate` coincide com o `sp.crt`, e não uma página de erro.
2. Em uma janela anônima, abra a página de login e clique em **SAML2**. Você deve ser levado ao Google, autenticar-se lá e voltar já logado.
3. Abra **Usuários › Usuários** e localize esse usuário. A coluna **Origem** precisa mostrar SAML2, e não `Local`, o nome de usuário precisa ser o endereço de e-mail e **E-mail** precisa estar preenchido.
4. Tente uma conta de uma unidade organizacional sem acesso ao app. O Google precisa recusá-la.
5. Saia e confirme que o comportamento corresponde à sua escolha em **Sincronizar logout**.

## Erros comuns

Os erros de autenticação ficam registrados no log do serviço core da instalação.

| Sintoma                                                                                        | Causa                                                                                                                | Solução                                                                                   |
| ---------------------------------------------------------------------------------------------- | -------------------------------------------------------------------------------------------------------------------- | ----------------------------------------------------------------------------------------- |
| `Invalid audience` no log                                                                      | O **ID da entidade** no Google não é idêntico ao `entityID` dos metadados do provedor de serviços                    | Copie de novo para o Google o `entityID` dos metadados desta instalação                   |
| O Google mostra `app_not_enabled_for_user`                                                     | O **Acesso do usuário** está desativado para a unidade organizacional do usuário, ou a mudança ainda não se propagou | Ative o acesso, salve e aguarde alguns minutos                                            |
| O Google aceita a conta, mas o login aqui falha                                                | O **Mapeamento de atributos** no Google não foi salvo, então nenhum `username` chega                                 | Refaça o passo 4.4 e confirme que o Google salvou os mapeamentos                          |
| O usuário fica sem nome ou e-mail                                                              | As chaves de **Mapear atributos dos usuários** não coincidem com os nomes dos atributos do app no Google             | Deixe as chaves idênticas aos nomes digitados no Google                                   |
| O endereço dos metadados devolve um erro sobre a chave privada ou o certificado do SP          | A chave e o certificado não foram salvos                                                                             | Faça o passo 2 e clique em **Salvar** primeiro                                            |
| O XML colado parece ser ignorado                                                               | **Endereço do IDP Metadata** está preenchido e tem prioridade                                                        | Esvazie o **Endereço do IDP Metadata**                                                    |
| **Configurações avançadas** é rejeitado                                                        | O JSON usa `uri` em vez de `url`                                                                                     | Troque a chave para `url`                                                                 |
| Uma mensagem pede para verificar se já existe um usuário com o mesmo nome de usuário ou e-mail | Um usuário local já tem esse e-mail com outro nome de usuário                                                        | Alinhe o nome de usuário do cadastro existente ao e-mail do Google, ou remova a duplicata |
| Sair do console também desconecta o usuário do Gmail                                           | **Sincronizar logout** está marcado                                                                                  | Desmarque                                                                                 |
| O `-subj` sai estragado no Windows                                                             | Conversão de caminhos do Git Bash                                                                                    | Coloque `MSYS_NO_PATHCONV=1` na frente do comando                                         |

## Referência de campos

Valores para o Google Workspace na aba **SAML2**:

| Campo                             | Valor para o Google Workspace                                                |
| --------------------------------- | ---------------------------------------------------------------------------- |
| SAML2                             | Ativado                                                                      |
| Endereço do IDP Metadata          | Em branco                                                                    |
| IDP Metadata XML                  | O XML de **FAZER O DOWNLOAD DOS METADADOS**                                  |
| Chave SP                          | Conteúdo de `sp.key`                                                         |
| Certificado SP                    | Conteúdo de `sp.crt`                                                         |
| Configurações avançadas           | O JSON do passo 6                                                            |
| Mapear atributos dos usuários     | Mapa dos nomes de atributo do app no Google para `username`, `email`, `name` |
| Sempre atualizar dados do usuário | Ativado                                                                      |
| Sincronizar logout                | Desativado se os usuários mantêm o Gmail aberto no mesmo navegador           |
| Organização                       | A organização em que os novos usuários são criados                           |

## Páginas relacionadas

* [Single sign-on](https://wiki.datadike.com/pt/pam/administration/identities/sso.md): métodos, URLs de serviço e mapeamento de atributos
* [Single sign-on com o Microsoft Entra ID](https://wiki.datadike.com/pt/pam/administration/identities/sso-entra-id.md): o mesmo resultado por OIDC
* [Usuários e grupos](https://wiki.datadike.com/pt/pam/administration/identities/users-and-groups.md): os cadastros que o SSO cria
* [Autenticação multifator](https://wiki.datadike.com/pt/pam/administration/identities/mfa.md): um segundo fator aqui, ou delegado ao Google
