Korzystając z funkcji aplikacji danych logowania, możesz łatwo łączyć się z usługami zewnętrznymi - przy minimalnej ilości kodowania!

Niezależnie od tego, czy tworzysz bloki na potrzeby monday workflows, czy integrujesz zewnętrzne interfejsy API, ta funkcja ułatwia tworzenie bezpiecznych i skalowalnych integracji. Struktura obsługuje procesy uwierzytelniania i przechowywanie danych logowania, dzięki czemu możesz skupić się na tworzeniu elastycznych, przyjaznych dla użytkowników rozwiązań.

Pojęcia

Funkcja aplikacji danych logowania umożliwia bezpieczne uwierzytelnianie między aplikacjami monday a usługami zewnętrznymi, takimi jak Google, Dropbox czy Slack, w ramach monday workflows.

Obsługuje procesy uwierzytelniania OAuth 2.0 i tokenami API, dzięki czemu łatwo zintegrujesz usługi niezależnie od obsługiwanej przez nie metody uwierzytelniania.

Po uwierzytelnieniu dane logowania przypisane do użytkownika są bezpiecznie przechowywane i powiązane z aplikacją. Możesz ich używać ponownie w różnych funkcjach aplikacji do tworzenia workflow, w tym w blokach i polach niestandardowych.

Bezpieczeństwo

Wszystkie dane logowania są obsługiwane z zastosowaniem rygorystycznych zabezpieczeń:

• Dane poufne są przechowywane w bezpiecznym miejscu.
• Dane poufne są przechowywane w tym samym regionie co konto monday.com.

👍 Obsługiwane typy uwierzytelniania

• OAuth 2.0: Obsługuje przekierowania, wymianę tokenów, tokeny odświeżania i zgodę użytkownika.
• Token API: Wykorzystuje statyczny token do bezpośredniego dostępu do API. Jest prosty i szybki w konfiguracji, ale mniej bezpieczny.

✅ Najlepsza praktyka: Jeśli to możliwe, wybieraj OAuth, aby zwiększyć bezpieczeństwo i usprawnić zarządzanie tokenami.

Wdrażanie

Aby utworzyć funkcję aplikacji danych logowania, musisz skonfigurować zarówno aplikację monday, jak i integrowaną usługę zewnętrzną. Ponieważ te dwa systemy wymagają koordynacji między aplikacjami, niektóre ustawienia trzeba skonfigurować równolegle.

Poniższe kroki przedstawiają ogólny przebieg procesu. Więcej informacji znajdziesz w sekcji „Informacje referencyjne”:

1. Zacznij od utworzenia aplikacji dla usługi zewnętrznej, którą chcesz zintegrować. Postępuj zgodnie z podanymi instrukcjami, aby prawidłowo skonfigurować wymagane ustawienia.
2. Utwórz aplikację lub otwórz istniejącą w monday.com Developer Center.
3. Dodaj funkcję aplikacji Credentials (Dane logowania). Dowiedz się, jak utworzyć nową funkcję aplikacji, tutaj.

4. Po utworzeniu funkcji aplikacji monday skonfiguruj ustawienia aplikacji dla każdej z poniższych sekcji:

Jeśli wybierzesz OAuth

Kontynuuj konfigurację następujących sekcji w aplikacji monday:

Jeśli wybierzesz token API

W panelu konfiguracji pojawią się następujące pola:

5. Połącz funkcję aplikacji danych logowania z funkcjami aplikacji bloków i pól niestandardowych, aby używać jej w kreatorze workflow.
6. Przetestuj bloki workflow, wykonując te kroki (opcjonalne, ale zalecane).
7. Opublikuj wersję roboczą jako aktywną, aby udostępnić funkcję na platformie.
8. Po pomyślnym uwierzytelnieniu dane logowania zostaną zapisane w monday.

Informacje referencyjne

Adres URL przekierowania

