Palmr/apps/docs/content/docs/3.1-beta/oidc-authentication/google.mdx

---
title: Google
icon: Chrome
---

Google is one of Palmr's officially supported OIDC providers, offering secure and reliable authentication through Google OAuth 2.0. This integration allows users to sign in to Palmr using their existing Google accounts, providing a seamless single sign-on experience.

{/* Imagem: Screenshot da tela de login do Palmr mostrando o botão "Sign in with Google" em destaque */}

## Why use Google authentication?

Google authentication provides several advantages for both administrators and users:

- **Seamless login experience** - Users can access Palmr with their existing Google accounts
- **Enhanced security** - Leverage Google's robust security infrastructure and two-factor authentication
- **Reduced password fatigue** - No need to create and remember additional passwords
- **Enterprise integration** - Perfect for organizations already using Google Workspace
- **Automatic user provisioning** - New users are created automatically upon first login

---

## Prerequisites

Before configuring Google authentication, ensure you have:

- **Google Cloud Console access** - Ability to create and manage projects
- **Admin privileges in Palmr** - Required to configure OIDC settings
- **Domain ownership** - For production deployments with custom domains

> **Note:** Google is pre-configured as an official provider in Palmr, which means the technical configuration is handled automatically. You only need to provide your OAuth credentials.

---

## Setting up Google Cloud Console

### Creating a Google Cloud project

To get started with Google authentication, you'll need to set up a project in Google Cloud Console.

