Rublon

Secure Remote Access

By

Ostatnia aktualizacja dnia 10 marca 2025

Niniejszy dokument zawiera wskazówki dotyczące korzystania z interfejsu Rublon REST API w celu włączenia uwierzytelniania wieloskładnikowego dla własnych aplikacji tworzonych i rozwijanych w danej organizacji. W zależności od typu, taka własna aplikacja może albo wyświetlać GUI webowe (w takim przypadku będzie obslugiwała widok Rublon Prompt), albo działać jako tzw. aplikacja promptless. Ta dokumentacja opisuje kroki niezbędne do inicjowania transakcji, obsługi metod uwierzytelniania oraz bezpiecznego finalizowania transakcji dla obydwu typów aplikacji.

Omówienie

Interfejs Rublon REST API umożliwia bezproblemowe wdrożenie uwierzytelniania wieloskładnikowego (MFA) w Twoich aplikacjach. W zależności od tego, czy Twoja aplikacja obsługuje widok Rublon Prompt, czy działa bez niego (promptless), punkty końcowe API i przepływy transakcji mogą się nieznacznie różnić.

Niniejsza dokumentacja dostarcza szczegółowych instrukcji dla obu typów aplikacji, zapewniając bezpieczną i efektywną implementację uwierzytelniania MFA.

WAŻNE: Używanie bibliotek Rublon SDK

Jeśli to możliwe dla Twojego języka programowania, użyj biblioteki Rublon SDK, aby uprościć wdrożenie:

WAŻNE: Konfiguracja typu aplikacji

Upewnij się, że typ aplikacji jest poprawnie skonfigurowany w konsoli Rublon Admin Console. Typ aplikacji wpływa na zachowanie interfejsu API, a nieprawidłowe ustawienia mogą prowadzić do błędów lub nieoczekiwanego działania. Ustaw typ aplikacji na Other.

WAŻNE: Obsługa błędów

  • Obsługa wyjątków: Obsługuj wyjątki na podstawie nazwy wyjątku i kodu błędu, a nie wartości pola errorMessage.
  • Komunikaty dla użytkownika: Wyświetlaj użytkownikom komunikat errorMessage z interfejsu API, gdy to stosowne, co pozwoli na zachowanie spójności z komunikatami platformy Rublon MFA.

WAŻNE: Nagłówek X-Rublon-Signature

Ze względów bezpieczeństwa każde żądanie do interfejsu Rublon API musi zawierać nagłówek X-Rublon-Signature. Ten nagłówek zawiera hash HMAC SHA-256 żądania, zaszyfrowany za pomocą klucza tajnego Twojej aplikacji.

Generowanie podpisu:

  1. Przygotuj treść żądania: Uzyskaj ciąg JSON treści żądania.
  2. Oblicz hash HMAC: Użyj algorytmu HMAC SHA-256 z kluczem tajnym Twojej aplikacji, aby zahashować ciąg JSON.
  3. Dołącz nagłówek: Ustaw nagłówek X-Rublon-Signature w hashu, który otrzymasz.

Ważne: Jeśli brakuje nagłówka X-Rublon-Signature lub jest on nieprawidłowy, interfejs API odpowie wyjątkiem InvalidSignatureException.

Proces transakcji dla aplikacji wspierających widok Rublon Prompt

Ta sekcja opisuje proces transakcji dla aplikacji obsługujących web GUI (a tym samym obsługujących widok Rublon Prompt).

Inicjowanie transakcji

Punkt końcowy:

POST /api/transaction/init HTTP/1.1
Host: core.rublon.net
Content-Type: application/json
Accept: application/json
X-Rublon-Signature: [Generated Signature]

Treść żądania:

