Skip to content
यह पृष्ठ अभी आपकी भाषा में उपलब्ध नहीं है। अंग्रेज़ी संस्करण दिखाया जा रहा है।

Autenticazione SSO e OAuth

Configura Google OAuth, GitHub OAuth e OIDC generico per un'autenticazione sicura in produzione.

Autenticazione SSO e OAuth

Novità in v2.3.0

Per impostazione predefinita, Potato utilizza un semplice login basato su nome utente in cui gli annotatori digitano qualsiasi nome utente per accedere. Questo è conveniente per lo sviluppo locale e i piccoli progetti, ma le distribuzioni di produzione necessitano di un'autenticazione adeguata per prevenire accessi non autorizzati, garantire l'identità degli annotatori e conformarsi ai requisiti istituzionali.

Potato 2.3 aggiunge il supporto per tre metodi di autenticazione:

  1. Google OAuth -- accesso con account Google, con restrizione di dominio opzionale
  2. GitHub OAuth -- accesso con account GitHub, con restrizione di organizzazione opzionale
  3. OIDC generico -- connessione a qualsiasi provider OpenID Connect (Okta, Azure AD, Auth0, Keycloak, ecc.)

Tutti i metodi possono essere combinati con il login tramite nome utente esistente di Potato per una configurazione in modalità mista.

Google OAuth

Prerequisiti

  1. Crea un progetto nella Google Cloud Console
  2. Abilita l'API "Google Identity"
  3. Crea credenziali OAuth 2.0 (tipo Applicazione web)
  4. Aggiungi l'URL del tuo server Potato agli "Authorized redirect URIs": https://your-server.com/auth/google/callback

Configurazione

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

Restrizione di dominio

Quando allowed_domains è impostato, solo gli utenti con indirizzi email di quei domini possono accedere. Gli altri vedono un messaggio di errore:

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

Prerequisiti

  1. Vai su GitHub Settings > Developer settings > OAuth Apps > New OAuth App
  2. Imposta "Authorization callback URL" su https://your-server.com/auth/github/callback
  3. Annota il tuo Client ID e genera un Client Secret

Configurazione

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

Restrizione di organizzazione

GitHub OAuth può limitare l'accesso ai membri di organizzazioni specifiche. Ciò richiede lo 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 generico

Per i provider SSO aziendali (Okta, Azure AD, Auth0, Keycloak, ecc.), usa l'integrazione generica OpenID Connect.

Configurazione

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

Esempio 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

Esempio 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

Esempio 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

Restrizione di dominio

Tutti i metodi OAuth supportano la restrizione di dominio basata sugli indirizzi email. Questo è utile quando si vuole consentire l'accesso a qualsiasi account di una specifica istituzione:

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."

Per i provider OIDC che includono un claim email, la restrizione di dominio funziona automaticamente. Per i provider che non includono l'email, potrebbe essere necessario richiedere esplicitamente lo scope email.

Auto-registrazione

Per impostazione predefinita, gli utenti devono essere pre-registrati in Potato prima di poter annotare. Con auto_register: true, qualsiasi utente che si autentica con successo viene automaticamente creato in Potato al suo primo accesso.

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

Per pre-approvare utenti specifici bloccando gli altri:

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."

Modalità mista

Puoi abilitare più metodi di autenticazione simultaneamente. La pagina di login mostra pulsanti per ogni metodo abilitato più un campo nome utente opzionale.

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"

La modalità mista è utile durante la migrazione: abilita OAuth insieme al login con nome utente, poi disabilita il login con nome utente una volta che tutti gli annotatori hanno collegato i loro account OAuth.

Gestione delle sessioni

Configura il comportamento delle sessioni per gli utenti autenticati:

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

Autenticazione amministratore

Gli account amministratore possono utilizzare lo stesso flusso OAuth o un metodo di autenticazione separato:

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}

Requisiti HTTPS

I provider OAuth richiedono HTTPS per gli URI di reindirizzamento in produzione. Per lo sviluppo locale, puoi usare 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"

Per distribuzioni di produzione dietro un reverse proxy (nginx, Caddy), assicurati che il proxy inoltri l'intestazione X-Forwarded-Proto corretta:

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

Esempio completo

Configurazione completa dell'autenticazione di produzione con Google OAuth, restrizione di dominio e chiave API amministratore:

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"

Ulteriori letture

Per i dettagli di implementazione, consulta la documentazione sorgente.