Takaisin

Oauth2 & OpenId connect, Hybrid-Flow

Talenom käyttää erilaisia authentikaatio ja authorisointi -menetelmiä riippuen rajapinnoista ja niille asetetuista tietoturvamääritteistä.

Purchases API rajapinnassa käytämme Oauth2:n ja OpenId Connectin hybrid tunnistautumista, koska ostolaskuissa meidän tulee varmistua sekä rajapintaa käyttävästä järjestelmästä, että järjestelmää käyttävästä käyttäjästä.

Mikäli etsit dokumentaatiota Client Credentials flowille, voit lukea siitä kohdasta "REST API Tunnistautuminen"

Alla kuvaus Hybrid-Flowista

Kuinka onnistun tunnistautumisessa?

Alla kuvattuna tarkemmin tunnistautumiseen vaadittavat kutsut. Jotta tunnistautuminen voidaan tehdä, täytyy järjestelmälle perustaa Talenomin integraatiopalveluiden toimesta omat tunnistautumistiedot, tunnistautumistietoja voit pyytää näiden sivujen "Tuki" -osion kautta. Muista mainita, että tarvitset tunnukset nimenomaan Hybrid-flow tunnistautumista varten, jotta voit käyttää Purchases API rajapintaa.

Käytämme esimerkissä näitä tietoja:

• ClientId: purchasesAPITestingClient
• Client Secret: super.secretKj4ncokm4
• Redirect URI: https://yoursoftware.com/callback.php

Sitten mennään!

1. Käyttäjä painaa kuviteltua "Nouda ostolaskut Talenomilta" painiketta järjestelmässäsi.

2. Järjestelmäsi huomaa, että kyseiselle käyttäjälle ei ole tallennettuna voimassaolevaa tokenia tai se on vanhentunut, joten järjestelmäsi aloittaa tunnistautumisen.

3. Järjestelmäsi lähettää authorisointikutsun Talenomin identiteettipalvelimelle, kutsu näyttää jotakuinkin tältä:

GET https://idsrv.talenom.fi/identity/connect/authorize?response_type=code id_token&scope=TalenomPurchasesWebApi+openid+profile+offline_access&redirect_uri=https://yoursoftware.com/callback.php&response_mode=form_post&client_id=purchasesAPITestingClient&nonce=xxx

Authorisointi kutsun URL -parametrit selostettuna:

* response_type: code id_token (Tällä kerrotaan, että millaista vastausta järjestelmä odottaa jos tunnistautuminen onnistuu)

* scope: TalenomPurchasesWebApi openid profile offline_access (Välilyönnillä eroteltu lista eri oikeuksia mitä järjestelmäsi pyytää)

* redirect_uri: https://yoursoftware.com/callback.php (URL sinun järjestelmääsi mihin identiteetti palvelu ohjaa vastaukset. Näitä osoitteita voi olla useampi per clientId, jokainen redirect_uri lisätään integraatiopalveluiden toimesta erillisellä pyynnöllä, kuitenkin yksi on vähimmäisvaatimus)

* response_mode: form_post (Määrittää miten vastaus-sanomat muotoillaan)

client_id: purchasesAPITestingClient (Järjestelmäsi tunniste joka luotu integraatiopalveluiden toimesta)

nonce: xxx (Ennalta määrittämätön pätkä random tekstiä ja numeroita, alla esimerkki noncen luonnista PHP:lla)

function generateNonce($length)
{
	$chars = "abcdefghijklmopqrstuvwxy0123456789";
	$nonce = "";
	for ($i = 0; $i < $length; $i++)
	{
		$nonce .= $chars[rand(0, strlen($chars) - 1)];
	}
	return $nonce;
}

