Logowanie przez PLVTuber

Konto PLVTuber może służyć do logowania w innych aplikacjach: na stronach, w botach czy programach na komputer. Logowanie odbywa się na login.plvtuber.pl, a aplikacja dostaje tylko te dane, na które użytkownik się zgodzi.

login.plvtuber.pl to standardowy dostawca OpenID Connect, więc wystarczy gotowa, sprawdzona biblioteka OIDC (np. openid-client dla Node.js) zamiast własnej implementacji.

Adresy

Issuerhttps://login.plvtuber.pl
Discoveryhttps://login.plvtuber.pl/.well-known/openid-configuration

Wymagany jest przepływ authorization code z PKCE (S256), także dla aplikacji z sekretem. Przepływ implicit i logowanie hasłem przez aplikację nie są dostępne.

Rodzaje aplikacji

AplikacjaSekretRedirect URI
Strona z backendemtak (client_secret_basic)dokładny adres https://, wszystkie na jednej domenie
Program na komputernigdyhttp://127.0.0.1/callback, port dowolny przy uruchomieniu
Aplikacja tylko w przeglądarcebrakdokładny adres https:// (lepiej mieć backend)

Programy na komputer otwierają logowanie w systemowej przeglądarce (nie we wbudowanym oknie), nasłuchują na losowym porcie loopback i trzymają refresh token w systemowym magazynie haseł. Użytkownik zawsze potwierdza takie logowanie jednym kliknięciem.

Zakresy danych

ZakresCo dostaje aplikacja
openidsub: identyfikator użytkownika, inny dla każdej aplikacji
profilename, picture, updated_at
emailemail, email_verified: tylko gdy PLVTuber włączy to dla aplikacji i tylko zweryfikowane adresy
vtubervtuber: zatwierdzony profil VTubera użytkownika albo null
vtuber.managedmanaged_vtubers: zatwierdzone profile, którymi użytkownik zarządza
offline_accessrefresh token (razem z prompt=consent)

Dane są dostępne w userinfo (/me). Jeśli usługa danych PLVTuber chwilowo nie odpowiada, vtuber ma wartość null, a _claim_errors wymienia zakresy, których nie udało się wypełnić. Wtedy warto spróbować później, zamiast uznawać użytkownika za nie-VTubera.

Przykład (Node.js)

import * as client from 'openid-client';

const config = await client.discovery(new URL('https://login.plvtuber.pl'), CLIENT_ID, CLIENT_SECRET);

// 1. Przekierowanie do logowania
const verifier = client.randomPKCECodeVerifier();
const state = client.randomState();
const url = client.buildAuthorizationUrl(config, {
  redirect_uri: 'https://twoja-aplikacja.pl/callback',
  scope: 'openid profile vtuber',
  code_challenge: await client.calculatePKCECodeChallenge(verifier),
  code_challenge_method: 'S256',
  state,
});

// 2. Powrót na redirect_uri
const tokens = await client.authorizationCodeGrant(config, currentUrl, {
  pkceCodeVerifier: verifier,
  expectedState: state,
});
const me = await client.fetchUserInfo(config, tokens.access_token, tokens.claims().sub);

Tokeny

  • Access token jest ważny 10 minut.
  • ID token to migawka do wyświetlania. Do decyzji (np. funkcje tylko dla VTuberów) lepiej pobrać świeże dane z /me.
  • Refresh token zmienia się przy każdym użyciu. Użycie starego unieważnia całe połączenie (ochrona przed kradzieżą). Programy na komputer: 30 dni bez użycia, najwyżej rok. Strony: 30 dni bez użycia, najwyżej 180 dni.
  • Użytkownik może odłączyć aplikację na login.plvtuber.pl/konto. Refresh token zwraca wtedy invalid_grant.

Błędy i wylogowanie

  • access_denied: użytkownik wybrał "Anuluj".
  • login_required / consent_required: wysłano prompt=none, a potrzebna jest interakcja użytkownika.
  • Wylogowanie: RP-initiated logout przez end_session_endpoint. Strony z adresem back-channel logout dostają informację, gdy użytkownik wyloguje się gdziekolwiek.

Jak zgłosić aplikację

Aplikacje rejestrują na razie administratorzy PLVTuber. Do zgłoszenia przydadzą się:

  • nazwa i krótki opis aplikacji,
  • rodzaj aplikacji (strona, program na komputer),
  • redirect URI (i ewentualnie adres po wylogowaniu),
  • potrzebne zakresy danych i powód, jeśli chodzi o email,
  • strona główna i polityka prywatności,
  • konto PLVTuber osoby odpowiedzialnej za aplikację.

Zgłoszenia prosimy wysyłać na [email protected] albo na naszym Discordzie. Sekret aplikacji przekazujemy prywatnie i tylko raz.