Liity Palveluväylän tuotantoympäristöön

X-Road Toolkitilla määrittelet yhden tai useamman liityntäpalvelimen automaattisesti skriptien avulla. Toolkitin haluttu toiminta ja tiedot määritellään YAML-konfiguraatiotiedostoon. Konfiguraation voi ajaa kahdessa osassa tai vaiheittain. Lue lisää X-Road Toolkitista.Avautuu uuteen ikkunaan.

Ota selaimella yhteys graafiseen hallintakäyttöliittymään osoitteella: https://{hostname}:4000

Korvaa {hostname} asennetun liityntäpalvelimen nimellä.

Sait Palveluväylän ylläpidolta sähköpostitse ympäristökohtaisen konfiguraatiotiedoston, eli konfiguraatioankkurin. Seuraa tukiartikkelia Liityntäpalvelimen liittäminen testi- tai tuotantoympäristöönAvautuu uuteen ikkunaan. ja tee seuraavat asiat ohjeen mukaan. Muista seurata tuotantoympäristön (FI) ohjeita.

Katso ohjevideo liityntäpalvelimen konfiguroimisesta (Youtube).Avautuu uuteen ikkunaan.

1. Kirjaudu sisään liityntäpalvelinohjelmiston asennuksen yhteydessä luomallasi pääkäyttäjätunnuksella.

2. Asenna konfiguraatioankkuri (tukiartikkelin kohta: ”Palvelimen perusasetusten määrittely”).

3. Täytä avautuvaan ikkunaan seuraavat tiedot:

• Member Code: organisaatiosi Y-tunnus
• Member Name: organisaatiosi nimi. Järjestelmän pitäisi täydentää tämä automaattisesti.
• Security Server Code: liityntäpalvelimen yksilöivä tunnus, tyypillisesti palvelimen nimen host-osa.
• PIN: vapaavalintainen koodi, jonka pituus on vähintään 10 merkkiä.

4. Jos viestiliikenteesi edellyttää lokitusta, lisää aikaleimapalvelu (TSA-palvelu): System Parameters > Timestamping Services > Add. Valitse käyttöliittymän ehdottama liityntäympäristön TSA-palvelu. Jos tiedonsiirtosi ei edellytä lokitusta, kannattaa liityntäpalvelimen lokitusvaihtoehdoksi valita OFF/no logging.

5. Luo allekirjoitusvarmennepyyntö: Keys and Certificates > Add Key. Täytä seuraavat tiedot:

• Usage: SIGNING
• Client: Y-tunnuksen perusteella oma organisaatiosi
• Certification Service: G2R
• CSR Format: PEM

6. Luo autentikointivarmennepyyntö: Keys and Certificates > Add Key. Täytä seuraavat tiedot:

• Usage: AUTHENTICATION
• Certification Service: G2R
• CSR Format: PEM

7. Lähetä molemmat varmennepyynnöt allekirjoitettavaksi sähköpostitse osoitteeseen palveluvayla@palveluvayla.fi. Varmennepyynnöt käsitellään DVV:llä ja käsittelyssä kuluu yleensä muutama päivä. Varaa tähän vaiheeseen kuitenkin viikko, sillä ruuhka- ja loma-aikoina käsittelyssä voi kulua pidempäänkin. Saat allekirjoitetut varmenteet sähköpostitse Palveluväylän ylläpidolta.

8. Asenna allekirjoitetut varmenteet: Keys and Certificates > Import Certificate.

9. Aktivoi autentikointivarmenne valitsemalla Activate.

10. Rekisteröi autentikointivarmenne valitsemalla Register.

1. Luo asiakasjärjestelmän yksityinen avain komentorivikäyttöliittymässä seuraavalla komennolla: openssl genrsa -out clientprivatekey.pem 2048
2. Luo avaimelle ns. self-signed-varmenne seuraavalla komennolla: openssl req -new -x509 -key clientprivatekey.pem -out clientcert.pem -days 365
3. Kirjaudu sisään liityntäpalvelimen hallintakäyttöliittymään, ja valitse Internal Servers sen alijärjestelmän kohdalta, johon haluat liittää asiakasjärjestelmän.
4. Valitse asiakasjärjestelmän ja liityntäpalvelimen välisen yhteyden tyyppi Connection type for Servers in Service Consumer Role -valikosta. Käytä aina HTTPS-protokollaa, jotta yhteys asiakasjärjestelmän ja liityntäpalvelimen välillä on salattu. Protokolla edellyttää, että asiakasjärjestelmän on esitettävä asiakasvarmenne käyttääkseen palveluitasi. HTTPS-asetuksen ja asiakasvarmenteiden käyttö on pakollista aina, kun useat eri organisaatiot käyttävät samaa liityntäpalvelinta. Tällaisessa tilanteessa asiakasvarmenteen käyttö on ainoa tapa estää organisaatioita kutsumasta Palveluväylän palveluita toistensa alijärjestelmien kautta.
5. Lisää liityntäpalvelimelle HTTPS-protokollan vaatima asiakasvarmenne, joka on tallennettu luomaasi clientcert.pem-tiedostoon Internal TLS Certificates > Add.
6. Lataa alijärjestelmälle liityntäpalvelimen sisäinen varmenne valitsemalla Security Server Certificate > Export.