Podczas konfigurowania aplikacji zewnętrznej każda usługa innej firmy obsługująca OAuth 2.0 poprosi o adres URL przekierowania, na który odeśle użytkowników po zalogowaniu.

Możesz znaleźć go w Developer Center po utworzeniu funkcji aplikacji danych logowania monday.com. Możesz też użyć następującego adresu URL przekierowania OAuth: https://apps-credentials.monday.com/authorize/oauth2/redirect-uri

Unikalny identyfikator dostawcy

Niektóre usługi zewnętrzne używają unikalnych identyfikatorów do rozpoznawania poszczególnych połączeń użytkowników.

:point_right: Na przykład: W Gmailu unikalnym identyfikatorem jest adres e-mail użytkownika.

Ponieważ nie ma standardowego sposobu udostępniania ani pobierania identyfikatora w różnych usługach, musisz udostępnić publicznie dostępny punkt końcowy zaplecza, z którego będziemy mogli pobrać ten identyfikator. Ten punkt końcowy powinien weryfikować przychodzące żądanie, porównując nagłówek Authorization z kluczem tajnym podpisywania aplikacji.

// Example: Verify Authorization header using the jsonwebtoken package

const { authorization } = req.headers;

const signingSecret = process.env.MONDAY_SIGNING_SECRET;

await new Promise((resolve, reject) => {
   jwt.verify(authorization, signingSecret, (err, decoded) => {
      if (err) {
        reject(err);
      } else {
        resolve(decoded);
      }
   });
});

Po wdrożeniu punktu końcowego:

1. Przejdź do sekcji Dodatkowe informacje w funkcji aplikacji danych logowania.
2. Wprowadź adres URL punktu końcowego używanego do pobrania unikalnego identyfikatora dostawcy, np. https://your-server

Chodzi o żądanie, które monday.com wysyła do Twojego zaplecza podczas etapu wywołania zwrotnego OAuth. Po zakończeniu procesu OAuth wywołamy podany punkt końcowy, aby pobrać unikalny identyfikator dostawcy dla danych logowania użytkownika.

W tym żądaniu przesyłamy token dostępu użytkownika wraz z następującym ładunkiem:

{
  "token": "abcs1234"
}

{  
  "userId": 123, // The ID of the user initiating the request  
  "accountId": 456, // The ID of the account associated with the request  
  "appFeatureReferenceId": 789, // The reference ID of your app feature  
  "callbackRequestedParams": {...}, // Parameters extracted from the OAuth callback  
  "tokenRequestedParams": {...}, // Parameters extracted from the token response  
  "userCredentialsParams": {...} // Optional parameters provided by the user  
}

Automatycznie dodajemy do żądania token dostępu użytkownika, używając klucza token, który został podany.

Oczekiwana odpowiedź

Serwer powinien zwrócić dane w następującym formacie:

{  
  "providerUniqueIdentifier": "test@monday.com", // a unique token-specific ID  
  "displayName": "Test Gmail" // the name displayed to the user in the UI  
}

Konfigurowanie parametrów danych logowania

Niektóre usługi zewnętrzne wymagają informacji przypisanych do użytkownika (np. subdomeny, regionu lub identyfikatora organizacji) przed rozpoczęciem procesu uwierzytelniania. Parametry danych logowania pozwalają zbierać te informacje i definiować dodatkowe pola, które pojawią się podczas konfigurowania integracji przez użytkownika.

:point_right: Na przykład: W Salesforce musimy znać subdomenę użytkownika, aby móc komunikować się z właściwym API.

Obsługiwane typy

Parametry danych logowania obsługują podstawowe typy danych: string, boolean i number.

Możesz połączyć parametr z typem pola korzystającym z jednego z tych podstawowych typów danych. Parametry mogą też odwoływać się do podstawowego typu pola zawierającego statyczne opcje.

Jak skonfigurować

