Integracja OAuth dla aplikacji zewnętrznych
Aplikacja deweloperska jest przeznaczona dla produktu, który łączy niezależne konta wielu klientów CloudPrint. Na wniosek CloudPrint tworzy organizację deweloperską i aplikację OAuth, a każdy klient sam zatwierdza dostęp przez Authorization Code z PKCE.
Wybierz właściwy model
Użyj API Credentials, gdy jeden klient łączy własny backend ze swoim kontem CloudPrint. Poproś o Developer Organization, gdy publikujesz SaaS, konektor lub integrację dla zewnętrznych klientów. Aplikacja deweloperska nie używa client_credentials; każde konto klienta wymaga osobnej zgody.
Poproś o konto deweloperskie
Wyślij zgłoszenie przez sekcję kontaktową CloudPrint. Podaj nazwę organizacji i produktu, kontakt techniczny, przypadek użycia, stronę produktu, URL polityki prywatności, dokładny callback HTTPS oraz minimalne scopes. CloudPrint tworzy aplikację OAuth i bezpiecznie przekazuje client_id oraz jednorazowy client_secret. Samodzielne tworzenie nie jest obecnie dostępne.
Zarejestruj adresy aplikacji
Podaj publiczną stronę HTTPS, URL polityki prywatności oraz callback URI. Redirect URI musi pasować dokładnie: schemat, host, port, ścieżka i końcowy ukośnik muszą być takie same podczas autoryzacji, wymiany kodu i w konfiguracji aplikacji. Rejestruj wyłącznie rzeczywiste ścieżki callback produktu i odrzucaj przekierowania pod inne adresy.
Uruchom Authorization Code z PKCE
Wygeneruj kryptograficznie losowe, jednorazowe state i PKCE code_verifier, a następnie zapisz je w krótkotrwałej transakcji po stronie serwera. Wylicz challenge S256 i przekieruj przeglądarkę użytkownika:
https://my.cloudprint.me/oauth/authorize?
response_type=code&
client_id=YOUR_CLIENT_ID&
redirect_uri=https%3A%2F%2Fapp.example.com%2Fintegrations%2Fcloudprint%2Fcallback&
scope=printers%3Aread%20documents%3Awrite%20print_jobs%3Awrite&
state=RANDOM_SINGLE_USE_VALUE&
code_challenge=BASE64URL_SHA256_OF_VERIFIER&
code_challenge_method=S256Nie umieszczaj client_secret w adresie przeglądarki. Użytkownik CloudPrint zobaczy aplikację, organizację i żądane uprawnienia przed zatwierdzeniem.
Zweryfikuj callback i wymień kod
W callback odrzuć brakujące, wygasłe lub niezgodne state. Backend wymienia krótkotrwały kod wraz z pierwotnym verifierem:
curl -sS https://public-api.cloudprint.me/oauth/token \
-H 'Content-Type: application/x-www-form-urlencoded' \
--data-urlencode 'grant_type=authorization_code' \
--data-urlencode 'client_id=YOUR_CLIENT_ID' \
--data-urlencode 'client_secret=YOUR_CLIENT_SECRET' \
--data-urlencode 'redirect_uri=https://app.example.com/integrations/cloudprint/callback' \
--data-urlencode 'code=CODE_FROM_CALLBACK' \
--data-urlencode 'code_verifier=ORIGINAL_PKCE_VERIFIER'Callback musi być identyczny z zarejestrowanym URI. Tokeny zapisuj dla organizacji klienta, która rozpoczęła połączenie, nigdy jako jeden globalny token produktu.
Odświeżaj i unieważniaj bezpiecznie
Access token jest krótkotrwały; backend powinien odświeżyć go przed wygaśnięciem:
curl -sS https://public-api.cloudprint.me/oauth/token \
-H 'Content-Type: application/x-www-form-urlencoded' \
--data-urlencode 'grant_type=refresh_token' \
--data-urlencode 'client_id=YOUR_CLIENT_ID' \
--data-urlencode 'client_secret=YOUR_CLIENT_SECRET' \
--data-urlencode 'refresh_token=STORED_REFRESH_TOKEN'Szyfruj client secret i refresh tokeny w bazie, zabezpiecz równoległe odświeżanie i nie loguj pełnych tokenów. Klient może odwołać dostęp w Integrations → Authorized Apps. Nieudany refresh lub API 401 oznacza rozłączenie i wymaga ponownej autoryzacji.
Dokończ połączenie klienta
Po pierwszej wymianie wywołaj /api/v1/me i sprawdź konto oraz scopes. Następnie pobierz drukarki, pozwól klientowi przypisać stabilne printer_id do lokalizacji lub procesów i zapisz identyfikatory CloudPrint obok ID organizacji w swoim systemie. Dalej używaj standardowego API dokumentów i zadań.
Lista przed uruchomieniem
Przed podłączeniem klientów sprawdź cały przepływ callback i refresh, ogranicz scopes, opublikuj prawdziwą politykę prywatności, opisz odłączenie, zapewnij idempotentny druk i kontakt wsparcia. Po cofnięciu zgody nie przełączaj wydruku na drukarkę innego klienta.
Lista kontrolna przed wdrożeniem
- Korzystaj z wychodzącego połączenia agenta; nie wystawiaj portów drukarki do internetu.
- Zapisuj stabilny identyfikator drukarki, a nie tylko jej nazwę.
- Sprawdzaj format dokumentu, rozmiar strony i orientację przed utworzeniem zadania.
- Jawnie obsługuj status końcowy, ponowienia i ochronę przed podwójnym drukiem.