Adres URL autoryzacji to punkt końcowy na Twoim serwerze, który przeprowadza użytkowników przez wymagane przez aplikację kroki autoryzacji.

Pojęcia

Gdy użytkownik doda przepis integracji, przed skonfigurowaniem czegokolwiek innego zostanie przekierowany pod ten adres URL autoryzacji. Aplikacja powinna przeprowadzić go przez odpowiednie procesy autoryzacji, na przykład poprosić o zalogowanie się do zewnętrznego systemu.

Po zakończeniu tych kroków aplikacja powinna przekierować użytkownika pod adres backToUrl, aby mógł dokończyć konfigurację przepisu.

Informacje

Adres powrotu

backToUrl to adres URL monday, pod którym użytkownik może dokończyć konfigurację integracji. Po zakończeniu procesu autoryzacji aplikacja powinna przekierować użytkownika pod ten adres. Możesz go uzyskać, dekodując token JWT z parametru zapytania token.

Token autoryzacyjny

Gdy przekierujemy użytkownika pod Twój adres URL autoryzacji, przekażemy aplikacji parametr zapytania token. Jest to token JWT podpisany za pomocą Signing Secret Twojej aplikacji. Znajdziesz go na stronie Basic Information aplikacji.

Po weryfikacji tokenu jego ładunek będzie zawierać trzy parametry:

• userId - User ID użytkownika monday.com, którego autoryzujesz
• accountId - Account ID konta monday.com tego użytkownika
• backToUrl - adres URL, pod którym użytkownik dokończy konfigurację przepisu. Po zakończeniu autoryzacji aplikacja powinna przekierować go pod ten adres.

Przykład kodu

Poniżej znajdziesz pustą implementację w Node.js, która weryfikuje token i od razu przekierowuje użytkownika z powrotem do monday.

// The authorization route is /authorization
router.get("/authorization", (req, res) => { 
  // get the token from the query parameter
  const { token } = req.query; 

  // verify the JWT token
  const { userId, accountId, backToUrl } = jwt.verify(token, process.env.SIGNING_SECRET);

  // redirect the user
  return res.redirect(backToUrl);
});

Uzyskiwanie tokenu dostępu monday

Czasami proces autoryzacji wymaga uzyskania od użytkownika długoterminowego tokenu dostępu do API monday.com. Aby go uzyskać, aplikacja powinna przekierować użytkownika pod adres URL OAuth monday.com. Gdy użytkownik zatwierdzi dostęp, otrzymasz token dostępu z wymaganymi zakresami uprawnień.

Po zakończeniu procesu możesz przekierować użytkownika pod adres powrotu. Zobacz pełną dokumentację OAuth!

📘 UWAGA

Aby po zakończeniu procesu OAuth monday aplikacja nadal miała dostęp do adresu powrotu, musisz przekazać go - lub cały token autoryzacyjny - w parametrze state żądania OAuth monday.

Implementowanie OAuth

Poniżej znajdziesz przykładowe punkty końcowe do zaimplementowania tego procesu:

1. Przekierowuje użytkownika pod adres URL autoryzacji OAuth
2. Adres URL wywołania zwrotnego, który wymienia kod autoryzacyjny OAuth na token

router.get("/authorization", (req, res) => {
  const { token } = req.query;
  return res.redirect('https://auth.monday.com/oauth2/authorize?' +
    querystring.stringify({
      client_id: process.env.CLIENT_ID,
      state: token
    })
  );
});

router.get("/oauth/callback", async (req, res) => {
  const { code, state } = req.query;
  const { userId, accountId, backToUrl } = jwt.verify(state, process.env.SIGNING_SECRET);

  // Get access token
  const token = await monday.oauthToken(code, process.env.CLIENT_ID, process.env.CLIENT_SECRET)

  // TODO - Store the token in a secure way in a way you'll can later on find it using the user ID. 
  // For example: await tokenStoreService.storeToken(userId, token);

  // Redirect back to monday
  return res.redirect(backToUrl);
});

Dodawanie innych usług do procesu autoryzacji

Jeśli aplikacja integruje monday z inną usługą, może być konieczne dodanie kolejnych procesów autoryzacji, aby uzyskać dostęp do potrzebnych zasobów. Możesz to zrobić, przekierowując użytkownika, by autoryzował dodatkowe usługi, zgodnie z procesem opisanym w poprzedniej sekcji. Gdy aplikacja uzyska wszystkie potrzebne tokeny i informacje, powinna przekierować użytkownika z powrotem pod adres powrotu.

Co się stanie, gdy użytkownik następnym razem doda mój przepis?

Za każdym razem, gdy użytkownik wybierze dodanie przepisu do swojej tablicy, zostanie przekierowany pod Twój adres URL autoryzacji. Aplikacja może wtedy sprawdzić, czy użytkownik został już uwierzytelniony, i przekierować go pod adres backToUrl, zamiast ponownie przeprowadzać proces autoryzacji.

Poniżej znajdziesz przykład, który od razu przekierowuje użytkownika, jeśli aplikacja ma już jego token dostępu:

router.get("/authorization", (req, res) => {
  const { token } = req.query;
  const { userId, accountId, backToUrl } = jwt.verify(state, process.env.CLIENT_SECRET);

  // TODO - Check if you already have proper access token for that user
  // For example: const accessToken = await tokenStoreService.getToken(userId, token);

  if (accessToken) {
    return res.redirect(backToUrl) // redirect immediately
  } else {
    // redirect to monday.com OAuth URL
    return res.redirect('https://auth.monday.com/oauth2/authorize?' +
      querystring.stringify({
        client_id: process.env.CLIENT_ID,
        state: token
      })
    );
  }
});