# GitBook com Google Workspace

## Overview

<details>

<summary>Objetivo</summary>

Implementar acesso ao GitBook com autenticação pelo **Google Workspace** da Rise.

O time entra com e-mail corporativo.

Quem não é da Rise fica bloqueado.

</details>

<details>

<summary>Quando usar</summary>

Use este playbook quando o GitBook precisar ficar:

* fechado para público externo
* aberto apenas para contas corporativas
* em modo leitura para a maior parte do time
* com edição restrita a poucos responsáveis

</details>

<details>

<summary>Resultado esperado</summary>

Ao abrir o link do site:

* o usuário faz login com Google corporativo
* contas pessoais não entram
* o time abre o conteúdo em consulta
* só editores entram no ambiente de edição

</details>

<details>

<summary>Responsáveis</summary>

* **Owner:** Tech Lead
* **Aprovador:** CEO/CTO
* **Consultados:** Head de Operações
* **Informados:** líderes de área e time interno

</details>

## Decisão de arquitetura

### Padrão recomendado

Usar **Authenticated access** no site publicado.

Usar **Google** como backend, se a opção existir no GitBook.

Se não existir, usar **OIDC com Google Workspace**.

### O que não usar

Não usar **Custom** sem um fluxo próprio de autenticação já pronto.

Esse modo exige login externo, emissão de token e callback funcionando.

Sem isso, o site bloqueia com erro de autenticação.

{% hint style="warning" %}
O link publicado sozinho não deve liberar acesso.

A proteção real vem do login corporativo e das permissões corretas.
{% endhint %}

## Pré-requisitos

Antes de começar, confirmar:

* domínio corporativo ativo no Google Workspace
* acesso administrativo ao **Google Cloud Console**
* acesso administrativo ao **GitBook Site Settings**
* lista de quem será **Editor** e quem será apenas **Reader**
* 2FA obrigatório nas contas corporativas

## Implementação

{% stepper %}
{% step %}

### Definir a política de acesso

Fechar as decisões antes da configuração.

Definir:

* quem pode editar
* quem pode apenas ler
* se o acesso será por domínio inteiro ou por grupo específico

**Recomendação:**

* **Editors:** líderes e responsáveis por documentação
* **Readers:** restante do time

Se quiser mais controle, usar grupos como:

* `docs-editors@risefinance.com.br`
* `docs-readers@risefinance.com.br`
  {% endstep %}

{% step %}

### Preparar o app de login no Google

No **Google Cloud Console**:

1. Abrir **APIs & Services → Credentials**.
2. Clicar em **Create credentials → OAuth client ID**.
3. Escolher **Web application**.
4. Dar um nome claro. Exemplo: `GitBook Internal Docs`.
5. Adicionar a **Authorized redirect URI** exatamente como o GitBook informar.
6. Salvar.
7. Copiar:
   * `Client ID`
   * `Client Secret`

Se o projeto pedir consentimento OAuth, configurar antes a tela de consentimento.

Usar escopo mínimo:

* `openid`
* `email`
* `profile`
  {% endstep %}

{% step %}

### Configurar o backend no GitBook

No **GitBook → Site Settings → Audience**:

1. Manter **Authenticated access**.
2. Em **Authentication backend**:
   * escolher **Google**, se existir
   * senão escolher **OIDC**
3. Preencher os campos do provedor.

#### Valores padrão do Google para OIDC

* **Issuer URL:** `https://accounts.google.com`
* **Authorization endpoint:** `https://accounts.google.com/o/oauth2/v2/auth`
* **Token endpoint:** `https://oauth2.googleapis.com/token`
* **Userinfo endpoint:** `https://openidconnect.googleapis.com/v1/userinfo`
* **Scopes:** `openid email profile`

Se o GitBook pedir URL de chaves públicas, usar a URL oficial do Google informada pelo provedor.

Salvar a configuração.
{% endstep %}

{% step %}

### Restringir ao domínio corporativo

Garantir que só contas da Rise possam autenticar.

Aplicar a restrição para:

* `@risefinance.com.br`

Se houver opção de domínio permitido, preencher apenas o domínio corporativo.

Se a restrição for por grupo, usar apenas os grupos internos aprovados.
{% endstep %}

{% step %}

### Ajustar permissões no GitBook

Autenticação e permissão são coisas diferentes.

Depois do login corporativo, ajustar os papéis:

* **Editor** para quem mantém a documentação
* **Reader** para quem só consulta

Revisar a lista atual de membros.