4. Mikäli authorisointipyyntö on oikein muotoiltu ja clientId perustettu Talenomin järjestelmiin, tällöin käyttäjälle pitäisi ponnahtaa auki Talenomin kirjautuminen. Tässä käyttäjän täytyy antaa henkilökohtaiset Talenom Online -tunnistautumistiedot, jonka jälkeen käyttäjän pitää antaa myöntymys (Consent), että ulkopuolinen järjestelmä saa käyttää käyttäjän edustaman yrityksen ostolaskudataa.

Käyttäjä antaa omat Talenom Online tunnukset ja klikkaa "Kirjaudu"

Käyttäjä antaa luvan käyttää heidän yrityksensä ostolaskudataa ulkopuolisessa järjestelmässä.

6. Mikäli käyttäjä antaa oikeat (toimivat) tunnukset sekä myöntymyksen, Talenomin identiteettipalvelu lähettää authorisointikoodin takaisin kyselevälle järjestelmälle.

Vastaus näyttää tältä:

{
	"code": "eb0690bxxxxxx123456xxxx789x45663298d2ff4c", --- Tässä kohtaa on authorisointikoodi jota käytetään seuraavassa kohdassa
	"id_token": "eyJ0eXAiOiJKV1QiLCJhbGciOiJSUzI1NiIsIng1dCXXXXXxxxxxXXXXXXXXxxxxXXX42R3V0ZyIsImtpZCI6IlRVbG9iMDljN1F6UUptYklEX3VGMm42R3V0ZyJ9.eyJpc3MiOiJodHRwczovL2lkc3J2LnRhbGVub20uZmkvaWRlbnRpdHkiLCJhdWQiOiJBcmluVGVzdGlIeWJyaWRpIiwiZXhwIjoxNjAxMjgxNjA1LCJuYmYiOjE2MDEyODEzMDUsIm5vbmNlIjoiYjN2dTh1OHRibW1hZ3h5Zng5YjZrY213MHEwa2U1M3YiLCJpYXQiOjE2MDEyODEzMDUsImNfaGFzaCI6IlpzQzE2R3oyd2JKM1dtX3RIVGt6ekEiLCJzaWQiOiJkZDcwZWI2N2U0NjVmMDBmMDI4NjE1YjlkMDhhMDUxZSIsInN1YiI6IjE1N2M4ZDJhLTVjNWYtNDY1OS05NDE3LTJjMzg0N2I0NTQ1ZCIsImF1dGhfdGltZSI6MTYwMTI4MDg5MSwiaWRwIjoiaWRzcnYiLCJhbXIiOlsicGFzc3dvcmQiXX0.I7ZgymgQmj7UVL1LGXsFxk5T6zQybIQSTu1DBF0ZXQTUaxQji7IRrq_U6AOG40Fg2Xw-q5LF-xt_2AMO9NvGxjuljzetaP8XXXXxxxxxxXXXXXXXX8tTKEb_J38rGQjNuEh-xUCYgiWHyWYRAjXxE0U0pEhpyBEFvQTXOBMbOOa-ZmZMiXYgP9BVUZh0rR9z5cSII6e22nDG7tohFe4R5NKxW3BN2guOvkGJnROKer-1IvKC8Qyl69Hmwmw7-n-aHP3zCFF9oPzd-dAxGGdcu7R8oIPcJWfJaI6-mLkBoGfvA",
	"scope": "TalenomPurchasesWebApi openid profile offline_access",
	"session_state": "4XN_sb4kLj9gyJw9pgOzdWXWtQ06OlDvP1wulmJsNkI.b43da94bfb379b457a56871f941cfc8c"
}

7. Tehdään uusi kutsu token palvelua vasten, jotta saadaan noudettua varsinainen access token:

Headers: 
Authorization: Basic cHVyY2hhc2VzQVBJVGVzdGluZ0NsaWVudDpzdXBlci5zZWNyZXRLajRuY29rbTQ
Content-Type: application/x-www-form-urlencoded
Accept: application/json

POST https://idsrv.talenom.fi/identity/connect/token

