Autenticação SSO e OAuth

Configure Google OAuth, GitHub OAuth e OIDC genérico no Potato. Restrinja o acesso por domínio de e-mail ou organização do GitHub e habilite login em modo misto com senhas.

Novo na v2.3.0

Por padrão, o Potato usa um login simples baseado em nome de usuário, no qual os anotadores digitam qualquer nome de usuário para entrar. Isso é conveniente para desenvolvimento local e projetos pequenos, mas implantações em produção precisam de autenticação adequada para evitar acessos não autorizados, garantir a identidade dos anotadores e atender a requisitos institucionais.

O Potato 2.3 adiciona suporte a três métodos de autenticação:

Google OAuth -- entre com contas Google, com restrição opcional por domínio
GitHub OAuth -- entre com contas GitHub, com restrição opcional por organização
OIDC genérico -- conecte-se a qualquer provedor OpenID Connect (Okta, Azure AD, Auth0, Keycloak, etc.)

Todos os métodos podem ser combinados com o login por nome de usuário existente do Potato para uma configuração em modo misto.

Google OAuth

Pré-requisitos

Crie um projeto no Google Cloud Console
Habilite a API "Google Identity"
Crie credenciais OAuth 2.0 (tipo Aplicação Web)
Adicione a URL do seu servidor Potato em "URIs de redirecionamento autorizados": https://your-server.com/auth/google/callback

Configuração

yaml

authentication:
  method: google_oauth
 
  google_oauth:
    client_id: ${GOOGLE_CLIENT_ID}
    client_secret: ${GOOGLE_CLIENT_SECRET}
    redirect_uri: "https://your-server.com/auth/google/callback"
 
    # Optional: restrict to specific domain(s)
    allowed_domains:
      - "umich.edu"
      - "research-lab.org"
 
    # Optional: auto-register new users on first login
    auto_register: true
 
    # Optional: map Google profile fields to Potato user fields
    field_mapping:
      username: email            # use email as Potato username
      display_name: name         # show Google display name

Restrição de Domínio

Quando allowed_domains está definido, apenas usuários com endereços de e-mail desses domínios podem entrar. Os demais veem uma mensagem de erro:

yaml

authentication:
  method: google_oauth
  google_oauth:
    client_id: ${GOOGLE_CLIENT_ID}
    client_secret: ${GOOGLE_CLIENT_SECRET}
    allowed_domains:
      - "umich.edu"
    domain_error_message: "This annotation task is restricted to University of Michigan accounts."

GitHub OAuth

Pré-requisitos

Vá em Configurações do GitHub > Developer settings > OAuth Apps > New OAuth App
Defina "Authorization callback URL" como https://your-server.com/auth/github/callback
Anote seu Client ID e gere um Client Secret

Configuração

yaml

authentication:
  method: github_oauth
 
  github_oauth:
    client_id: ${GITHUB_CLIENT_ID}
    client_secret: ${GITHUB_CLIENT_SECRET}
    redirect_uri: "https://your-server.com/auth/github/callback"
 
    # Optional: restrict to members of specific GitHub organizations
    allowed_organizations:
      - "my-research-lab"
      - "university-nlp-group"
 
    # Optional: restrict to specific teams within an organization
    allowed_teams:
      - "my-research-lab/annotators"
 
    # Scopes to request
    scopes:
      - "read:user"
      - "read:org"             # needed for organization restriction
 
    auto_register: true
 
    field_mapping:
      username: login            # GitHub username
      display_name: name

Restrição por Organização

O GitHub OAuth pode restringir o acesso a membros de organizações específicas. Isso requer o escopo read:org:

yaml

authentication:
  method: github_oauth
  github_oauth:
    client_id: ${GITHUB_CLIENT_ID}
    client_secret: ${GITHUB_CLIENT_SECRET}
    allowed_organizations:
      - "my-research-lab"
    scopes:
      - "read:user"
      - "read:org"
    org_error_message: "You must be a member of the my-research-lab GitHub organization."

OIDC genérico