1. Parametry danych logowania możesz skonfigurować bezpośrednio w Developer Center, w funkcji aplikacji Credentials (Dane logowania). Dodając parametr, pamiętaj o podaniu:

• Nazwa: krótki klucz używany do odwoływania się do wartości w wywołaniach API
• Tytuł: nazwa widoczna dla użytkownika, która wyjaśnia przeznaczenie pola
• Typ: wybierz string, number lub boolean
• Wymagane: określ, czy pole jest wymagane

2. Po skonfigurowaniu tych parametrów możesz się do nich odwoływać w innych polach danych logowania, używając składni {{parameterName}}.

"authorizationUrl": {
  "type": "url",
  "value": "https://{{subdomain}}.salesforce.com/oauth2/authorize"
}

3. Po rozpoczęciu procesu autoryzacji zastępujemy parametry danymi wprowadzonymi przez użytkownika. Ta wartość jest też dostępna w ładunku punktu końcowego unikalnego identyfikatora dostawcy oraz w innych żądaniach korzystających z danych logowania (np. w adresie URL wykonania bloku i opcjach zdalnych).

Konfigurowanie parametrów tokena API

Niektóre usługi zewnętrzne nie obsługują OAuth i wymagają uwierzytelniania za pomocą tokenów API. Parametry tokena API pozwalają zdefiniować pola, które pojawią się podczas konfigurowania integracji przez użytkownika.

Jak skonfigurować

Parametry tokena API możesz skonfigurować bezpośrednio w Developer Center, w funkcji aplikacji Credentials (Dane logowania).

Te parametry pojawiają się automatycznie po wybraniu tokena API jako typu danych logowania. Niektóre pola są wstępnie zdefiniowane i nie można ich modyfikować, ale możesz skonfigurować następujące ustawienia, aby dostosować działanie tokena w aplikacji:

• Tytuł parametru: tytuł pola widoczny dla użytkowników
• Tekst zastępczy: tekst wyświetlany w polu, zanim użytkownik wprowadzi wartość
• Statyczny sufiks: opcjonalny tekst wyświetlany po polu
• Tekst opisu: krótki dodatkowy kontekst lub wskazówki, które pomogą użytkownikom zrozumieć, co należy wpisać
• Tekst linku: etykieta opcjonalnego linku (np. „Dowiedz się więcej”)
• Adres URL linku: adres strony otwieranej po kliknięciu tekstu linku

Te ustawienia określają, jak pole tokena API będzie wyglądać w interfejsie monday.com, gdy użytkownicy będą łączyć aplikację.

Łączenie funkcji aplikacji danych logowania z innymi funkcjami aplikacji

Aby używać funkcji aplikacji danych logowania w kreatorze workflow, musisz połączyć ją z innymi funkcjami aplikacji:

Pole niestandardowe dla monday workflows

1. Otwórz funkcję aplikacji pola niestandardowego i przejdź do sekcji Credentials (Dane logowania).
2. Kliknij Add credentials (Dodaj dane logowania).
3. Wybierz dane logowania z listy rozwijanej i przypisz klucz*.
4. Kliknij Add (Dodaj).

• :memo: Uwaga: Klucz będzie używany w ładunkach żądań wysyłanych do Twojej usługi (np. w przypadku opcji zdalnych lub pól podrzędnych). Będzie dostępny w atrybucie credentialsValues.

Integracja dla monday workflows

1. Otwórz funkcję aplikacji bloku i przejdź do sekcji Credentials (Dane logowania).
2. Kliknij Add credentials (Dodaj dane logowania).
3. Wybierz dane logowania z listy rozwijanej i dodaj tytuł, nagłówek (opcjonalnie), podtytuł oraz klucz*.
4. Kliknij Add (Dodaj).

• :memo: Uwaga: Klucz będzie używany w ładunkach żądań wysyłanych do Twojej usługi (np. w przypadku subskrybowania i anulowania subskrypcji albo wykonywania działania). Będzie dostępny w atrybucie credentialsValues.