Oracle APEX – Let’s integrate with JIRA! Część 1

6 września 2019, Lech Cieślik

Jira jest oprogramowaniem firmy Atlassian służącym do zarządzania projektami. Użytkownik pracujący z dowolną aplikacją APEX często potrzebuje zgłosić błąd dotyczący działania aplikacji lub danych, z którymi pracuje. Zamiast logować się do Jiry, szukać odpowiedniego projektu, korzystać z wizarda który umożliwi mu stworzenie nowego zgłoszenia (nazwy, typu, opisu, przypisania zgłoszenia itp.), może w łatwy sposób wykorzystać do tego rozwiązanie zaimplementowane w Oracle Application Express, które krok po kroku przedstawimy w serii artykułów Oracle APEX – Let’s integrate with Jira! W przykładach wykorzystamy bazę danych Oracle Database 12c Enterprise Edition oraz narzędzie Oracle SQL Developer Version 18.2.

Tym wpisem rozpoczniemy serię trzech artykułów opisujących jak krok po kroku zintegrować aplikację Oracle APEX z Jirą.

Artykuły zostaną podzielone na trzy części:

  1. W pierwszej części przedstawimy dokładne działanie autoryzacji typu OAuth opartej o proces wymiany tokenów zwany popularnie „OAuth Dance”. Efektem końcowym będzie uzyskanie tokena który pozwoli nam nam na zarządzanie danymi Jiry za pomocą REST API.
  2. W kolejnym kroku skupimy się na wykorzystaniu języka Java w Oracle który okazał się niezbędny do szybkiej implementacji szyfrowania wykorzystanego w procesie ‚OAuth Dance’.
  3. W ostatnim artykule z serii przedstawimy przykład wykorzystania Jira API do utworzenia własnego zgłoszenia w Jira z aplikacji Oracle APEX.

Co to jest OAuth i „OAuth Dance”?

Autoryzacja z Jira może odbyć się na dwa sposoby. Z wykorzystaniem Basic Authentication oraz OAuth 1.0. Każdy z nich ma swoje wady i zalety. Pierwszy jest bardzo prosty, jednak w nagłówku żądania wysyłamy zakodowany login i hasło użytkownika. Drugi z kolei jest bardziej skomplikowany w implementacji ale to właśnie na nim skupimy się w tym artykule.

OAuth jest standardem autoryzacji, który pozwala użytkownikowi udostępniać aplikacjom informacje przechowywane u innych dostawców usług bez podawania hasła. Cały proces odbywa się za pomocą wymiany tokenów które otrzymuje się w odpowiedzi na żądanie HTTP wysłane na konkretny adres (tabela poniżej). Proces ten jest znany jako „OAuth Dance” i można go opisać w trzech krokach:

  1. Użytkownik za pośrednictwem Request Token URL zgłasza żądanie o wygenerowanie Request Token.
  2. Użytkownik zostaje przekierowany do Authorize URL aby autoryzować wcześniej otrzymany Request Token.
  3. Użytkownik za pośrednictwem Access Token URL, zgłasza żądanie o wygenerowanie Access Token. Za pomocą Access Token może przetwarzać dane udostępnione przez Jirę (Jira API).
Request Token URL /jira/plugins/servlet/oauth/request-token
Authorize URL /jira/plugins/servlet/oauth/authorize
Access Token URL /jira/plugins/servlet/oauth/access-token

Aby dowiedzieć się więcej na temat „OAuth Dance” warto zapoznać się z dokumentacją Jiry: https://developer.atlassian.com/cloud/jira/platform/jira-rest-api-oauth-authentication/

W kolejnej części artykułu przejdziemy już od teorii do praktyki i opiszemy poszczególne kroki „OAuth Dance” od strony technicznej.

„OAuth Dance”: kilka szczegółów na początek

