Skip to content

Autenticación SSO y OAuth

Configura Google OAuth, GitHub OAuth y OIDC genérico para autenticación segura en producción.

Autenticación SSO y OAuth

Nuevo en v2.3.0

De forma predeterminada, Potato usa un inicio de sesión simple basado en nombre de usuario donde los anotadores escriben cualquier nombre de usuario para acceder. Esto es conveniente para desarrollo local y proyectos pequeños, pero los despliegues en producción necesitan autenticación adecuada para prevenir acceso no autorizado, asegurar la identidad del anotador y cumplir con requisitos institucionales.

Potato 2.3 agrega soporte para tres métodos de autenticación:

  1. Google OAuth -- inicio de sesión con cuentas de Google, con restricción de dominio opcional
  2. GitHub OAuth -- inicio de sesión con cuentas de GitHub, con restricción de organización opcional
  3. OIDC Genérico -- conexión con cualquier proveedor de OpenID Connect (Okta, Azure AD, Auth0, Keycloak, etc.)

Todos los métodos pueden combinarse con el inicio de sesión por nombre de usuario existente de Potato para una configuración de modo mixto.

Google OAuth

Requisitos Previos

  1. Crea un proyecto en la Google Cloud Console
  2. Habilita la API "Google Identity"
  3. Crea credenciales OAuth 2.0 (tipo aplicación web)
  4. Agrega la URL de tu servidor Potato a "URIs de redirección autorizados": https://your-server.com/auth/google/callback

Configuración

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

Restricción de Dominio

Cuando se configura allowed_domains, solo los usuarios con direcciones de correo electrónico de esos dominios pueden iniciar sesión. Los demás ven un mensaje de error:

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

Requisitos Previos

  1. Ve a GitHub Settings > Developer settings > OAuth Apps > New OAuth App
  2. Establece "Authorization callback URL" a https://your-server.com/auth/github/callback
  3. Anota tu Client ID y genera un Client Secret

Configuración

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

Restricción de Organización

GitHub OAuth puede restringir el acceso a miembros de organizaciones específicas. Esto requiere el scope 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 proveedores de SSO empresariales (Okta, Azure AD, Auth0, Keycloak, etc.), usa la integración genérica de OpenID Connect.

Configuración

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

Ejemplo de 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

Ejemplo de 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

Ejemplo de 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

Restricción de Dominio

Todos los métodos de OAuth admiten restricción de dominio basada en direcciones de correo electrónico. Esto es útil cuando deseas permitir cualquier cuenta de una institución 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 proveedores OIDC que incluyen un claim de email, la restricción de dominio funciona automáticamente. Para proveedores que no incluyen email, es posible que necesites solicitar el scope email explícitamente.

Registro Automático

De forma predeterminada, los usuarios deben estar pre-registrados en Potato antes de poder anotar. Con auto_register: true, cualquier usuario que se autentique exitosamente se crea automáticamente en Potato en su primer inicio de sesión.

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

Para pre-aprobar usuarios específicos mientras se bloquea a otros:

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 Mixto

Puedes habilitar múltiples métodos de autenticación simultáneamente. La página de inicio de sesión muestra botones para cada método habilitado más un campo opcional de nombre de usuario.

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"

El modo mixto es útil durante la migración: habilita OAuth junto con el inicio de sesión por nombre de usuario, luego deshabilita el inicio de sesión por nombre de usuario una vez que todos los anotadores hayan vinculado sus cuentas OAuth.

Gestión de Sesiones

Configura el comportamiento de sesiones para usuarios 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

Autenticación de Administradores

Las cuentas de administrador pueden usar el mismo flujo OAuth o un método de autenticación 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

Los proveedores de OAuth requieren HTTPS para las URIs de redirección en producción. Para desarrollo local, puedes usar HTTP con 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 despliegues en producción detrás de un proxy inverso (nginx, Caddy), asegúrate de que el proxy reenvíe el encabezado X-Forwarded-Proto correcto:

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

Ejemplo Completo

Configuración completa de autenticación en producción con Google OAuth, restricción de dominio y clave 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"

Lectura Adicional

Para detalles de implementación, consulta la documentación fuente.