{
  "systemToken": "[Your System Token]",
  "username": "user_identifier",
  "callbackUrl": "https://yourapp.com/callback",
  "params": {
    "appVer": "4.0.2",
    "hostName": "Optional Hostname",
    "logoutUrl": "https://yourapp.com/login",
    "os": "Optional OS Information",
    "userPhone": "+1234567890"
  },
  "userEmail": "user@example.com"
}
  • systemToken: Unikalny token systemowy aplikacji.
  • username: Identyfikator użytkownika próbującego się uwierzytelnić.
  • callbackUrl: Adres URL do przekierowania użytkownika po zakończeniu uwierzytelniania MFA.
  • params: Opcjonalne parametry zapewniające dodatkowy kontekst.
    • appVer: wersja konektora (Twojej aplikacji)
    • hostName: nazwa hosta urządzenia klienta
    • logoutUrl: URL do strony wylogowania lub formularza logowania Twojej aplikacji
    • os: informacje o systemie operacyjnym klienta
    • userPhone: numer telefonu użytkownika
  • userEmail: Opcjonalny adres e-mail użytkownika.

Odpowiedź (Wymagane uwierzytelnianie MFA):

Jeśli konektor otrzymał adres webURI, powinien przekierować stronę na ten adres, aby kontynuować uwierzytelnianie MFA.

{
  "status": "OK",
  "result": {
    "webURI": "https://core.rublon.net/api/transaction/process/[Transaction ID]"
  }
}

Odpowiedź (Pominięcie uwierzytelniania MFA):

W tym przypadku należy wpuścić użytkownika do aplikacji bez konieczności ukończenia uwierzytelniania MFA i wyświetlić komunikat zawarty w result.errorMessage.

{
  "status": "ERROR",
  "code": 400,
  "result": {
    "exception": "UserBypassedException",
    "code": 45,
    "errorMessage": "User bypassed",
    "details": null
  }
}

Odpowiedź (Odmowa dostępu):

W tym przypadku użytkownik nie powinien zostać wpuszczony do aplikacji. Przekieruj stronę na adres webURI, gdzie użytkownik zobaczy komunikat „Access Denied!”.

{
  "status": "OK",
  "result": {
    "webURI": "https://core.rublon.net/api/transaction/deny/[Transaction ID]"
  }
}

Odpowiedź (Oczekiwanie na zatwierdzenie przez administratora):

Przekieruj użytkownika na adres webURI z komunikatem w stylu „Twoje konto musi zostać zatwierdzone. Poczekaj, aż administrator zaakceptuje Twoją prośbę o zalogowanie.”

{
  "status": "OK",
  "result": {
    "webURI": "https://core.rublon.net/api/transaction/deny/[Transaction ID]"
  }
}

Finalizowanie transakcji

Po zakończeniu uwierzytelniania MFA użytkownik zostanie przekierowany na Twój adres callbackUrl z parametrami:

https://yourapp.com/callback?rublonState=ok&rublonToken=[Access Token]
  • rublonToken: Access token wymagany do finalizacji transakcji.

Punkt końcowy:

POST /api/transaction/credentials HTTP/1.1
Host: core.rublon.net
Content-Type: application/json
Accept: application/json
X-Rublon-Signature: [Generated Signature]

Treść żadania:

{
  "systemToken": "[Your System Token]",
  "accessToken": "[Access Token from rublonToken]"
}

Odpowiedź:

{
	"status": "OK",
	"result": {
		"systemToken": "F950953E5454435B9A59E3125F9E7879",
		"email": "bob@rublon.com",
		"username": "user-identifier",
	}
}

Użytkownik może teraz zostać zalogowany do aplikacji.

Proces transakcji dla aplikacji, które nie obsługują widoku Rublon Prompt

Ta sekcja opisuje proces transakcji dla aplikacji bez monitu, które nie obsługują widoku Rublon Prompt.

Inicjowanie transakcji

Punkt końcowy:

POST /api/transaction/init HTTP/1.1
Host: core.rublon.net
Content-Type: application/json
Accept: application/json
X-Rublon-Signature: [Generated Signature]

Treść żądania:

{
	"systemToken": "F950953E5454435B9A59E3125F9E7879",
	"username": "bob",
"params": {
	"appVer": "4.0.2",
	"hostName": "22-88-AB",
	"os": "Windows-10-10.0.20348-SP0",
	"userIP": "127.19.3.124",
"userPhone": "+48666777888"
},
"userEmail": "bob@rublon.com"
}
  • appVer: Wersja konektora (Twojej aplikacji własnej)
  • userIP: Publiczny adres IP klienta.
  • userPhone: Opcjonalnie, jeśli został pobrany z usługi Active Directory
  • userEmail: Opcjonalnie, jeśli został pobrany z usługi Active Directory