Para provedores SSO corporativos (Okta, Azure AD, Auth0, Keycloak, etc.), use a integração genérica de OpenID Connect.

Configuração

yaml

authentication:
  method: oidc
 
  oidc:
    # Discovery URL (provider's .well-known endpoint)
    discovery_url: "https://accounts.example.com/.well-known/openid-configuration"
 
    # Or specify endpoints manually
    # authorization_endpoint: "https://accounts.example.com/authorize"
    # token_endpoint: "https://accounts.example.com/token"
    # userinfo_endpoint: "https://accounts.example.com/userinfo"
    # jwks_uri: "https://accounts.example.com/.well-known/jwks.json"
 
    client_id: ${OIDC_CLIENT_ID}
    client_secret: ${OIDC_CLIENT_SECRET}
    redirect_uri: "https://your-server.com/auth/oidc/callback"
 
    scopes:
      - "openid"
      - "profile"
      - "email"
 
    auto_register: true
 
    field_mapping:
      username: preferred_username
      display_name: name
      email: email

Exemplo com Azure AD

yaml

authentication:
  method: oidc
 
  oidc:
    discovery_url: "https://login.microsoftonline.com/${AZURE_TENANT_ID}/v2.0/.well-known/openid-configuration"
    client_id: ${AZURE_CLIENT_ID}
    client_secret: ${AZURE_CLIENT_SECRET}
    redirect_uri: "https://your-server.com/auth/oidc/callback"
    scopes:
      - "openid"
      - "profile"
      - "email"
    auto_register: true
    field_mapping:
      username: preferred_username
      display_name: name

Exemplo com Okta

yaml

authentication:
  method: oidc
 
  oidc:
    discovery_url: "https://your-org.okta.com/.well-known/openid-configuration"
    client_id: ${OKTA_CLIENT_ID}
    client_secret: ${OKTA_CLIENT_SECRET}
    redirect_uri: "https://your-server.com/auth/oidc/callback"
    scopes:
      - "openid"
      - "profile"
      - "email"
      - "groups"               # request group membership
    auto_register: true
 
    # Restrict to specific groups
    allowed_groups:
      - "annotation-team"
 
    field_mapping:
      username: preferred_username
      display_name: name
      groups: groups

Exemplo com Keycloak

yaml

authentication:
  method: oidc
 
  oidc:
    discovery_url: "https://keycloak.example.com/realms/annotation/.well-known/openid-configuration"
    client_id: ${KEYCLOAK_CLIENT_ID}
    client_secret: ${KEYCLOAK_CLIENT_SECRET}
    redirect_uri: "https://your-server.com/auth/oidc/callback"
    scopes:
      - "openid"
      - "profile"
      - "email"
    auto_register: true
    field_mapping:
      username: preferred_username
      display_name: name

Restrição de Domínio

Todos os métodos OAuth oferecem suporte à restrição de domínio com base nos endereços de e-mail. Isso é útil quando você quer permitir qualquer conta de uma instituição específica:

yaml

authentication:
  method: google_oauth          # or github_oauth, oidc
 
  domain_restriction:
    enabled: true
    allowed_domains:
      - "umich.edu"
      - "stanford.edu"
    error_message: "Access is restricted to university accounts."

Para provedores OIDC que incluem uma declaração email, a restrição de domínio funciona automaticamente. Para provedores que não incluem o e-mail, talvez seja necessário solicitar o escopo email explicitamente.

Registro Automático

Por padrão, os usuários precisam ser pré-registrados no Potato antes de poderem anotar. Com auto_register: true, qualquer usuário que se autenticar com sucesso é criado automaticamente no Potato no primeiro login.

yaml

authentication:
  auto_register: true
  auto_register_role: annotator   # annotator or admin

Para pré-aprovar usuários específicos e bloquear os demais:

yaml

authentication:
  auto_register: false
  allowed_users:
    - "researcher@umich.edu"
    - "student1@umich.edu"
    - "student2@umich.edu"
  user_not_found_message: "Your account has not been approved. Contact the project administrator."

Modo Misto