Remover papel de editor de quem não precisa editar.
{% endstep %}

{% step %}

### Validar em ambiente real

Fazer os testes abaixo antes de comunicar o time.

#### Teste 1 — conta corporativa autorizada

Resultado esperado:

* login bem-sucedido
* acesso ao site publicado
* conteúdo abre em leitura

#### Teste 2 — conta pessoal

Resultado esperado:

* acesso negado

#### Teste 3 — link vazado para terceiro

Resultado esperado:

* sem login corporativo, não abre

#### Teste 4 — usuário editor

Resultado esperado:

* consegue editar quando entra pelo ambiente interno

#### Teste 5 — usuário reader

Resultado esperado:

* não vê modo de edição no uso normal do site publicado
  {% endstep %}

{% step %}

### Publicar e comunicar

Depois da validação:

1. confirmar que o site está publicado
2. compartilhar o link oficial com o time
3. enviar instruções curtas de acesso
4. orientar uso do e-mail corporativo
5. orientar o time a usar aba anônima no primeiro teste, se necessário
   {% endstep %}
   {% endstepper %}

## Checklist de aceite

A implementação só pode ser considerada pronta quando:

* o site exige login Google corporativo
* contas pessoais são bloqueadas
* o link publicado não abre para terceiros
* leitores acessam em consulta
* editores seguem com acesso de edição
* o erro **Authentication missing to access this content** deixa de ocorrer no fluxo correto

## Troubleshooting

<details>

<summary>O site mostra “Authentication missing to access this content”</summary>

Checar:

* backend ainda está em **Custom**
* callback do OAuth está incorreto
* `Client ID` ou `Client Secret` estão errados
* configuração OIDC não foi salva

</details>

<details>

<summary>O usuário entra, mas cai na edição</summary>

Checar:

* ele está como **Editor** ou membro com permissão alta
* o link enviado foi o do ambiente interno, não o publicado

</details>

<details>

<summary>Conta pessoal consegue entrar</summary>

Checar:

* restrição por domínio não foi aplicada
* grupo autorizado aceita e-mails fora do domínio
* a autenticação está validando identidade, mas não está filtrando domínio

</details>

<details>

<summary>O login Google funciona, mas o acesso continua negado</summary>

Checar:

* se o usuário está no domínio correto
* se o usuário faz parte do grupo permitido, quando houver grupo
* se a política do site permite visitantes autenticados

</details>

## Segurança e operação contínua

### Boas práticas

* manter **2FA obrigatório** no Google Workspace
* não usar contas pessoais para acesso interno
* revisar editores a cada trimestre
* registrar mudanças de acesso em canal oficial
* preferir grupos em vez de liberar usuários soltos

### Revisão periódica

Revisar trimestralmente:

* lista de editores
* grupos autorizados
* contas desligadas
* funcionamento do login

## Rollback

Se a nova autenticação falhar em produção:

1. reverter a alteração do backend
2. restaurar o último método estável
3. validar acesso do time crítico
4. corrigir a configuração antes de nova tentativa

{% hint style="info" %}
Fazer a primeira ativação em janela controlada.

Validar com 2 ou 3 usuários reais antes de comunicar toda a empresa.
{% endhint %}

## Brief pronto para abrir com o Tech Lead

Use este texto na abertura da demanda:

> Precisamos proteger o GitBook interno com autenticação via **Google Workspace**. Objetivo: permitir acesso apenas para contas `@risefinance.com.br`, manter o time em modo leitura no site publicado e restringir edição a poucos responsáveis. Implementação esperada: substituir o backend **Custom** por **Google** ou **OIDC com Google Workspace**, validar domínio corporativo, ajustar papéis de Reader e Editor e executar testes com conta corporativa e conta pessoal. Critério de aceite: link publicado só abre com login corporativo, conta pessoal não entra e leitores não caem no modo de edição.

## Entregáveis esperados do Tech Lead

Ao fim da implementação, pedir:

* print ou gravação curta do login funcionando
* confirmação do backend configurado
* confirmação da restrição ao domínio corporativo
* lista final de editores
* resultado dos testes de aceite


---

# Agent Instructions: Querying This Documentation

If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question.

Perform an HTTP GET request on the current page URL with the `ask` query parameter:

```
GET https://rise-finance-2.gitbook.io/internal/playbook/ferramentas-and-acessos/gitbook-com-google-workspace.md?ask=<question>
```

The question should be specific, self-contained, and written in natural language.
The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.