Odpowiedź (Wymagane uwierzytelnianie MFA):

Poproś użytkownika o uwierzytelnienie MFA.

{
	"status": "OK",
"result": {
	"methods": [
	"email",
	"totp",
	"qrcode",
	"phoneCall",
	"push",
	"sms",
	"smsLink",
	"webauthn",
	"yotp"
],
"tid": "CCF19A8CE2D1406586278D961AB620F2",
"status": "pending",
"companyName": "Rublon",
"applicationName": "Demo"
}
}
  • methods: Dostępne metody uwierzytelniania dla użytkownika.
  • tid: Identyfikator transakcji.
  • status: Status transakcji.

Odpowiedź (Pominiecie uwierzytelniania MFA):

W tym przypadku należy wpuścić użytkownika do aplikacji bez uwierzytelniania MFA i wyświetlić komunikat zawarty w result.errorMessage.

{
	"status": "ERROR",
	"code": 400,
	"result": {
		"exception": "UserBypassedException",
		"code": 45,
		"errorMessage": "User bypassed",
		"details": null
	}
}

Odpowiedź (Odmowa dostępu):

W tym przypadku użytkownik nie powinien zostać wpuszczony do aplikacji. Wyświetl komunikat „Access Denied!”.

{
	"status": "OK",
	"result": {
		"methods": [],
		"tid": "CCF19A8CE2D1406586278D961AB620F2",
		"status": "denied",
		"companyName": "Rublon",
		"applicationName": "Demo"
	}
}

Odpowiedź (Oczekiwanie na zatwierdzenie przez administratora):

Poinformuj użytkownika, że jego konto oczekuje na zatwierdzenie.

{
	"status": "OK",
	"result": {
		"methods": [],
		"tid": "CCF19A8CE2D1406586278D961AB620F2",
		"status": "waiting",
		"companyName": "Rublon",
		"applicationName": "Demo",
		"webURI": "https://core.rublon.net/api/user/enrollment/114de367d58e706aba1030f6cc5615fca162323129d33f2a00479b0a1a6e"
	}
}

Wybór metody uwierzytelniania

Poproś użytkownika o wybór jednej z dostępnych metod uwierzytelniania z tablicy methods.

Punkt końcowy:

POST /api/transaction/methodSSH HTTP/1.1
Host: core.rublon.net
Content-Type: application/json
Accept: application/json
X-Rublon-Signature: [Generated Signature]

Treść żądania:

{
	"systemToken": "F950953E5454435B9A59E3125F9E7879",
	"tid": "CCF19A8CE2D1406586278D961AB620F2",
"method": "email"
}
  • tid: Identyfikator transakcji pobrany z odpowiedzi na inicjację transakcji.
  • method: Metoda uwierzytelniania wybrana przez użytkownika.

Dostępne metody uwierzytelniania:

Odpowiedź:

{
	"status": "OK",
"result": {
	"action": "authentication",
	"method": "email",
"tid": "CCF19A8CE2D1406586278D961AB620F2",
"qrText": "994a113db56f39cbc177cd84d1d1410896359a096bcff23dbea1d487bdf7",
"vericodeLength": 6,
"phoneNumber": "********7888",
"token": "b9a1757f987a77237672d0fd4716fb30119fc0c7a73dccd51d1527dcbfab"
}
}
  • qrText: Gdy użytkownik wybierze metodę uwierzytelniania Kod QR; wyświetl ten kod użytkownikowi.
  • vericodeLength: Gdy użytkownik wybierze metodę Kod SMS lub Kod dostępu.
  • phoneNumber: Gdy użytkownik wybierze metodę Kod SMS, Link SMS lub Połączenie telefoniczne.
  • token: Gdy użytkownik wybierze metodę YubiKey OTP; wymagane do kolejnego żądania.