Você pode habilitar vários métodos de autenticação ao mesmo tempo. A página de login mostra botões para cada método habilitado, além de um campo opcional de nome de usuário.

yaml

authentication:
  methods:
    - google_oauth
    - github_oauth
    - username                   # keep simple username login as fallback
 
  google_oauth:
    client_id: ${GOOGLE_CLIENT_ID}
    client_secret: ${GOOGLE_CLIENT_SECRET}
    redirect_uri: "https://your-server.com/auth/google/callback"
 
  github_oauth:
    client_id: ${GITHUB_CLIENT_ID}
    client_secret: ${GITHUB_CLIENT_SECRET}
    redirect_uri: "https://your-server.com/auth/github/callback"
 
  # Username login settings
  username:
    enabled: true
    require_password: true       # require a password for username login
    password_file: "auth/passwords.yaml"

O modo misto é útil durante a migração: habilite o OAuth junto com o login por nome de usuário e, depois, desative o login por nome de usuário quando todos os anotadores tiverem vinculado suas contas OAuth.

Gerenciamento de Sessão

Configure o comportamento da sessão para usuários autenticados:

yaml

authentication:
  session:
    lifetime_hours: 24           # session duration
    refresh: true                # refresh session on activity
    cookie_secure: true          # require HTTPS for cookies
    cookie_samesite: "Lax"       # SameSite cookie attribute

Autenticação de Administrador

As contas de administrador podem usar o mesmo fluxo OAuth ou um método de autenticação separado:

yaml

authentication:
  method: google_oauth
  google_oauth:
    client_id: ${GOOGLE_CLIENT_ID}
    client_secret: ${GOOGLE_CLIENT_SECRET}
 
  admin:
    # Admins must match these emails
    admin_emails:
      - "pi@umich.edu"
      - "lead-ra@umich.edu"
 
    # Or use a separate API key for admin access
    api_key: ${ADMIN_API_KEY}

Requisitos de HTTPS

Os provedores OAuth exigem HTTPS para as URIs de redirecionamento em produção. Para desenvolvimento local, você pode usar HTTP com localhost:

yaml

# Development (HTTP allowed)
authentication:
  google_oauth:
    redirect_uri: "http://localhost:8000/auth/google/callback"
 
# Production (HTTPS required)
authentication:
  google_oauth:
    redirect_uri: "https://annotation.example.com/auth/google/callback"

Para implantações em produção atrás de um proxy reverso (nginx, Caddy), certifique-se de que o proxy encaminhe o cabeçalho X-Forwarded-Proto correto:

nginx

# nginx example
location / {
    proxy_pass http://localhost:8000;
    proxy_set_header X-Forwarded-Proto $scheme;
    proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for;
    proxy_set_header Host $host;
}

Exemplo Completo

Configuração completa de autenticação em produção com Google OAuth, restrição de domínio e chave de API de administrador:

yaml

task_name: "Annotation Project"
task_dir: "."
 
authentication:
  method: google_oauth
 
  google_oauth:
    client_id: ${GOOGLE_CLIENT_ID}
    client_secret: ${GOOGLE_CLIENT_SECRET}
    redirect_uri: "https://annotation.umich.edu/auth/google/callback"
    allowed_domains:
      - "umich.edu"
    auto_register: true
    field_mapping:
      username: email
      display_name: name
 
  session:
    lifetime_hours: 48
    cookie_secure: true
 
  admin:
    admin_emails:
      - "pi@umich.edu"
    api_key: ${ADMIN_API_KEY}
 
data_files:
  - "data/instances.jsonl"
 
annotation_schemes:
  - annotation_type: radio
    name: sentiment
    labels: [Positive, Neutral, Negative]
 
output_annotation_dir: "output/"
output_annotation_format: "jsonl"

Leitura Adicional

Login sem senha -- autenticação por link mágico baseado em e-mail
Integração com MTurk -- autenticação em plataforma de crowdsourcing
Painel do Administrador -- gerenciamento de usuários e permissões
Controle de Qualidade -- garantia da qualidade dos anotadores com usuários autenticados

Para detalhes de implementação, consulte a documentação de origem.