Instrukcja techniczna - zamowienia.mazovia.pl

Transkrypt

Wydatek współfinansowany przez Unię Europejską ze środków Europejskiego Funduszu Rozwoju Regionalnego
w ramach Regionalnego Programu Operacyjnego Województwa Mazowieckiego 2007-2013
ESB
Instrukcja techniczna
Strona 1 z 29
ESB
SPIS TREŚCI.
1.
Wstęp. ........................................................................................... 3
1.1
Cel dokumentu. .............................................................................. 3
1.2
Warunki początkowe. ....................................................................... 3
1.3
Referencje do innych dokumentów. ................................................... 4
2.
Budowanie źródeł aplikacji serwera ................................................... 4
2.1
Zmiany w źródłach .......................................................................... 4
2.1.1
Aktualizacja modułu logowania jboss-logging do wersji 2.1.1.GA ..... 4
2.1.2
Kompilacja źródeł serwera JBOSS ................................................ 5
3.
Budowanie źródeł szyny ESB ............................................................ 6
3.1
Zmiany w źródłach .......................................................................... 6
3.2
Kompilacja źródeł szyny ESB ............................................................ 7
4.
Zmiana silnika JBoss-WS-Native na JBoss-WS-CXF 3.4.0 ..................... 7
5.
Konfiguracja regionalnej szyny ESB z serwerem bazy danych MSSQL .... 8
6.
Konfiguracja lokalnej szyny ESB z serwerem bazy danych PostgreSQL . 10
7.
Wdrożenie szyny ESB na serwer JBoss ............................................. 11
8.
Usługi ESB - struktura źródeł aplikacji.............................................. 12
8.1
Warunki początkowe ...................................................................... 12
8.2
Założenia wynikające z wymagań .................................................... 12
8.3
Mechanizm podpisywania kopert SOAP w oparciu o silnik WSS4j ......... 13
8.4
Schemat ogólny struktury usługi ESB .............................................. 13
8.5
Usługi ESB ................................................................................... 14
8.5.1
Usługi dynamicznie routowane .................................................. 20
8.5.2
Usługi typu SOAP Proxy ............................................................ 21
8.5.3
Konfiguracja SSL usługi ............................................................ 22
8.5.4
Konfiguracja WS-Security usługi ................................................ 23
8.5.5
Konfiguracja ról dostępowych do usługi ...................................... 26
9.
Dodanie nowej usługi ESB .............................................................. 27
10.
Kompilacja źródeł usług ESB ........................................................... 27
Strona 2 z 29
ESB
1. Wstęp.
1.1 Cel dokumentu.
Celem dokumentu jest przekazanie wiedzy programistycznej w zakresie zmian
wykonanych w źródłach serwera JBoss oraz szyny ESB, aktualizacji bibliotek
silnika usług sieciowych JBoss-WS-CXF, a także implementacji, testowania i
wdrożenia usług centralnych oraz lokalnych na szynie ESB.
1.2 Warunki początkowe.
Osoba wykonująca jakiekolwiek prace związane z implementacją usług powinna
posiadać ogólną wiedzę programistyczną z zakresu specyfikacji Java EE 5/6. W
szczególności wymagana jest wiedza z zakresu:
język programowania JAVA,
implementacja usług sieciowych w oparciu o silnik Apache CXF z
wykorzystaniem mechanizmów zabezpieczeń WS-Security, w tym
podpis
elektroniczny,
a
także
standardowe
uwierzytelnienie
(login/haslo) w kopercie SOAP,
JMS Server i konfiguracja kolejek JMS.
Wymagana dodatkowa wiedza z zakresu administracji systemem operacyjnym,
obsługi plików XML oraz XSD, a także generowaniem i podpisywaniem
certyfikatem kopert SOAP.
Wymagana również wiedza z zakresu przesyłania informacji protokołami:
HTTP,
szyfrowanym HTTP,
SOAP,
a także wykorzystania interfejsów REST.
Wymagana wiedza ogólna z zakresu konfiguracji i wdrożenia usług na szynie
ESB.
Zakłada się również, że środowisko pracy ze
skonfigurowane. Poprawna konfiguracja obejmuje:
źródłami
jest
poprawnie
instalację środowiska uruchomieniowego JAVA,
Strona 3 z 29
ESB
instalację narzędzi do automatycznego budowania MAVEN oraz ANT,
instalację środowiska deweloperskiego Eclipse lub JBoss Developers
Studio.
Wykorzystane wersje oprogramowania:
Oprogramowanie
Wersja
JAVA JDK
jdk1.6.0_45
MAVEN
apache-maven-2.2.1
ANT
apache-ant-1.7.1
JBoss Developers Studio
jbdevstudio-product-universal5.0.0.v20120615-1714-H213GA.jar
1.3 Referencje do innych dokumentów.
Podręcznik Administratora ESB
2. Budowanie źródeł aplikacji serwera
2.1 Zmiany w źródłach
2.1.1 Aktualizacja modułu logowania jboss-logging do
wersji 2.1.1.GA
Aktualizacja modułu logowania umożliwi łatwiejsze zarządzanie logami usług ESB
oraz samego serwera JBOSS.
Modyfikacja obejmuje zmianę wersji bibliotek logowania w pliku
konfiguracyjnym: /jboss-5.1.0.GA-src/component-matrix/pom.xml
<dependency>
<groupId>org.jboss.logging</groupId>
<artifactId>jboss-logging-spi</artifactId>
<version>2.1.1.GA</version>
</dependency>
<dependency>
<artifactId>jboss-logging-jdk</artifactId>
</dependency>
<dependency>
Strona 4 z 29
ESB
<artifactId>jboss-logging-log4j</artifactId>
<exclusions>
<exclusion>
<groupId>apache-log4j</groupId>
<artifactId>log4j</artifactId>
</exclusion>
</exclusions>
</dependency>
Po zmianie wymagane jest przebudowanie aplikacji zgodnie z sekcją Kompilacja
źródeł serwera.
2.1.2 Kompilacja źródeł serwera JBOSS
Warunki początkowe:
zainstalowane narzędzie ANT, widoczne z linii komend
zainstalowane środowisko uruchomieniowe JAVA
dostęp do internetu
Konfiguracja repozytorium JBoss
Należy zweryfikować konfigurację publicznych repozytorium czy zawierają listę
poniższych serwerów. Gdyby, któryś z serwerów był niedostępny należy znaleźć
inne publiczne repozytorium zawierające niezbędne biblioteki i dodać je do listy
repozytoriów.
Konfiguracja publicznych repozytoriów znajduje się w pliku pom.xml, w głównym
katalogu archiwum jboss-5.1.0.GA-modified-src.zip:
<repositories>
<repository>
<id>jboss-public-repository-group</id>
<name>JBoss Public Repository Group</name>
<url>http://repository.jboss.org/nexus/content/groups/public/</url>
<layout>default</layout>
<releases>
<enabled>true</enabled>
<updatePolicy>never</updatePolicy>
</releases>
<snapshots>
</snapshots>
</repository>
<repository>
<id>jboss-deprecated</id>
<name>JBoss
Strona 5 z 29
ESB
Deprecated</name>
d/</url>
<url>https://repository.jboss.org/nexus/content/repositories/deprecate
<releases>
</releases>
<snapshots>
<enabled>false</enabled>
</snapshots>
</repository>
<repository>
<id>jboss-maven2-brew</id>
<name>JBoss Maven 2 Brew Repository</name>
<url>http://repository.jboss.org/maven2-brew/</url>
<releases>
</releases>
<snapshots>
<enabled>false</enabled>
</snapshots>
</repository>
</repositories>
W celu kompilacji źródeł serwera JBOSS należy:
znajdować się w katalogu z źródłami aplikacji serwera
[JBOSS_5.1.0.GA_SRC_HOME]/build
wykonać poniższe polecenie w celu usunięcia katalogu wynikowego
ant clean
wykonać poniższe polecenie w celu kompilacji źródeł
ant
3. Budowanie źródeł szyny ESB
3.1 Zmiany w źródłach
W celu poprawy błędu obsługi kopert SOAP w wersji 1.2 wprowadzono zmiany w
klasach
org.jboss.soa.esb.services.security.auth.ws.SoapConstants
oraz
Strona 6 z 29
ESB
org.jboss.soa.esb.services.security.auth.ws.SoapExtractionUtil. Należy podmienić
pliki znajdujące się w katalogu:
jbossesb-4.11-modifiedsrc.zip/trunk/product/rosetta/src/org/jboss/soa/esb/services/security/auth/ws/
na pliki z katalogu esb_modified.
3.2 Kompilacja źródeł szyny ESB
W celu kompilacji źródeł szyny ESB należy:
znajdować się w katalogu:
[JBOSSESB_4.11_SRC_HOME]/product
wykonać poniższe polecenie w celu usunięcia katalogu wynikowego
ant clean
wykonać poniższe polecenie w celu kompilacji źródeł
ant dist
4. Zmiana silnika JBoss-WS-Native na JBossWS-CXF 3.4.0
Warunki początkowe:
zainstalowane narzędzie ANT, widoczne z linii komend
zainstalowane środowisko uruchomieniowe JAVA
Przejść do folderu głównego aktualizacji (do którego została rozpakowana
zawartość jbossws-cxf-3.4.0.GA.zip):
[jbossws-cxf-bin-dist]
Skonfigurować:
ścieżkę do domowego folderu serwera JBoss w pliku konfiguracyjnym
./ant.properties (usunąć fragment rozszerzenia pliku .example):
jboss510.home <- w sekcji # Optional JBoss Home
np. jboss510.home=D:/UMWM/ESB/src/ws/jboss-5.1.0.GA
profil konfiguracji serwera w sekcji # The JBoss settings:
jboss.server.instance
np. jboss.server.instance=all
Strona 7 z 29
ESB
Polecenie wdrożenia aktualizacji silnika WS (wykonać z poziomu folderu
[jbossws-cxf-bin-dist]):
ant -Djboss.server.instance=all deploy-jboss510
5. Konfiguracja
regionalnej
szyny
ESB
z
serwerem bazy danych MSSQL
W celu konfiguracji szyny ESB z SZBD (Systemem Zarządzania Bazą Danych)
MSSQL należy usunąć konfigurację domyślną bazy Hypersonic oraz dostarczyć
odpowiednią konfigurację dla bazy MSSQL.
Należy usunąć foldery:
./jboss-5.1.0.GA/server/default
./jboss-5.1.0.GA/server/minimal
./jboss-5.1.0.GA/server/standard
./jboss-5.1.0.GA/server/web
Należy usunąć pliki:
./jboss-5.1.0.GA/server/all/hsqldb-ds.xml
./jboss-5.1.0.GA/server/all/deploy/messaging/hsqldb-persistenceservice.xml
Do katalogu ./jboss-5.1.0.GA/server/all/deploy/messaging/ należy skopiować plik
konfiguracyjny dedykowany dla SZBD MSSQL: mssql-persistence-service.xml z
katalogu mssql
Następnie należy podmienić poniższe pliki na ich odpowiedniki dedykowane dla
SZBD MSSQL (znajdują się one w katalogu mssql):
./jboss-5.1.0.GA/server/all/deploy/jbpm.esb/jbpm-service.xml
./jboss-5.1.0.GA/server/all/deploy/jbpm.esb/hibernate.cfg.xml
./jboss-5.1.0.GA/server/all/deploy/jbossesb.esb/jbossesb-service.xml
./jboss-5.1.0.GA/server/all/deploy/jbossesb-registry.sar/juddi_config/METAINF/persistence.xml
Konfiguracja sterownika JDBC dla wybranej wersji MSSQL:
Skopiować do katalogu ./ jboss-5.1.0.GA/server/all/lib plik sqljdbc4.jar z
katalogu mssql.
Konfiguracja połączenia do wybranej bazy danych została umieszczona w plikach
konfiguracyjnych w kilku lokalizacjach:
1. Konfiguracja DataSource dla instancji bazy danych localDB serwera
JBoss oraz pozostałych źródeł danych dla aplikacji wdrażanych na
serwer:
Strona 8 z 29
ESB
$JBOSS_HOME/server/all/deploy/mssql-ds.xml
2. Konfiguracja DataSource dla juddiDB - rejestru serwisów ESB:
$JBOSS_HOME/server/all/deploy/jbossesb-registry.sar/juddi-ds.xml
3. Konfiguracja DataSource dla instancji bazy danych jbossesb - źródła
danych dla szyny ESB, składowania kolejek JMS oraz innych danych
konfiguracyjnych:
$JBOSS_HOME/server/all/deploy/jbossesb.esb/message-store-ds.xml
Konfiguracja przewiduje utworzenie struktur DB w pustych bazach danych
podczas pierwszego rozruchu serwera. Wymagane jest aby utworzyć puste
instancje baz danych (localDB, juddiDB, jbossesb) w systemie zarządzania bazą
danych oraz przypisać do nich odpowiedniego użytkownika – ‘jbossesb’.
Opcjonalna konfiguracja bazy danych dla katalogu raportów wymaga, aby w
SZBD utworzyć bazę danych o nazwie esblogging oraz wykonać na niej
dostarczony skrypt mssql_create.sql. Konfiguracja przechowywana jest w pliku
konfiguracyjnym mechanizmów logowania na serwerze JBoss (jboss-log4j.xml).
W celu nawiązania komunikacji z bazą danych MSSQL należy w plikach
konfiguracyjnych (wymienionych powyżej) ustawić wskazane atrybuty (w
zależności od pliku mogą być dostępne różne, wymienione niżej atrybuty):
Konfiguracja URL połączenia z instancją DB:
connection-url
jdbc:sqlserver://[HOST]:[PORT];DatabaseName=[DATABASE_NAME]
Klasa sterownika dla MSSQL:
driver-class
com.microsoft.sqlserver.jdbc.SQLServerDriver
Użytkownik administracyjny
user-name
[NAZWA_UZYTKOWNIKA]
Hasło użytkownika:
password
[HASLO_UZYTKOWNIKA]
Mapowanie typów metadanych w wybranej wersji MSSQL:
type-mapping
MS SQLSERVER2000
URL
jdbc:sqlserver://[HOST]:[PORT];DatabaseName=[DATABASE_NAME]
Klasa sterownika dla MSSQL:
driver
com.microsoft.sqlserver.jdbc.SQLServerDriver
user
[NAZWA_UZYTKOWNIKA]
password
[HASLO_UZYTKOWNIKA]
Strona 9 z 29
ESB
6. Konfiguracja lokalnej szyny ESB z serwerem
bazy danych PostgreSQL
W celu konfiguracji szyny ESB z SZBD PostgreSQL należy usunąć konfigurację
domyślną bazy Hypersonic oraz dostarczyć odpowiednią dla bazy PostgreSQL.
Należy usunąć foldery:
./jboss-5.1.0.GA/server/default
./jboss-5.1.0.GA/server/minimal
./jboss-5.1.0.GA/server/standard
./jboss-5.1.0.GA/server/web
Należy usunąć pliki:
./jboss-5.1.0.GA/server/all/hsqldb-ds.xml
./jboss-5.1.0.GA/server/all/deploy/messaging/hsqldb-persistenceservice.xml
Do katalogu ./jboss-5.1.0.GA/server/all/deploy/messaging/ skopiować plik
konfiguracyjny dedykowany dla SZBD PostgreSQL o nazwie postgresqlpersistence-service.xml z katalogu postgresql
Następnie należy podmienić poniższe pliki na ich odpowiedniki dedykowane dla
SZBD PostgreSQL (znajdują się w katalogu postgresql):
./jboss-5.1.0.GA/server/all/deploy/jbpm.esb/jbpm-service.xml
./jboss-5.1.0.GA/server/all/deploy/jbpm.esb/hibernate.cfg.xml
./jboss-5.1.0.GA/server/all/deploy/jbossesb.esb/jbossesb-service.xml
./jboss-5.1.0.GA/server/all/deploy/jbossesb-registry.sar/juddi_config/METAINF/persistence.xml
Konfiguracja sterownika JDBC dla wybranej wersji PostgreSQL 9.1:
Skopiować do katalogu ./jboss-5.1.0.GA/server/all/lib plik postgresql-9.1903.jdbc4.jar z katalogu postgresql.
Konfiguracja połączenia do wybranej bazy danych została umieszczona w plikach
konfiguracyjnych w kilku lokalizacjach:
1.
Konfiguracja DataSource dla instancji bazy danych localDB serwera
JBoss oraz pozostałych źródeł danych dla aplikacji wdrażanych na serwer :
$JBOSS_HOME/server/all/deploy/postgresql-ds.xml
2.
Konfiguracja DataSource dla juddiDB - rejestru serwisów ESB:
$JBOSS_HOME/server/all/deploy/jbossesb-registry.sar/juddi-ds.xml
3.
Konfiguracja DataSource dla instancji bazy danych jbossesb - źródła
danych dla szyny ESB, składowania kolejek JMS oraz innych danych
konfiguracyjnych:
Strona 10 z 29
ESB
$JBOSS_HOME/server/all/deploy/jbossesb.esb/message-store-ds.xml
Konfiguracja przewiduje utworzenie struktur DB w pustych bazach danych
podczas pierwszego rozruchu serwera. Wymagane jest aby utworzyć puste
instancje baz danych (localDB, juddiDB, jbossesb) w systemie zarządzania bazą
danych oraz przypisać do nich odpowiedniego użytkownika – ‘jbossesb’.
Opcjonalna konfiguracja bazy danych dla katalogu raportów wymaga, aby w
SZBD utworzyć bazę danych o nazwie esblogging oraz wykonać na niej
dostarczony skrypt postgresql_create.sql. Konfiguracja przechowywana jest w
pliku konfiguracyjnym mechanizmów logowania na serwerze JBoss (jbosslog4j.xml).
W celu nawiązania komunikacji z bazą danych PostgreSQL należy w plikach
konfiguracyjnych (wymienionych powyżej) ustawić wskazane atrybuty (w
zależności od pliku mogą być dostępne różne, wymienione niżej atrybuty):
connection-url
jdbc:postgresql://[HOST]:[PORT]/[NAZWA_BAZY_DANYCH]
Klasa sterownika dla PostgreSQL:
driver-class
org.postgresql.Driver
user-name
[NAZWA_UZYTKOWNIKA]
password
[HASLO_UZYTKOWNIKA]
Mapowanie typów metadanych w wybranej wersji PostgreSQL:
type-mapping
PostgreSQL 8.0
URL
jdbc:postgresql://[HOST]:[PORT]/[NAZWA_BAZY_DANYCH]
Klasa sterownika dla PostgreSQL:
driver
org.postgresql.Driver
user
[NAZWA_UZYTKOWNIKA]
password
[HASLO_UZYTKOWNIKA]
7. Wdrożenie szyny ESB na serwer JBoss
W celu wdrożenia szyny ESB na serwer JBoss należy w pierwszej kolejności
przeprowadzić konfigurację ścieżki do serwera w pliku konfiguracyjnym:
jbossesb-4.11-modified-src.zip\trunk\product\install\deployment.properties
Następnie należy wykonać poniższe operacje:
Zmienić
rozszerzenie
pliku
jbossesb-4.11-modifiedsrc.zip\trunk\product\install\deployment.properties-example
na
deployment.properties
Skonfigurować właściwości:
Strona 11 z 29
ESB
o org.jboss.esb.server.home=D:/BGWM/ESB/src/cxf/jboss-5.1.0.GA
o Profil serwera: org.jboss.esb.server.config=all
Wykonać komendę (z poziomu folderu instalacyjnego ./jbossesb/install/):
ant deploy
8. Usługi ESB - struktura źródeł aplikacji
8.1 Warunki początkowe
Serwer i szyna ESB są poprawnie zainstalowane, połączone z zewnętrznym
systemem bazy danych.
8.2 Założenia wynikające z wymagań
Dostęp do usług ESB chroniony jest podpisem koperty SOAP przy
użyciu certyfikatu prywatnego oraz oznaczeniem koperty czasem
wygenerowania żądania. Podpis obejmuje sekcje nagłówka koperty
SOAP w zależności od usługi (Timestamp, BinarySecurityToken, Body
lub bez sekcji BinarySecurityToken),
Usługa ESB dostępna na szynie ESB poprzez przedstawienie się
prywatnym certyfikatem wygenerowanym przez Lokalne Centrum
Certyfikacji,
Komunikacja po szyfrowanym protokole HTTP,
Zgodność ze specyfikacją WS-Metadata-Exchange,
Transparentność WSDL wystawianej usługi, niezależnie od tego czy
usługa jest zewnętrzna, czy wewnętrzna,
Zgodność z SOAP 1.1, SOAP 1.2,
Zgodność wersji WSS4J oraz XML-Security pomiędzy szyną ESB,
serwerem JBoss oraz bibliotekami usług sieciowych JBoss-WS-CXF
3.4.0.
Strona 12 z 29
ESB
8.3 Mechanizm podpisywania kopert SOAP w oparciu o
silnik WSS4j
W celu realizacji wymagania zabezpieczenia przesyłanych wiadomości podpisem
elektronicznym został zaimplementowany mechanizm podpisywania i weryfikacji
przesyłanych kopert SOAP na poziomie łańcucha akcji usługi ESB. Koperta
zawierająca podpis elektroniczny podlega weryfikacji na poziomie mechanizmu
logowania operacji wykonywanych przez szynę ESB. Dzięki temu uzyskujemy
informację o tym, kto przesyła wiadomość i czy ma odpowiednie prawa do
korzystania z funkcjonalności usługi ESB. Moduł podpisujący jest częścią wspólną
wszystkich usług ESB, zarówno na szynie centralnej, jak i na szynach lokalnych.
Moduł podpisu obsługuje koperty SOAP w wersji 1.1 oraz 1.2.
8.4 Schemat ogólny struktury usługi ESB
[/ESB_SERVICE_NAME.esb]
| jbm-queue-service.xml
| jbossesb-properties.xml
| log4j.properties
----lib
|
[esb-common-utils].jar
|
----META-INF
| | [PROXY_WSDL].wsdl
| | crypto_[system]_client_check.properties
| | crypto_[system]_client_request.properties
| | crypto_[system]_client_response.properties
| | deployment.xml
| | https-443.properties
| | jboss-classloading.xml
| | jboss-esb.xml
| | MANIFEST.MF
| |---maven
|
|---com.comarch.umwm.esb.services
|
|---[ESB_SERVICE_PROJECT_NAME]
|
pom.properties
|
pom.xml
|---pl
|---gov
|--- ...
Objaśnienia:
.
W folderze głównym usługi znajduje
się konfiguracja kolejek JMS (dla
komunikacji synchronicznej
Strona 13 z 29
ESB
/lib
META-INF
/maven
/pl/gov/...
żądanie/odpowiedź) usługi (plik jbmqueue-service.xml) oraz parametrów
dodatkowych, dedykowanych dla
wdrożonej usługi (jbossesbproperties.xml), a także konfiguracja
mechanizmu logowania log4j dla
usługi.
Folder przechowuje biblioteki zależne,
wymagane do wdrożenia i
poprawnego działania usługi na
szynie ESB
Folder przechowuje kluczową
konfigurację usługi. Istotnym plikiem
konfiguracyjnym jest jboss-esb.xml,
który zawiera definicję oraz opis
funkcjonalny usługi ESB. W celu
poprawnego wdrożenia usługi
wymagane jest również dodanie pliku
wdrożenia, który stanowi o kolejności
ładowania zależności usługi
(deployment.xml). Pozostała
konfiguracja dotyczy konfiguracji
klienta HTTP, którego wewnętrznie
wykorzystuje usługa do komunikacji z
systemami zewnętrznymi (https443.properties). Pozostałe
właściwości dotyczą mechanizmu
podpisu elektronicznego wiadomości,
przechowują konfigurację
certyfikatów dla podpisu oraz jego
weryfikacji.
Niektóre usługi mogą wymagać
ustawienia izolacji ładowania
zależnych bibliotek w oparciu o
odpowiedni poziom ClassLoader'a
(jboss-classloading.xml).
Informacje o zależnościach źródeł dla
procesu automatycznego budowania
aplikacji.
Skompilowane klasy funkcji, które
realizuje usługa ESB.
8.5 Usługi ESB
Usługi ESB zostały zintegrowane z bramką HTTP oraz kolejkami JMS, które
stanowią punkt dostępowy do usługi odpowiednio z zewnątrz oraz z wewnątrz
Strona 14 z 29
ESB
szyny ESB. Bramka HTTP umożliwia przyjęcie przez szynę wiadomości w
formacie niezrozumiałym jeszcze przez szynę ESB, z kolei JMS przyjmuje
wiadomość zrozumiałą dla szyny, mechanizmy konwersji zapewniają poprawną
transformację wiadomości pomiędzy punktami dostępowymi.
Każda usługa została zintegrowana z rozbudowanym modułem weryfikacji
certyfikatów, zapewniającym uwierzytelnienie klientów usług na podstawie
podpisu wiadomości.
Usługi zostały podzielone na publiczne i prywatne. Do realizacji grupowania usług
został wykorzystany mechanizm ról dostępowych powiązanych z klientami usług,
który jest częścią składową rozszerzonego modułu uwierzytelniania klientów
usług poprzez prywatny certyfikat. W środowisku projektowym wszystkie usługi
mają status public.
Kolejny podział usług niewynikający z ról dostępowych uwzględnia centralne oraz
lokalne usługi ESB, zgodnie z podziałem infrastruktury ESB dla opracowywanego
systemu.
Każda usługa przechowuje fizyczny plik WSDL, który jest skonfigurowany jako
parametr wejściowy akcji SOAPProxy lub DynamicEndpointProxyAction. Plik
WSDL przechowuje adres końcowy/dostępowy do zewnętrznej usługi.
Przykład pliku WSDL:
<?xml version="1.0" encoding="UTF-8"?>
<wsdl:definitions targetNamespace="http://userinfo.zp.epuap.gov.pl"
xmlns:impl="http://userinfo.zp.epuap.gov.pl"
xmlns:intf="http://userinfo.zp.epuap.gov.pl"
xmlns:tns2="http://sign.zp.comarch.gov"
xmlns:tns3="http://exception.userinfo.zp.epuap.gov.pl"
xmlns:wsaw="http://www.w3.org/2006/05/addressing/wsdl"
xmlns:wsdl="http://schemas.xmlsoap.org/wsdl/"
xmlns:wsdlsoap="http://schemas.xmlsoap.org/wsdl/soap/"
xmlns:wsi="http://ws-i.org/profiles/basic/1.1/xsd"
xmlns:xsd="http://www.w3.org/2001/XMLSchema">
<wsdl:types>
<schema targetNamespace="http://userinfo.zp.epuap.gov.pl"
xmlns="http://www.w3.org/2001/XMLSchema"
xmlns:tns2="http://sign.zp.comarch.gov"
Strona 15 z 29
ESB
<import namespace="http://sign.zp.comarch.gov" />
<element name="getTpUserInfoResponse">
<complexType>
<sequence>
<element
name="getTpUserInfoReturn"
nillable="true"
type="tns2:TpUserInfo" />
</sequence>
</complexType>
</element>
<element name="getTpUserInfo">
<complexType>
<sequence>
<element
name="tgsid"
nillable="true"
<element
name="systemOrganisationId"
type="xsd:string" />
nillable="true" type="xsd:string" />
</sequence>
</complexType>
</element>
</schema>
<schema
targetNamespace="http://sign.zp.comarch.gov"
<complexType name="TpUserInfo">
<sequence>
Strona 16 z 29
ESB
<element
nillable="true" type="xsd:string" />
<element
name="accountEmailAddress"
name="claimedRole"
nillable="true"
</sequence>
</complexType>
</schema>
<schema
targetNamespace="http://exception.userinfo.zp.epuap.gov.pl"
<complexType name="TpUserInfoException">
<sequence>
<element
name="message"
nillable="true"
</sequence>
</complexType>
<element name="TpUserInfoException" nillable="true"
type="tns3:TpUserInfoException" />
</schema>
</wsdl:types>
<wsdl:message name="getTpUserInfoResponse">
<wsdl:part
name="parameters" />
element="intf:getTpUserInfoResponse"
</wsdl:message>
<wsdl:message name="getTpUserInfoRequest">
<wsdl:part element="intf:getTpUserInfo" name="parameters" />
</wsdl:message>
Strona 17 z 29
ESB
<wsdl:message name="TpUserInfoException">
<wsdl:part element="tns3:TpUserInfoException" name="fault" />
</wsdl:message>
<wsdl:portType name="TpUserInfoService">
<wsdl:operation name="getTpUserInfo">
<wsdl:input
name="getTpUserInfoRequest" />
<wsdl:output
name="getTpUserInfoResponse" />
<wsdl:fault
name="TpUserInfoException" />
message="intf:getTpUserInfoRequest"
message="intf:getTpUserInfoResponse"
message="intf:TpUserInfoException"
</wsdl:operation>
</wsdl:portType>
<wsdl:binding
type="intf:TpUserInfoService">
name="TpUserInfoServiceSoapBinding"
<wsaw:UsingAddressing wsdl:required="false" />
<wsdlsoap:binding style="document"
transport="http://schemas.xmlsoap.org/soap/http" />
<wsdl:operation name="getTpUserInfo">
<wsdlsoap:operation soapAction="getTpUserInfo" />
<wsdl:input name="getTpUserInfoRequest">
<wsdlsoap:body use="literal" />
</wsdl:input>
<wsdl:output name="getTpUserInfoResponse">
<wsdlsoap:body use="literal" />
</wsdl:output>
<wsdl:fault name="TpUserInfoException">
Strona 18 z 29
ESB
<wsdlsoap:fault
name="TpUserInfoException"
use="literal" />
</wsdl:fault>
</wsdl:operation>
</wsdl:binding>
<wsdl:service name="TpUserInfoServiceService">
<wsdl:port
name="TpUserInfoService">
binding="intf:TpUserInfoServiceSoapBinding"
<wsdlsoap:address
location="https://test.epuap.gov.pl:443/zp_userinfo_external_ws/
services/TpUserInfoService" />
<wsp:PolicyReference URI="#x509SecuritySignPolicy"
xmlns:wsp="http://schemas.xmlsoap.org/ws/2004/08/policy" />
</wsdl:port>
</wsdl:service>
<wsp:UsingPolicy Required="true"
xmlns:wsp="http://schemas.xmlsoap.org/ws/2004/08/policy" />
<wsp:Policy wsu:Id="x509SecuritySignPolicy"
xmlns:wsp="http://schemas.xmlsoap.org/ws/2004/08/policy"
xmlns:wsu="http://docs.oasis-open.org/wss/2004/01/oasis200401-wss-wssecurity-utility-1.0.xsd">
<wsp:ExactlyOne>
<wsse:SecurityToken
xmlns:wsse="http://schemas.xmlsoap.org/ws/2002/12/secext">
<wsse:TokenType>
"http://docs.oasis-open.org/wss/2004/01/oasis200401-wss-x509-token-profile-1.0#X509v3"
</wsse:TokenType>
Strona 19 z 29
ESB
</wsse:SecurityToken>
</wsp:ExactlyOne>
</wsp:Policy>
</wsdl:definitions>
8.5.1 Usługi dynamicznie routowane
Usługi dynamicznie routowane są typem usług, których odbiorca (endpoint) jest
zmienny w zależności od parametru przekazanego w kopercie SOAP. Ten typ
usług jest wykorzystywany m.in. przez usługę EZDStatusService. Dynamiczny
routing pozwolił znacznie ograniczyć liczbę usług ESB świadczonych przez szynę.
Dynamiczny mechanizm wyznaczania trasy został zrealizowany w oparciu o
rozbudowany mechanizm akcji SOAPProxy oraz rozbudowany mechanizm
publikowania kontraktu na szynie ESB. Programowe wywołanie usługi SOAPProxy
umożliwiło dynamiczną konfigurację docelowych punktów odbioru wiadomości.
Usługa dynamicznie routowana pobiera atrybut partnerId z nagłówka koperty
SOAP, a następnie odnajduję adres hosta z pliku konfiguracyjnego
partners.properties (JBOSS_HOME\server\all\conf\partners.properties).
Przykładowa zawartość pliku partners.properties:
TEST=TESTEURZAD-JST.wrotamazowsza.pl:8543
OSostroAndrzGW=OSTROANDRZGWVM1.wrotamazowsza.pl:8543
CPplonsBabosGW=PLONSBABOSGWVM1.wrotamazowsza.pl:8543
OSostroBaranGW=OSTROBARANGWVM1.wrotamazowsza.pl:8543
...
Pozostała konfiguracja jest zawarta w pliku jboss-esb.xml usługi (wewnątrz
archiwum *.esb\META-INF), gdzie zamiast akcji SOAPProxy należy podać
poniższy wpis:
<action name="WSDLContractPublisher"
class="pl.gov.ezd.esb.custom.actions.WSDLServiceContractPublisherActi
on">
<property
name="wsdl"
value="classpath:///METAINF/statusService.wsdl" />
</action>
<action class="pl.gov.ezd.esb.custom.actions.DynamicEndpointProxyAction"
name="request-action">
<property name="routeDestinations"
value="C:/comarch/szyna_esb/jboss5.1.0.GA/server/all/conf/partners.properties" />
<property name="file" value="/META-INF/https-443.properties" />
<property name="clientCredentialsRequired" value="false" />
Strona 20 z 29
ESB
<property name="protocol" value="https://" />
<property name="serviceEndpointUrl"
value="/esb-local-ezd-status-service/http/SOAP/EZDLocalStatusWS"
/>
</action>
Parametry:
wsdl - określa lokalizację pliku WSDL
routeDestinations – określa lokalizację pliku partners.properties
file – określa lokalizację pliku z konfiguracją dla połączenia HTTPS. Jest
to parametr opcjonalny
clientCredentialsRequired – parametr opcjonalny określający, czy
połączenie SSL wymaga clientCredentials
protocol – określa protokół adresu endpoint
serviceEndpointUrl – określa resztę ciągu adresu endpoint usługi.
Dla powyżej przykładowej konfiguracji jeśli do szyny ESB trafi koperta z
parametrem partnerId ustawionym na TEST, to koperta zostanie przekierowana
na adres https:// TESTEURZAD-JST.wrotamazowsza.pl:8543/esb-local-ezdstatus-service/http/SOAP/EZDLocalStatusWS, a nie na adres zawarty w pliku
WSDL, jak dla zwykłych akcji SOAP Proxy
8.5.2 Usługi typu SOAP Proxy
Usługi typu SOAP Proxy są najpopularniejsze i polegają na przekierowaniu
koperty wejściowej SOAP na inny adres endpoint. Adres endpoint jest pobierany
z sekcji address zawartej w pliku WSDL usługi.
Konfiguracja jest zawarta w pliku jboss-esb.xml (wewnątrz archiwum
*.esb\META-INF), usługi, gdzie w łańcuchu akcji należy podać poniższy wpis:
<action
name="proxy"
class="org.jboss.soa.esb.actions.soap.proxy.SOAPProxy">
<property
name="wsdl"
value="classpath:///METAINF/[PLIK_WSDL].wsdl" />
</action>
Parametry:
wsdl – określa lokalizację pliku WSDL z adresem endpoint proxowanej
usługi
file – opcjonalny parametr zawierający lokalizację pliku konfiguracyjnego
dla połączeń https
Strona 21 z 29
ESB
clientCredentialsRequired – opcjonalny parametr wykorzystywany dla
połączeń https. Określa czy połączenie SSL wymaga clientCredentials
8.5.3 Konfiguracja SSL usługi
Konfiguracja połączenia HTTPS polega na utworzeniu pliku https-443.properties
(wewnątrz archiwum *.esb\META-INF), modyfikacji akcji SOAP Proxy lub
DynamicEndpointProxyAction w łańcuchu akcji oraz zmiany protokołu w adresie
endpoint.
Plik https-443.properties ma poniższą składnię:
# HTTP Protocol config
configurators=pl.gov.epuap.protocol.config.EpuapProtocol
# SSLv3 socket factory
protocol-socketfactory=pl.gov.epuap.protocol.factory.SSL3ProtocolSocketFactory
# Keystore config
keystore=C:/comarch/szyna_esb/jboss-5.1.0.GA/server/all/conf/jboss.keystore
keystore-passw=changeit
# Truststore config
truststore=C:/comarch/szyna_esb/jboss-5.1.0.GA/server/all/conf/jboss.keystore
truststore-passw=changeit
# Connection config
connection-timeout=1000
host-name=TESTeUrzad-Portale.wrotamazowsza.pl
Parametry:
configurators oraz protocol-socket-factory – jest to parametr opcjonalny.
Wymusza on połaczenie SSL w wersji 3. Należy go używać wyłącznie dla
połączeń SSL, które udostępniają również starsze wersje protokołu SSL
keystore oraz trustowe – lokalizacja kontenera certyfikatów SSL
keystore-passwd oraz trustowe-passws – hasło do kontenerów
certyfikatów
connection-timeout – jest to parametr opcjonalny. Definiuje maksymalny
czas połączenia
host-name – jest to parametr opcjonalny z nazwą hosta SSL. Należy go
używać wyłącznie gdy nazwa hosta jest stała, np. dla SOAP Proxy. Nie
należy go używać dla DynamicEndpointProxyAction
Dla usługi typu SOAP Proxy należy w pliku jboss-esb.xml dodać dodatkowe
parametry file (określające lokalizację pliku z konfiguracją SSL) i
clientCredentialsRequired (parametr ten określa czy połączenie SSL wymaga
clientCredentials) oraz w pliku WSDL zmienić adres endpoint na protokół https
Np.:
Strona 22 z 29
ESB
<action
name="proxy"
<property
name="wsdl"
value="classpath:///METAINF/[PLIK_WSDL].wsdl" />
</action>
Dla usługi typu DynamicEndpointProxyAction należy w pliku jboss-esb.xml dodać
dodatkowy parametry file (określający lokalizację pliku z konfiguracją SSL) i
clientCredentialsRequired (parametr ten określa czy połączenie SSL wymaga
clientCredentials) oraz zmienić parametr protocol na ‘https://’
Np.:
<action class="pl.gov.ezd.esb.custom.actions.DynamicEndpointProxyAction"
name="request-action">
<property name="routeDestinations"
value="C:/comarch/szyna_esb/jboss5.1.0.GA/server/all/conf/partners.properties" />
<property name="protocol" value="https://" />
<property name="serviceEndpointUrl"
value="/esb-local-ezd-status-service/http/SOAP/EZDLocalStatusWS"
/>
</action>
8.5.4 Konfiguracja WS-Security usługi
Mechnizm WS-Security polega na dodawaniu elementu Timestamp oraz
podpisywaniu/weryfikacji elementu Body i Timestamp koperty SOAP. Typ
identyfikacji klucza jest ustawiany na: BinarySecurityToken
Dodanie WSSecurity do usługi ESB polega na utworzeniu 3 plików properties z
konfiguracją certyfikatów oraz dodaniu akcji do łańcucha akcji w pliku jbossesb.xml.
[ESB_SERVICE.esb]/META-INF/crypto_client_check.properties – weryfikacja
podpisu odpowiedzi sytemu zewnętrznego oraz żądania do szyny ESB
Zawartość:
Atrybut
org.apache.ws.security.crypto.provider
org.apache.ws.security.crypto.merlin.truststore.type
org.apache.ws.security.crypto.merlin.truststore.file
Opis
Komponent provider’a Apache
obsługujący kryptografię.
Typ pliku repozytorium
certyfikatów zaufanych.
Ścieżka względna/bezwzględna do
pliku.
Strona 23 z 29
ESB
org.apache.ws.security.crypto.merlin.truststore.password
timestamp.time.to.live
enable.signature.confirmation
Hasło do repozytorium zaufanych
certyfikatów.
Czas ważności znacznika czasu
Potwierdzenie weryfikacji podpisu.
[ESB_SERVICE.esb]/META-INF/crypto_client_request.properties – konfiguracja
dla podpisu żądania przesyłanego do systemu zewnętrznego
Zawartość:
Atrybut
org.apache.ws.security.crypto.merlin.keystore.type
org.apache.ws.security.crypto.merlin.file
Org.apache.ws.security.crypto.merlin.keystore.alias
org.apache.ws.security.crypto.merlin.keystore.password
Opis
certyfikatów.
pliku.
Alias certyfikatu z podpisem.
Hasło do repozytorium certyfikatów.
[ESB_SERVICE.esb]/META-INF/crypto_client_response.properties – konfiguracja
dla podpisu odpowiedzi z szyny ESB
Zawartość:
Atrybut
org.apache.ws.security.crypto.merlin.keystore.type
org.apache.ws.security.crypto.merlin.file
org.apache.ws.security.crypto.merlin.keystore.alias
org.apache.ws.security.crypto.merlin.keystore.password
Opis
certyfikatów.
pliku.
Alias certyfikatu z podpisem.
Hasło do repozytorium certyfikatów.
Przykładowa zawartość pliku:
org.apache.ws.security.crypto.provider=org.apache.ws.security.components.cryp
to.Merlin
org.apache.ws.security.crypto.merlin.keystore.type=JKS
org.apache.ws.security.crypto.merlin.keystore.password=123456
org.apache.ws.security.crypto.merlin.keystore.alias=central-signature-key
org.apache.ws.security.crypto.merlin.file=C:/comarch/szyna_esb/jboss5.1.0.GA/server/all/conf/esb.keystore
timestamp.time.to.live=300
enable.signature.confirmation=true
Strona 24 z 29
ESB
W łańcuchu akcji pliku jboss-esb.xml przed oraz po akcji proxującej (SOAPProxy
lub DynamicEndpointProxyAction) należy dodać poniższe wpisy:
<action class="com.custom.common.logging.esb.actions.SystemPrintln"
name="echo-request1">
<property name="message"
value="[esb-eurzad-proxy-pull-service] Message before
RequestSignExchangeAction" />
<property name="printfull" value="false" />
<property name="level" value="debug" />
</action>
<action
class="pl.gov.eurzad.esb.custom.actions.RequestSignExchangeAction"
name="request-sign-exchange-action">
<property name="senderFileBaseURI"
value="/METAINF/crypto_eurzad_central_request.properties" />
<property name="receiverFileBaseURI"
value="/METAINF/crypto_eurzad_central_check.properties" />
</action>
name="echo-response1">
value="[esb-eurzad-proxy-pull-service] Message after
RequestSignExchangeAction" />
</action>
<action
..........
</action>
name="proxy"
name="echo-request2">
SOAPProxy" />
</action>
<action
class="pl.gov.eurzad.esb.custom.actions.ResponseSignExchangeAction"
name="response-sign-exchange-action">
<property name="receiverFileBaseURI"
Strona 25 z 29
ESB
value="/METAINF/crypto_eurzad_central_check.properties" />
<property name="senderFileBaseURI"
value="/METAINF/crypto_eurzad_central_response.properties" />
</action>
name="echo-response2">
ResponseSignExchangeAction" />
</action>
Akcja RequestSignExchangeAction jest wykonywana przed akcją proxującą z
parametrami:
receiverFileBaseURI – wskazanie na plik konfiguracyjny do weryfikacji
podpisu przychodzącego do szyny żądania
senderFileBaseURI – wskazanie na plik konfiguracyjny do podpisu żądania
przesyłanego do systemu zewnętrznego zdefiniowanego np. w SOAPProxy
Akcja ResponseSignExchangeAction jest wykonywana przed akcją proxującą z
parametrami:
receiverFileBaseURI – wskazanie na plik konfiguracyjny do weryfikacji
podpisu odpowiedzi otrzymanej od systemu zewnętrznego zdefiniowanego
np. w SOAPProxy
senderFileBaseURI – wskazanie na plik konfiguracyjny do podpisu
odpowiedzi z szyny ESB
Dodatkowo zalecane jest przed oraz po akcji do tworzenia/weryfikacji podpisu
dodać akcję typu com.custom.common.logging.esb.actions.SystemPrintln, która
doda do logów z określonym poziomem logowania (parametr level) wpis z
prefixem (parametr message) i aktualną kopertą SOAP
8.5.5 Konfiguracja ról dostępowych do usługi
Mechanizm dostępu do usług ESB może zostać dodatkowo rozszerzony o role.
Funkcjonalność ta pozwala zdefiniować grupę usług z rolą publiczną (rola public) i
prywatną (rola private) oraz ograniczyć dostęp do usługi dla wybranej roli.
Mechanizm ten wymaga włączonego mechanizmu WSSecurity dla usługi.
Nadanie usłudze wymagalności posiadania wybranej roli pozwoli ograniczyć
dostęp do wybranej usługi wyłącznie do klientów posiadających wymaganą rolę.
Strona 26 z 29
ESB
Konfiguracja roli usługi polega na dodaniu poniższego wpisu do pliku jbossesb.xml usługi wewnątrz sekcji service:
<security moduleName="ESBCertLogin" rolesAllowed="public"
callbackHandler="pl.gov.esb.cert.callback.handler.CertCallbackHandler">
</security>
Wewnątrz atrybutu rolesAllowed należy podać nazwę wymaganej roli.
Definicja klientów i ich ról znajduje się w pliku C:\comarch\szyna_esb\ jboss5.1.0.GA\server\all\conf\props\roles.properties
Jako nazwę systemu należy podać Common Name (CN) certyfikatu wydanego
przez LCC (Lokalne Centrum Certyfikacji), który służy do komunikacji z
wykorzystaniem WSSecurity z szyną ESB, natomiast po znaku równości listę ról
danego systemu.
Przykładowa zawartość pliku:
TESTeUrzad-Portale.wrotamazowsza.pl=public
TESTEURZAD-JST.wrotamazowsza.pl=public,private
OSTROANDRZGWVM1.wrotamazowsza.pl=public
9. Dodanie nowej usługi ESB
Dodanie nowej usługi powinno utrzymywać schemat ogólny struktury usług
przedstawiony w punkcie 8.4 Schemat ogólny struktury usługi ESB. Zgodność z
przygotowanymi usługami ESB zapewni poprawne wdrożenie nowej usługi oraz
integrację z przygotowanymi mechanizmami wywołania, konfiguracji i
zabezpieczeń na poziomie modułów bezpieczeństwa serwera JBoss.
W celu wdrożenia nowej usługi na serwer należy zbudowane archiwum usługi w
postaci pliku *.esb skopiować do katalogu JBOSS_HOME/server/all/deploy i
zrestartować usługę sieciową serwera JBOSS.
10. Kompilacja źródeł usług ESB
Źródła zostały podzielone tematycznie w zależności od przeznaczenia usług ESB.
Główna klasyfikacja pozwala odróżnić usługi centralne (services-central) od
lokalnych (services-local).
Kolejna klasyfikacja pozwala ustalić poziom/zakres integracji, który umożliwia
usługa.
Strona 27 z 29
ESB
Szyna regionalna
Zakres integracji
central
comarchportal
eop
epuap
eurzad
ezd
gis
rdp
teryt
wksp
Szyna lokalna
Zakres integracji
central
comarchportal
eop
eurzad
gis
plp
rdp
ezd
teryt
wksp
Opis
Usługi świadczone centralnie dla
partnerów
Integracja z aplikacją Comarch Portal
w zakresie publikacji rejestrów BIP,
zarządzania użytkownikami
Integracja z EOP na poziomie
centralnym
Integracja z platformą EPUAP
Integracja z EUrząd
Integracja z EZD
Integracja z WMS i WFS
Integracja z RDP
Integracja z Teryt
Integracja z WKSP
Opis
Integracja z usługami świadczonymi
przez szynę regionalną. Usługi
komunikują się z centralnymi.
Integracja z aplikacją Comarch Portal
poprzez szynę centralną w zakresie
publikacji rejestrów BIP, zarządzania
użytkownikami. Usługi komunikują
się z centralnymi.
Integracja z EOP na poziomie
lokalnym.
Integracja z EUrząd na poziomie
lokalnym. Usługi komunikują się z
centralnymi.
Integracja z WMS i WFS na poziomie
centralnymi.
Integracja z PLP na poziomie
lokalnym.
Integracja z RDP na poziomie
centralnymi.
Integracja z lokalnymi EZD
Integracja z Teryt na poziomie
centralnymi.
Integracja z WKSP na poziomie
centralnymi.
Strona 28 z 29
ESB
W lokalizacji głównej ROOT źródeł znajduje się plik konfiguracyjny pom.xml
grupujący moduły, które zostaną zbudowane w procesie automatycznego
budowania narzędziem MAVEN.
Aby zbudować z wiersza poleceń systemu operacyjnego źródła usług ESB należy
przejść do głównego folderu źródeł usług ESB i wywołać polecenie:
mvn -P[NAZWA_PROFILU] clean install
Do działania polecenia mvn należy skonfigurować narzędzie MAVEN, ustawić
zmienną środowiskową JAVA_HOME na katalog domowy JDK, dodać do zmiennej
środowiskowej PATH katalog bin z Mavenem oraz posiadać dostęp do
repozytoriów Maven
Dostępne profile:
prod – profil dla środowiska produkcyjnego np.:
EURZADESB.wrotamazowsza.pl
prodTest – profil dla środowiska testowego produkcyjnego np.:
TESTEURZAD-ESB.wrotamazowsza.pl
preprod – profil dla środowiska przedprodukcyjnego
Przykład dla środowiska produkcyjnego:
mvn –Pprod clean install
Strona 29 z 29

Instrukcja techniczna - zamowienia.mazovia.pl

Transkrypt

Podobne dokumenty

Generowanie usług Web Services na podstawie opisu WSDL