1. **Navigate to Google Cloud Console**: Go to [console.cloud.google.com](https://console.cloud.google.com/)

{/* Imagem: Screenshot da página inicial do Google Cloud Console com a seleção de projeto em destaque */}

2. **Create or select a project**: Choose an existing project or create a new one for your Palmr installation

{/* Imagem: Modal de criação/seleção de projeto no Google Cloud Console, mostrando o botão "NEW PROJECT" */}

3. **Enable the project**: Ensure the project is active and selected

### Configuring OAuth consent screen

The OAuth consent screen is what users see when they authenticate with Google.

1. **Access OAuth consent screen**: Navigate to **APIs & Services** > **OAuth consent screen**

{/* Imagem: Menu lateral do Google Cloud Console com "APIs & Services" expandido e "OAuth consent screen" em destaque */}

2. **Choose user type**:
   - **Internal** - For Google Workspace organizations (users within your domain only)
   - **External** - For public use (any Google user can authenticate)

{/* Imagem: Tela de seleção do tipo de usuário (Internal vs External) no OAuth consent screen */}

3. **Fill required information**:
   - **Application name**: Enter a descriptive name like "Palmr File Sharing"
   - **User support email**: Provide a valid support email address
   - **Developer contact information**: Add your contact email for Google communications

{/* Imagem: Formulário do OAuth consent screen preenchido com os campos obrigatórios destacados */}

> **Tip:** For business use, choose "Internal" if you have Google Workspace. This restricts access to your organization's users and simplifies the approval process.

### Adding OAuth scopes

Configure the permissions your application will request from users.

1. **Navigate to Scopes**: In the OAuth consent screen configuration, find the **Scopes** section
2. **Add standard scopes**:
   - `openid` - Required for OpenID Connect
   - `profile` - Access to basic profile information
   - `email` - Access to user's email address

{/* Imagem: Seção de Scopes no OAuth consent screen com os scopes openid, profile e email adicionados */}

These scopes provide Palmr with the basic information needed to create and manage user accounts.

### Creating OAuth 2.0 credentials

Now you'll create the actual credentials that Palmr will use to authenticate with Google.

1. **Navigate to Credentials**: Go to **APIs & Services** > **Credentials**

{/* Imagem: Página de Credentials no Google Cloud Console vazia, pronta para criar novas credenciais */}

2. **Create OAuth client**: Click **+ CREATE CREDENTIALS** > **OAuth client ID**

{/* Imagem: Dropdown do botão "CREATE CREDENTIALS" com "OAuth client ID" em destaque */}

3. **Select application type**: Choose **Web application**

{/* Imagem: Formulário de criação de OAuth client ID com "Web application" selecionado */}

4. **Configure authorized URIs**:

   **For production:**

   ```
   https://yourdomain.com/api/auth/callback/google
   ```

   **For development:**

   ```
   http://localhost:3000/api/auth/callback/google
   ```

   **For custom ports:**

   ```
   https://yourdomain.com:5487/api/auth/callback/google
   ```

{/* Imagem: Campo "Authorized redirect URIs" preenchido com as URLs de callback do Palmr */}

5. **Create and save credentials**: Click **Create** and copy both the **Client ID** and **Client Secret**

{/* Imagem: Modal final mostrando o Client ID e Client Secret gerados, com botões de cópia em destaque */}

> **Important:** Replace `yourdomain.com` with your actual domain. You can add multiple URIs for different environments (development, staging, production).

---

## Configuring Palmr

### Accessing OIDC settings

To configure Google authentication in Palmr, you need administrator access to the settings panel.

1. **Login as administrator**: Sign in to Palmr with an admin account

{/* Imagem: Tela de login do Palmr com credenciais de administrador */}

2. **Access settings**: Click your profile picture in the header and select **Settings**

{/* Imagem: Menu dropdown do usuário no Palmr com a opção "Settings" em destaque */}

3. **Navigate to authentication**: Find and click on the **Authentication** or **OIDC** configuration section

{/* Imagem: Página de configurações do Palmr mostrando as diferentes seções, com Authentication/OIDC em destaque */}

### Enabling Google provider

Google comes pre-configured as an official provider, so the setup process is streamlined.

1. **Locate Google provider**: Find Google in the list of available providers

{/* Imagem: Lista de provedores OIDC no Palmr com o Google listado como provider oficial */}

2. **Enable the provider**: Toggle the status to **Enabled**

{/* Imagem: Card do provedor Google no Palmr com o toggle "Enabled" ativado */}

3. **Configure credentials**:
   - **Client ID**: Paste the Client ID from Google Cloud Console
   - **Client Secret**: Paste the Client Secret from Google Cloud Console

{/* Imagem: Formulário de configuração do Google provider no Palmr com os campos Client ID e Client Secret preenchidos */}

### Advanced configuration options

Configure additional settings to customize the authentication behavior:

**Auto Registration**: Enable this to automatically create user accounts when someone authenticates for the first time.

**Admin Email Domains**: Specify domains that should automatically receive admin privileges. For example, entering `yourcompany.com` will grant admin access to anyone with an email from that domain.

**Sort Order**: Control where the Google login button appears relative to other authentication providers.

{/* Imagem: Seção de configurações avançadas do Google provider mostrando Auto Registration, Admin Email Domains e Sort Order */}

> **Security consideration:** Be cautious with auto-registration and admin domains. Only enable these if you trust the user base or have domain restrictions in place.

---

## Technical configuration

Google's technical configuration is handled automatically, but understanding the setup can help with troubleshooting:

```yaml
Provider Type: OAuth 2.0 with OIDC Discovery
Issuer URL: https://accounts.google.com
Authorization Endpoint: /o/oauth2/v2/auth
Token Endpoint: /o/oauth2/token
UserInfo Endpoint: https://www.googleapis.com/oauth2/v3/userinfo
Scopes: openid profile email
Discovery: Enabled (/.well-known/openid_configuration)
```

### Field mappings

Palmr automatically maps Google user information to local user accounts:

- **User ID**: Maps from Google's `sub` field
- **Email**: Maps from Google's `email` field
- **Full Name**: Maps from Google's `name` field
- **First Name**: Maps from Google's `given_name` field
- **Last Name**: Maps from Google's `family_name` field
- **Avatar**: Maps from Google's `picture` field

---

## Testing the configuration

### Verifying the setup

After configuring Google authentication, test the integration to ensure everything works correctly.

1. **Check login page**: Navigate to your Palmr login page and verify the "Sign in with Google" button appears

{/* Imagem: Tela de login do Palmr mostrando o botão "Sign in with Google" visível e funcionando */}

2. **Test authentication flow**: Click the Google sign-in button and complete the authentication process

{/* Imagem: Fluxo de autenticação do Google mostrando a tela de login do Google após clicar no botão */}

3. **Verify user creation**: Confirm that a new user account is created (if auto-registration is enabled)

{/* Imagem: Dashboard administrativo do Palmr mostrando o novo usuário criado automaticamente via Google */}

4. **Check admin privileges**: If you configured admin domains, verify that users from those domains receive admin access

### Login flow verification

The complete authentication process should work as follows:

1. **User clicks "Sign in with Google"**: The browser redirects to Google's authentication page
2. **User authenticates with Google**: User enters their Google credentials or confirms existing session
3. **Google redirects back to Palmr**: User returns to Palmr with authentication tokens
4. **Palmr creates or updates user**: User account is automatically managed based on your configuration
5. **User accesses Palmr**: User is logged in and can use all features according to their permissions

{/* Imagem: Diagrama de fluxo visual mostrando o processo completo de autenticação Google -> Palmr */}

---

## Troubleshooting common issues

### Redirect URI mismatch error

**Error message**: `Error 400: redirect_uri_mismatch`

{/* Imagem: Screenshot do erro "redirect_uri_mismatch" no browser durante tentativa de login */}

**Cause**: The redirect URI in your request doesn't match what's configured in Google Cloud Console.

**Solution**:

1. Check the exact URL in the error message
2. Add this exact URL to your Google Cloud Console credentials
3. Ensure you include the correct protocol (http/https) and port
4. Remove any trailing slashes unless they're in the error message

### Access denied error

**Error message**: `Error 403: access_denied`

{/* Imagem: Screenshot do erro "access_denied" na tela de OAuth do Google */}

**Cause**: User denied permissions or the OAuth consent screen isn't properly configured.

**Solution**:

1. Verify the OAuth consent screen is published (for External user type)
2. Check that required scopes are correctly configured
3. For Internal applications, ensure the user belongs to your Google Workspace organization
4. Review and simplify the permissions you're requesting

### Invalid client error

**Error message**: `Error 401: invalid_client`

{/* Imagem: Screenshot do erro "invalid_client" durante tentativa de autenticação */}

**Cause**: Incorrect Client ID or Client Secret.

**Solution**:

1. Double-check that you've copied the credentials correctly from Google Cloud Console
2. Ensure there are no extra spaces or characters in the credentials
3. Regenerate credentials if necessary
4. Verify you're using the correct project in Google Cloud Console

### Users not receiving admin privileges

**Cause**: Email domain not properly configured in Palmr settings.

{/* Imagem: Configuração de Admin Email Domains no Palmr com exemplo de domínio configurado */}

**Solution**:

1. Verify the admin domain configuration in Palmr settings
2. Check that the user's email domain exactly matches the configured domain
3. Ensure the domain format is correct (e.g., `company.com`, not `@company.com`)
4. Manually promote users through the admin interface if needed

### Discovery endpoint issues

**Cause**: Network connectivity problems or DNS resolution issues.

**Solution**:

1. Test the discovery endpoint manually: `https://accounts.google.com/.well-known/openid_configuration`
2. Check server firewall and network connectivity
3. Verify DNS resolution from your server
4. Consider proxy or CDN configurations that might block the request

---

## Security best practices

### Credential management

- **Never expose secrets**: Keep your Client Secret secure and never commit it to version control
- **Rotate credentials regularly**: Generate new credentials periodically for enhanced security
- **Use environment variables**: Store sensitive configuration in environment variables, not config files
- **Monitor access logs**: Regularly review authentication logs for suspicious activity

### Domain and user restrictions

- **Limit admin domains**: Only add trusted domains to the admin list
- **Review auto-registration**: Consider disabling auto-registration if you need manual user approval
- **Use Internal OAuth**: For organizations with Google Workspace, use Internal OAuth consent screen
- **Regular access reviews**: Periodically review user access and remove inactive accounts

### Production considerations

- **Use HTTPS**: Always use HTTPS in production environments
- **Configure proper domains**: Use production domains in Google Cloud Console
- **Test thoroughly**: Verify the complete authentication flow before going live
- **Plan for failures**: Have fallback authentication methods available

---

## Example configurations

### Basic setup

For a simple Palmr installation with Google authentication:

```yaml
Google Cloud Console:
  Project: palmr-production
  OAuth Consent: External
  Scopes: openid, profile, email
  Authorized URIs: https://files.yourcompany.com/api/auth/callback/google

Palmr Configuration:
  Provider: Google (Enabled)
  Auto Register: Yes
  Admin Domains: yourcompany.com
  Client ID: 123456789-abcdefghijklmnop.apps.googleusercontent.com
  Client Secret: GOCSPX-xxxxxxxxxxxxxxxxxxxxxxxx
```

{/* Imagem: Comparação lado a lado das configurações no Google Cloud Console e no Palmr para setup básico */}

### Enterprise setup

For Google Workspace organizations:

```yaml
Google Cloud Console:
  Project: yourcompany-palmr
  OAuth Consent: Internal
  Scopes: openid, profile, email
  Authorized URIs:
    - https://palmr.yourcompany.com/api/auth/callback/google
    - https://files.yourcompany.com/api/auth/callback/google

Palmr Configuration:
  Provider: Google (Enabled)
  Auto Register: Yes
  Admin Domains: yourcompany.com, admin.yourcompany.com
  Client ID: 987654321-zyxwvutsrqponmlk.apps.googleusercontent.com
  Client Secret: GOCSPX-yyyyyyyyyyyyyyyyyyyyyyyy
```

{/* Imagem: Configuração enterprise completa mostrando múltiplos domínios e URIs autorizadas */}

---

## Next steps

With Google authentication configured, you might want to:

- **Configure additional providers**: Set up other OIDC providers for more authentication options
- **Customize user management**: Fine-tune auto-registration and admin assignment rules
- **Review security settings**: Ensure your authentication setup meets your security requirements
- **Monitor usage**: Keep track of authentication patterns and user activity

For more information about OIDC authentication in Palmr, see the [OIDC Authentication overview](/docs/3.1-beta/oidc-authentication).

## Useful resources

- [Google Identity Platform Documentation](https://developers.google.com/identity)
- [OAuth 2.0 for Web Server Applications](https://developers.google.com/identity/protocols/oauth2/web-server)
- [OpenID Connect](https://developers.google.com/identity/protocols/oauth2/openid-connect)
- [Google Cloud Console](https://console.cloud.google.com/apis/credentials)