Voit testata asiakasvarmenteen helposti kutsumalla getRandom-testipalvelua Curl-ohjelman avulla. Huomaa, että tämä testaus täytyy suorittaa jollakin muulla palvelimella kuin liityntäpalvelimella. Löydät ohjeet testaukseen Asiakasjärjestelmän liittäminen liityntäpalvelimeen -tukiartikkelinAvautuu uuteen ikkunaan. kohdasta Asiakasvarmenteen testaaminen. 

Kutsu getRandom-testipalvelua sillä alijärjestelmällä, jonka alle lisäsit asiakasvarmenteen Curl-komennolla: 

curl -E ./clientcert.pem --key ./clientprivatekey.pem -k -d @getRandom.xml --header "Content-Type: text/xml" -X POST https://{host}/ 

Jos asiakasvarmenne toimii oikein, kutsu palauttaa satunnaisesti generoidun luvun väliltä 0–100.

1. Valitse CLIENTS-välilehdeltä alijärjestelmä, jolle haluat lisätä palvelun.
2. Lisää WSDL-kuvaus SERVICES-välilehdeltä antamalla palvelun rajapintakuvauksen URL-osoite. Yksittäinen WSDL-kuvaus voi sisältää yhden tai useamman palvelun rajapintakuvauksen.
3. Aktivoi WSDL-kuvaus sen kohdalla olevasta valintakytkimestä.
4. Määrittele palvelun yhteysasetukseksi HTTPS-protokolla. Löydät ohjeet Palvelun lisääminen liityntäpalvelimelle -tukiartikkelistaAvautuu uuteen ikkunaan. kohdasta Palvelun yhteysasetukset.
5. Tarkista seuraavana päivänä, että palvelu ja sen tekniset tiedot näkyvät Liityntäkatalogissa. Jos tiedot eivät näy oikein, ota yhteys Palveluväylän ylläpitoon: palveluvayla@palveluvayla.fi

1. Valitse CLIENTS-välilehdeltä alijärjestelmä, jolle haluat lisätä palvelun.
2. Lisää REST-palvelu SERVICES-välilehdeltä valitsemalla ADD REST.
3. Valitse osoitepolun tyypiksi joko REST API Base Path tai OpenAPI3 Description. Anna URL-osoite ja palvelun nimi (service code). Lisää palvelu valitsemalla ADD.
4. Aktivoi REST-palvelu sen kohdalla olevasta valintakytkimestä. Varmista ennen aktivointia, että palvelun tiedot ovat oikein. Aktivoinnin jälkeen palvelu on käyttäjien saatavilla.
5. Tarkista seuraavana päivänä, että palvelu ja sen tekniset tiedot näkyvät Liityntäkatalogissa. Jos tiedot eivät näy oikein, ota yhteys Palveluväylän ylläpitoon: palveluvayla@palveluvayla.fi

Määrittele palvelun käyttöoikeudet niille organisaatioille, jotka saavat hyödyntää tarjoamaasi palvelua. Voit lisätä käyttöoikeuksia myös myöhemmin samasta valikosta.

1. Valitse palvelu ja sen jälkeen Access Rights.
2. Valitse Add Subjects ja valitse avautuvasta näkymästä alijärjestelmä, jolle haluat antaa käyttöoikeuden palveluun.

1. Mikä organisaatio on kyseessä
2. Mitä organisaatio tekee
3. Mitä palveluita organisaatio tuottaa Palveluväylän kautta

Tutustu ohjeeseen organisaation tietojen kuvaamisesta.Avautuu uuteen ikkunaan.

1. Mitä tietoja palvelun kautta voi saada käyttöönsä
2. Mitä edellytyksiä ja rajoituksia palvelun käytössä on
3. Miten palvelun saa käyttöönsä (käyttöönottoprosessi ja mahdolliset käyttöluvat)

Kuvaa palvelusi Liityntäkatalogiin huolellisesti, niin muiden on helpompi löytää palvelusi ja hyödyntää niitä. Älä kirjoita kuvausta liian teknisellä kielellä, vaan pyri yleistajuiseen ilmaisuun. Kirjoita kuvaus ytimekkäästi, mutta muista kertoa kaikki oleellinen.

Tutustu ohjeeseen alijärjestelmän ja palveluiden kuvaamisesta.Avautuu uuteen ikkunaan.

Katso esimerkki Suomi.fi-valtuudet-palvelun kuvauksesta.Avautuu uuteen ikkunaan.