Skip to content
Cette page n'est pas encore disponible dans votre langue. La version anglaise est affichée.

SSO & OAuth-Authentifizierung

Google OAuth, GitHub OAuth und generisches OIDC für sichere Produktionsauthentifizierung konfigurieren.

SSO & OAuth-Authentifizierung

Neu in v2.3.0

Standardmäßig verwendet Potato ein einfaches benutzernamenbasiertes Login, bei dem Annotatoren einen beliebigen Benutzernamen eingeben, um sich anzumelden. Dies ist praktisch für die lokale Entwicklung und kleine Projekte, aber Produktionsinstallationen benötigen eine ordnungsgemäße Authentifizierung, um unbefugten Zugriff zu verhindern, die Annotatoridentität sicherzustellen und institutionelle Anforderungen zu erfüllen.

Potato 2.3 fügt Unterstützung für drei Authentifizierungsmethoden hinzu:

  1. Google OAuth -- Anmeldung mit Google-Konten, mit optionaler Domain-Beschränkung
  2. GitHub OAuth -- Anmeldung mit GitHub-Konten, mit optionaler Organisationsbeschränkung
  3. Generisches OIDC -- Verbindung zu einem beliebigen OpenID Connect-Anbieter (Okta, Azure AD, Auth0, Keycloak usw.)

Alle Methoden können mit Potatos vorhandenem Benutzernamen-Login für ein gemischtes Setup kombiniert werden.

Google OAuth

Voraussetzungen

  1. Erstellen Sie ein Projekt in der Google Cloud Console
  2. Aktivieren Sie die "Google Identity" API
  3. Erstellen Sie OAuth 2.0-Anmeldeinformationen (Web-Anwendungstyp)
  4. Fügen Sie Ihre Potato-Server-URL zu "Authorized redirect URIs" hinzu: https://your-server.com/auth/google/callback

Konfiguration

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

Domain-Beschränkung

Wenn allowed_domains gesetzt ist, können sich nur Benutzer mit E-Mail-Adressen aus diesen Domains anmelden. Anderen wird eine Fehlermeldung angezeigt:

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

Voraussetzungen

  1. Gehen Sie zu GitHub Settings > Developer settings > OAuth Apps > New OAuth App
  2. Setzen Sie "Authorization callback URL" auf https://your-server.com/auth/github/callback
  3. Notieren Sie Ihre Client ID und generieren Sie einen Client Secret

Konfiguration

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

Organisationsbeschränkung

GitHub OAuth kann den Zugriff auf Mitglieder bestimmter Organisationen beschränken. Dies erfordert den read:org-Scope:

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

Generisches OIDC

Für Enterprise-SSO-Anbieter (Okta, Azure AD, Auth0, Keycloak usw.) verwenden Sie die generische OpenID Connect-Integration.

Konfiguration

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

Azure AD-Beispiel

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

Okta-Beispiel

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

Keycloak-Beispiel

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

Domain-Beschränkung

Alle OAuth-Methoden unterstützen die Domain-Beschränkung auf Basis von E-Mail-Adressen. Dies ist nützlich, wenn Sie jedem Konto einer bestimmten Institution erlauben möchten:

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

Für OIDC-Anbieter, die einen email-Claim enthalten, funktioniert die Domain-Beschränkung automatisch. Für Anbieter ohne E-Mail müssen Sie möglicherweise den email-Scope explizit anfordern.

Automatische Registrierung

Standardmäßig müssen Benutzer in Potato vorregistriert sein, bevor sie annotieren können. Mit auto_register: true wird jeder Benutzer, der sich erfolgreich authentifiziert, bei seiner ersten Anmeldung automatisch in Potato erstellt.

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

Um bestimmte Benutzer vorab zu genehmigen und andere zu blockieren:

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

Gemischter Modus

Sie können mehrere Authentifizierungsmethoden gleichzeitig aktivieren. Die Anmeldeseite zeigt Schaltflächen für jede aktivierte Methode sowie ein optionales Benutzernamenfeld.

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"

Der gemischte Modus ist bei der Migration nützlich: Aktivieren Sie OAuth neben dem Benutzernamen-Login, dann deaktivieren Sie das Benutzernamen-Login, sobald alle Annotatoren ihre OAuth-Konten verknüpft haben.

Sitzungsverwaltung

Sitzungsverhalten für authentifizierte Benutzer konfigurieren:

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

Admin-Authentifizierung

Admin-Konten können denselben OAuth-Ablauf oder eine separate Authentifizierungsmethode verwenden:

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}

HTTPS-Anforderungen

OAuth-Anbieter erfordern HTTPS für Umleitungs-URIs in der Produktion. Für die lokale Entwicklung können Sie HTTP mit localhost verwenden:

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"

Für Produktionsinstallationen hinter einem Reverse Proxy (nginx, Caddy) stellen Sie sicher, dass der Proxy den korrekten X-Forwarded-Proto-Header weiterleitet:

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

Vollständiges Beispiel

Vollständige Produktionsauthentifizierungseinrichtung mit Google OAuth, Domain-Beschränkung und Admin-API-Schlüssel:

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"

Weiterführende Informationen

Implementierungsdetails finden Sie in der Quelldokumentation.