SSO & OAuth認証

Google OAuth、GitHub OAuth、汎用OIDCを設定して、安全な本番環境の認証を実現します。

SSO & OAuth認証

v2.3.0の新機能

デフォルトでは、Potatoはアノテーターが任意のユーザー名を入力してサインインするシンプルなユーザー名ベースのログインを使用します。これはローカル開発や小規模プロジェクトには便利ですが、本番環境のデプロイメントでは、不正アクセスの防止、アノテーター身元の確認、組織の要件への準拠のために適切な認証が必要です。

Potato 2.3は3つの認証方法のサポートを追加しました：

Google OAuth -- Googleアカウントでサインイン、オプションのドメイン制限付き
GitHub OAuth -- GitHubアカウントでサインイン、オプションの組織制限付き
汎用OIDC -- 任意のOpenID Connectプロバイダー（Okta、Azure AD、Auth0、Keycloakなど）に接続

すべてのメソッドは、混合モードセットアップとしてPotatoの既存のユーザー名ログインと組み合わせることができます。

Google OAuth

前提条件

Google Cloud Consoleでプロジェクトを作成
「Google Identity」APIを有効にする
OAuth 2.0認証情報を作成（Webアプリケーションタイプ）
「認可済みリダイレクトURI」にPotatoサーバーURLを追加：https://your-server.com/auth/google/callback

設定

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

ドメイン制限

allowed_domainsが設定されている場合、それらのドメインのメールアドレスを持つユーザーのみがサインインできます。それ以外のユーザーにはエラーメッセージが表示されます：

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

前提条件

GitHub Settings > Developer settings > OAuth Apps > New OAuth Appに移動
「Authorization callback URL」をhttps://your-server.com/auth/github/callbackに設定
Client IDをメモし、Client Secretを生成

設定

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

組織制限

GitHub OAuthは特定の組織のメンバーにアクセスを制限できます。これには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

エンタープライズSSOプロバイダー（Okta、Azure AD、Auth0、Keycloakなど）には、汎用OpenID Connect統合を使用してください。

設定

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の例

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の例

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の例

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

ドメイン制限

すべてのOAuthメソッドは、メールアドレスに基づくドメイン制限をサポートしています。特定の機関からの任意のアカウントを許可したい場合に便利です：

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

emailクレームを含むOIDCプロバイダーの場合、ドメイン制限は自動的に機能します。メールを含まないプロバイダーの場合、emailスコープを明示的にリクエストする必要がある場合があります。

自動登録

デフォルトでは、ユーザーはアノテーション前にPotatoに事前登録されている必要があります。auto_register: trueを設定すると、正常に認証されたユーザーは初回ログイン時にPotatoに自動的に作成されます。

yaml

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

特定のユーザーを事前承認しつつ他のユーザーをブロックする場合：

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

混合モード

複数の認証方法を同時に有効にできます。ログインページには、有効化された各方法のボタンとオプションのユーザー名フィールドが表示されます。

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"

混合モードは移行時に便利です：ユーザー名ログインと並行してOAuthを有効にし、すべてのアノテーターがOAuthアカウントをリンクした後にユーザー名ログインを無効にします。

セッション管理

認証済みユーザーのセッション動作を設定：

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

管理者認証

管理者アカウントは同じOAuthフローまたは別の認証方法を使用できます：

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の要件

OAuthプロバイダーは本番環境でリダイレクトURIにHTTPSを要求します。ローカル開発ではlocalhostでHTTPを使用できます：

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"

リバースプロキシ（nginx、Caddy）の背後にある本番デプロイメントの場合、プロキシが正しいX-Forwarded-Protoヘッダーを転送することを確認してください：

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

完全な例

Google OAuth、ドメイン制限、管理者APIキーを使用した完全な本番認証セットアップ：

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"

参考資料

パスワードレスログイン -- メールベースのマジックリンク認証
MTurk統合 -- クラウドソーシングプラットフォーム認証
管理ダッシュボード -- ユーザーと権限の管理
品質管理 -- 認証済みユーザーによるアノテーター品質の確保

実装の詳細については、ソースドキュメントを参照してください。