Wysłanie żądania i odbiór odpowiedzi odbywa się za pomocą protokołu HTTP. Do ich implementacji wykorzystamy bibliotekę PL/SQL utl_http. Najważniejszą rzeczą będzie poprawne definiowanie nagłówków w treści żądania które pozwoli nam na uzyskanie odpowiedniego tokena.

„OAuth Dance” krok 1: Request Token & Przekierowanie do Authorization URL

Uzyskanie Request Tokena jest pierwszym krokiem „OAuth Dance”. W żądaniu HTTP typu POST musimy zdefiniować podstawowe nagłówki takie jak User-Agent oraz Content-Type. Nagłówek Authorization powinien zawierać parametry przedstawione w przykładzie poniżej, co zapewni nam wykorzystanie standardu OAuth:

Zatrzymajmy się na chwilę przy sygnaturze. Wszystkie żądania muszą zostać podpisane kluczem prywatnym (znajdującym się po stronie naszej aplikacji), a następnie zweryfikowane za pomocą klucza publicznego (znajdującego się po stronie Jiry). OAuth definiuje trzy metody podpisu: HMAC-SHA1, RSA-SHA1 oraz PLAINTEXT jednak Jira korzysta tylko z RSA-SHA1. Tak więc sygnatura to nic innego jak zbiór połączonych parametrów (tzw. base string) podpisany kluczem prywatnym. Base string możemy utworzyć w sposób przedstawiony poniżej natomiast więcej o implementacji samej sygnatury opowiemy w następnym artykule.

Po wysłaniu żądania otrzymamy odpowiedź zawierającą Request Token:

„OAuth Dance” krok 2: Autoryzacja

Po wygenerowaniu Request Token, powinien zostać on dodany do Authorization URL:/jira/plugins/servlet/oauth/authorize?oauth_token=DdNCjYhyOfUdHUDXnYqc3RVPN2MqYy3d. Opisany URL przekierowuje do ekranu autoryzacji:

Po wybraniu przycisku Allow nastąpi przekierowanie do adresu URL zdefiniowanego za pomocą parametru oauth_callback w kroku 1. Dodatkowo do URL zostanie dodany parametr oauth_verifier który posłuży do uzyskania Access Token w kolejnym kroku.

„OAuth Dance” krok 3: Access Token

Na tym etapie posiadamy już wygenerowany Request Token oraz przeszliśmy proces autoryzacji czego efektem jest wygenerowany parametr oauth_verifier. Jedyne co nam pozostaje to wysłanie żądania o wygenerowanie Access Token który pozwoli nam na dowolne przetwarzanie danych w Jirze. Żądanie powinno być utworzone według przykładu przedstawionego w kroku 1. Jedyne zmiany to adres URL: /jira/plugins/servlet/oauth/access-token, brak parametru oauth_callback oraz dwa nowe parametry w nagłówku Authorization: 

  • oauth_token – Request Token zwrócony w odpowiedzi żądania w kroku 1
  • oauth_verifier – parametr zwrócony po autoryzacji w kroku 2

Musimy również pamiętać o modyfikacji parametrów użytych do utworzenia Base String który musi zostać podpisany kluczem prywatnym.

W wyniku wysłania żądania otrzymamy odpowiedź zawierającą Access Token:

Podsumowanie

W artykule opisaliśmy standard autoryzacji OAuth 1.0 oraz przedstawiliśmy proces wymiany tokenów w „OAuth Dance”. Do implementacji użyliśmy bibliotek języka PL/SQL co pozwala nam na wykorzystanie przedstawionych przykładów w procesach Oracle APEX. W kolejnym artykule opiszemy bardziej szczegółowo problem sygnatury i samego jej podpisu w Oracle.  

Tagi: , , ,

Zapraszamy do kontaktu!

Pretius jest firmą tworząca oprogramowanie wspierające biznes.
Tworzymy aplikacje webowe wykorzystując: Java, Oracle DB, Oracle Apex, AngularJS.
Skontaktuj się z nami, aby porozmawiać o tym jak możemy pomóc w realizacji Twojego projektu!