Body: 
{
	code: ADKLSJANM;Rnfjidmikl55n2mlkmr3nr_etc..,
	redirect_uri: https://yoursoftware.com/callback.php,
	grant_type: authorization_code
}

Access token noudon parametrit

Otsikkotason tiedot (headers):

* Authorization: Basic cHVyY2hhc2VzQVBJVGVzdGluZ0NsaWVudDpzdXBlci5zZWNyZXRLajRuY29rbTQ (Tämä sisältää tekstin Basic jonka jälkeen järjestelmällesi luotu ClientId ja Client Secret base64 enkoodattuna. ClientId:n ja Client Secretin välissä tulee olla kaksoispiste (:), esimerkkinä: purchasesAPITestingClient:super.secretKj4ncokm4 base64 enkoodattuna näyttää tältä: cHVyY2hhc2VzQVBJVGVzdGluZ0NsaWVudDpzdXBlci5zZWNyZXRLajRuY29rbTQ

* Content-Type: application/x-www-form-urlencoded (Tällä sisältötyypillä avaimet ja arvot enkoodataan pareina joissa erottelu on & merkillä ja avain-arvo pari yhdistyy = merkillä.

* Accept: application/json (Tällä kerrotaan palvelulle, että vastaus halutaan json muodossa (json on ainoastaan tuettu tällä hetkellä)

POST pyynnön sisältö (Body):

code: XXXXXX.... (authorisointikoodi jonka sait edellisen kyselyn vastauksena kohdassa "code")

redirect_uri: https://yoursoftware.com/callback.php, (Sama kuin edellisessä pyynnössä)

grant_type: authorization_code (Tällä kerrotaan palvelulle, että mitä pyyntöä ollaan tekemässä)

Onnistuneen pyynnön vastauksen sisältö jossa mukana access_token:

{
	"id_token": "eyJ0eXAiOiJKV1QiLrKueHJOYYYYYYYYYYYYYYYYYYYYYYYYYYYY",
	"access_token": "eyJ0eXAiOXXXXXXXXXXXXXXXXXXXXXXXX",
	"expires_in": 3600,
	"token_type": "Bearer",
	"refresh_token": "a8651fd7e49fdda123456789d2db701b00"
}

7. Mikäli pyyntö on onnistunut ja olet saanut vastaukseksi samanlaisen sisällön kuin yllä, voit tehdä ensimmäisen varsinaisen pyynnön itse rajapintaan:

Headers: 
Accept: application/json
Authorization: Bearer eyJ0eXAiOXXXXXXXXXXXXXXXXXXXXXXXX

GET https://purchasestesting.talenom.fi/v1/invoices?customerNumber=14222

Ja vastaukseksi pitäisi tulla jotain tämän tyyppistä:

{
    "Items": [{
            "version": 799200913,
            "seller": {
                "businessId": "1234567-1",
                "organisationName": "Kopiokonekauppa Oy",
                "additionalName": null,
                "bankAccount": {
                    "bankName": "",
                    "bankAddress": null,
                    "iban": "FI2112345600000785",
                    "bic": "NDEAFIHH"
                }
            },
            "buyer": {
                "businessId": "7654321-0",
                "organisationName": "Tietoväylä Demoyritys",
                "additionalName": null,
                "postalAddress": {
                    "streetName": [
                        "Yrttipellontie  2"
                    ],
                    "townName": "OULU",
                    "postCode": "90230 ",
                    "countryCode": "FI",
                    "postOfficeBoxId": null
                },
                ...etc..
            }
        }
    ]}

Mikäli sait vastaukseksi jotain vastaavaa, Onnittelut! Sait tunnistautumisen toimimaan!

Ekstra vinkki: Access token pyynnön mukana tulee myös Refresh token, tuota voidaan hyödyntää koneellisesti päivittämään access_token, tästä lisää linkin takaa: https://openid.net/specs/openid-connect-core-1_0.html#RefreshTokens

Takaisin