Po otrzymaniu odpowiedzi na to żądanie, nawiąż połączenie z Socket.IO (https://core.rublon.net/ws/socket.io).

Potwierdzenie tożsamości

W zależności od wybranej metody, postępuj zgodnie z odpowiednimi krokami:

Link e-mail

Proces:

  • Użytkownik otrzymuje e-mail z linkiem potwierdzającym.
  • Po kliknięciu linku API emituje zdarzenie TransactionConfirmedEvent.

Działanie:

Nasłuchuj zdarzenia poprzez WebSockety, aby kontynuować.

Kod dostępu (TOTP & Bypass Code)

Proces:

Użytkownik wprowadza kod jednorazowy.

Punkt końcowy:

POST /api/transaction/confirmCode HTTP/1.1
Host: core.rublon.net
Content-Type: application/json
Accept: application/json
X-Rublon-Signature: [Generated Signature]

Treść żądania:

{
  "systemToken": "[Your System Token]",
  "tid": "[Transaction ID]",
  "vericode": "[User's Passcode]"
}

Odpowiedź (Sukces):

Nasłuchuj zdarzenia TransactionConfirmedEvent. Zdarzenie zawiera atrybut token (zawierający access token transakcji), który będzie wymagany do wykonania kolejnego żądania REST.

{
  "status": "OK",
  "result": true
}

Odpowiedź (Nieprawidłowy kod):

Poproś użytkownika o ponowną próbę.

{
  "status": "ERROR",
  "code": 400,
  "result": {
    "exception": "PasscodeException",
    "code": 18,
    "errorMessage": "Hmm, that's not the right code. Try again.",
    "details": null
  }
}

Kod QR

Proces:

  • Wyświetl kod QR używając wartości w qrText.
  • Użytkownik skanuje kod QR za pomocą aplikacji Rublon Authenticator.

Działanie:

Nasłuchuj zdarzenia TransactionConfirmedEvent.

Powiadomienie mobilne

Proces:

  • Użytkownik otrzymuje powiadomienie push.
  • Po zatwierdzeniu powiadomienia, inferfejs API emituje zdarzneie TransactionConfirmedEvent.
  • Jeśli powiadomienie zostało odrzucone, emitowane jest zdarzeni TransactionDeniedEvent.

Działanie:

Słuchaj wydarzeń i postępuj zgodnie z nimi.

Kod SMS

Proces:

  • Użytkownik otrzymuje kod jednorazowy poprzez wiadomość tekstową.
  • Postępuj tak samo jak dla metody Kod dostępu.

Link SMS

Proces:

  • Użytkownik otrzymuje wiadomość tekstową z linkiem potwierdzającym.

Działanie:

Nasłuchuj zdarzenia TransactionConfirmedEvent po kliknięciu linka przez użytkownika.

Klucz bezpieczeństwa YubiKey OTP

Proces:

  • Użytkownik dotyka klucza YubiKey, aby wprowadzić OTP.

Punkt końcowy:

POST /api/transaction/confirmSecurityKeySSH HTTP/1.1
Host: core.rublon.net
Content-Type: application/json
Accept: application/json
X-Rublon-Signature: [Generated Signature]

Treść żądania:

{
  "systemToken": "[Your System Token]",
  "accessToken": "[Token from methodSSH response]",
  "otp": "[User's YubiKey OTP]"
}

Odpowiedź (Sukces):

{
  "status": "OK"
}

Działanie:

Nasłuchuj zdarzenia TransactionConfirmedEvent.

Klucz bezpieczeństwa WebAuthn/U2F

Nieobsługiwane dla aplikacji promptless. Nie prezentuj tej opcji użytkownikowi.

Połączenie telefoniczne

Proces:

  • Użytkownik otrzymuje połączenie telefoniczne z instrukcjami głosowymi.
  • Aby potwierdzić tożsamość, użytkownik naciska dowolny klawisz numeryczny na klawiaturze telefonu podczas połączenia.
  • Po wykonaniu tej akcji interfejs API emituje zdarzenie TransactionConfirmedEvent.

Działanie:

Nasłuchuj zdarzenia TransactionConfirmedEvent, aby kontynuować transakcję.

Uwaga:

Zdarzenie zawiera atrybut token (access token transakcji), który jest wymagany do następnego żądania REST.

Finalizowanie transakcji

Po wystąpieniu zdarzenia TransactionConfirmedEvent możesz sfinalizować transakcję.

Punkt końcowy:

POST /api/transaction/credentials HTTP/1.1
Host: core.rublon.net
Content-Type: application/json
Accept: application/json
X-Rublon-Signature: [Generated Signature]

Treść żadania:

{
  "systemToken": "[Your System Token]",
  "accessToken": "[Access Token from TransactionConfirmedEvent]"
}

Odpowiedź:

{
  "status": "OK",
  "result": {
    "username": "user_identifier",
    "email": "user@example.com",
    "consumerParams": null
  }
}

Działanie:

Zaloguj użytkownika do aplikacji.

Wyjątki

Nieprawidłowa wartość System Token

{
	"status": "ERROR",
	"code": 400,
	"result": {
		"exception": "APIException",
		"code": 10,
		"errorMessage": "Project error",
		"details": null
	}
}
  • Przyczyna: Podany systemToken jest nieprawidłowy.
  • Działanie: Zweryfikuj i popraw systemToken.

Nieprawidłowy nagłówek X-Rublon-Signature

{
	"status": "ERROR",
	"code": 400,
	"result": {
		"exception": "InvalidSignatureException",
		"code": 9,
		"errorMessage": "X-Rublon-Signature is invalid",
		"details": null
	}
}
  • Przyczyna: Brak podpisu lub jest on nieprawidłowy.
  • Działanie: Upewnij się, że podpis jest poprawnie wygenerowany przy użyciu algorytmu HMAC SHA-256 z Twoim kluczem tajnym.

Wygasły identyfikator transakcji

{
  "status": "ERROR",
  "code": 400,
  "result": {
    "exception": "TransactionIdExpiredException",
    "code": 11,
    "errorMessage": "The session has expired due to inactivity.",
    "details": "You must log in again."
  }
}
  • Przyczyna: Transakcja wygasła.
  • Działanie: Poproś użytkownika o ponowną inicjację uwierzytelniania.

Wygasły Access Token

{
  "status": "ERROR",
  "code": 400,
  "result": {
    "exception": "TransactionAccessTokenExpiredException",
    "code": 11,
    "errorMessage": "Authentication took too long to complete.",
    "details": "Return to the application and select the authentication method again."
  }
}
  • Przyczyna: Access token nie jest już ważny.
  • Działanie: Poproś użytkownika o ponowne wybranie metody uwierzytelniania.

Brakujące parametry lub nieprawidłowy typ aplikacji

{
  "status": "ERROR",
  "code": 400,
  "result": {
    "exception": "MissingFieldException",
    "code": 3,
    "errorMessage": "Parameter required",
    "details": null,
    "name": "callbackUrl"
  }
}
  • Przyczyna: Brak wymaganych parametrów lub typ aplikacji jest niepoprawnie ustawiony.
  • Działanie: Sprawdź, czy wszystkie wymagane parametry zostały uwzględnione oraz czy typ aplikacji jest poprawnie skonfigurowany w konsoli Rublon Admin Console.

Dodatkowe uwagi

  • Komunikacja z Socket.IO:
    • W przypadku aplikacji bez monitów należy ustanowić połączenie WebSocket w celu nasłuchiwania zdarzeń transakcji (TransactionConfirmedEvent, TransactionDeniedEvent).
    • Kanał zdarzeń ma wzorzec: transactionConfirmation.{tid}.{eventName}.
  • Obsługa limitów czasu i ponownych prób:
    • Zaimplementuj odpowiednie limity czasowe dla odpowiedzi użytkownika.
    • Obsługuj wyjątek TooManyRequestsException, gdy użytkownicy przekroczą dozwoloną liczbę prób.
  • Najlepsze praktyki bezpieczeństwa:
    • Używaj protokołu HTTPS dla całej komunikacji z interfejsem API.
    • Chroń swój systemToken i secretKey.
    • Waliduj i sanitizuj wszystkie dane wejściowe od użytkowników.

Rozwiązywanie problemów

Jeśli napotkasz na jakiekolwiek problemy, skontaktuj się z pomocą techniczną Rublon Support.

Powiązane posty