Skip to main content
Käytä OAuth-asiakastunnuksia (client credentials), kun taustajärjestelmäintegraatiosi tarvitsee lyhytikäisiä käyttöoikeustunnisteita tai kun tietoturvakäytäntösi edellyttää niitä. Kukin asiakasohjelma kuuluu yhdelle palvelutilille ja yhdelle organisaatiolle. OAuth on valinnainen: rajattu API-avain riittää yksityiseen palvelinintegraatioon, joka pystyy tallentamaan ja kierrättämään avaimen turvallisesti. Katso Todennus, kun valitset näiden kahden menetelmän välillä ja haluat ymmärtää, miten palvelutilit liittyvät asiaan.
OAuth-käyttö on otettava käyttöön organisaatiollesi. Käyttöönoton yhteydessä saat alueellisen token-päätepisteen, myöntäjän (issuer), kohderyhmän (audience) ja asiakkaan todennustavan. Jos tarvitset nämä asetukset tai sinulla ei ole pääsyä asiakasohjelmien hallintaan, ota yhteyttä Living Securityn tukeen.
Client credentials -myöntötapa edustaa palvelutiliäsi. Se ei kirjaa henkilöä sisään eikä pyydä asiakasta valtuuttamaan sovellusta. Selaimen kautta tapahtuva delegoitu valtuutus on erillinen OAuth-ominaisuus, eikä näitä toimintoja tarjota sitä varten.

Ennen aloittamista

  • Luo palvelutili, jolla on vain integraation tarvitsemat oikeudet.
  • Käytä hallintatunnistetta, jolla on service_account:manage sekä kaikki oikeudet, jotka haluat myöntää uudelle asiakasohjelmalle. Kohdetilillä on myös oltava nämä oikeudet. Asiakasohjelma ei voi laajentaa kummankaan tilin valtuuksia.
  • Valitse organisaation alue. API-tunnisteet ja OAuth-käyttöoikeustunnisteet kuuluvat vastaavalle alueelliselle API-isännälle.
  • Säilytä asiakassalaisuus ja tokenit palvelinpuolen salaisuuksien tallennustilassa. Älä koskaan sijoita niitä selainkoodiin, mobiilisovelluksiin, versionhallintaan tai pyyntölokeihin.

Asiakasohjelman luominen

POST /v1/oauth_clients edellyttää service_account_id-arvoa, ei-tyhjää luetteloa nimenomaisista scopes-arvoista ja Idempotency-Key-arvoa. Jokerimerkkejä ei hyväksytä. Asiakasohjelma tukee enintään 100 oikeusaluetta (scope), joiden yhteispituus on enintään 4 096 merkkiä. Kullakin palvelutilillä voi olla enintään 20 asiakasohjelmaa tai ratkaisematonta luonti- tai puhdistustoimintoa. Mitätöinti estää API-käytön välittömästi. Asiakasohjelma tai epävarma palveluntarjoajan puolella tehty luonti lasketaan edelleen rajaan, kunnes etäpuolen puhdistus on vahvistettu. Hylätty varaus tai luonti, jonka on osoitettu epäonnistuneen ennen kuin palveluntarjoajan työ alkoi, voi vapauttaa paikkansa turvallisesti. Sen uudelleenyrityksen avain kuuluu edelleen alkuperäiselle yritykselle; palauta kuitti ennen kuin päätät, luodaanko korvaava asiakasohjelma. Valitse tälle luontiyritykselle yksi uudelleenyritysavain ja tallenna se pysyvästi ennen pyynnön lähettämistä. Käytä 1–255 näkyvää ASCII-merkkiä ilman välilyöntejä. Käytä samaa avainta uudelleen samalla tilillä, samoilla oikeusalueilla, samalla hallintatunnisteella, samalla alueella ja samalla API-versiolla, kun vastaus on kadonnut. Hallintatunnisteen kierrättäminen saman palvelutilin alla ei luo uutta uudelleenyrityksen identiteettiä. Asenna Pythonin requests-paketti. Lataa seuraavat ympäristöarvot tavanomaisen salaisuus- ja konfiguraationhallintasi kautta:
Python
Esimerkki tekee yhden pyynnön ja säilyttää tuloksen muistissa. Lisää salaisuuksienhallintasi kirjoitustoiminto merkittyyn kohtaan ennen tuotantokäyttöä. Esimerkki edellyttää tarkoituksella päätöstä epävarman tuloksen jälkeen sen sijaan, että se loisi hiljaa toisen asiakasohjelman. Myös verkkopoikkeukset edellyttävät alla kuvattuja palautusvaiheita. Luonti- ja kuittivastaukset käyttävät 201-arvoa ja sisältävät oauth_client-resurssin, jossa on id, service_account_id, client_id, scopes, status, created_at ja client_secret. Vastaukset merkitään arvolla Cache-Control: no-store.
  • id tunnistaa alustan resurssin. Tallenna se hakua ja mitätöintiä varten.
  • client_id tunnistaa asiakasohjelman tokenin vaihdon aikana. Se ei ole alustan resurssin tunnus. Se voi olla null, kun luonti on vielä kesken.
  • client_secret palautetaan vain pyynnölle, joka saattaa luonnin päätökseen. Jokainen toistettu luontipyyntö palauttaa arvon null, myös uudelleenyritys kadonneen onnistumisvastauksen jälkeen. Haku ei koskaan palauta salaisuutta.

Kadonneen tai keskeytyneen vastauksen palauttaminen

Toista sama luontipyyntö tallennetulla uudelleenyritysavaimella, jotta saat resurssin kuitin. Kuitti kuvaa nykytilaa, joten mitätöity asiakasohjelma pysyy mitätöitynä. Tämä toiminto ei käytä yleistä 24 tunnin välimuistissa olevan vastauksen toistosopimusta eikä palauta Idempotent-Replayed-otsaketta. Katso pyyntötunnuksia ja palautustietoja koskevat ohjeet kohdasta virheet. Älä koskaan lähetä asiakassalaisuutta tai käyttöoikeustunnistetta tukipyynnön mukana.

Tarkastelu ja mitätöinti

Käytä hallintatunnistettasi ja alustan resurssin id-arvoa: Mitätöinti estää asiakasohjelman myöhemmät API-pyynnöt, myös jo myönnettyjä tokeneita käyttävät pyynnöt. Se ei peruuta API:n jo hyväksymää työtä. Etäpuolen tunnisteiden puhdistus voi valmistua myöhemmin. Mitätöinnin toistaminen on turvallista, eikä se vaadi uudelleenyritysavainta. Jatka hallintatunnisteen käyttöä, jos mitätöitävä asiakasohjelma on itse API-kutsuja.

Kierrätys ilman käyttöoikeuden menetystä

Luo toinen asiakasohjelma, jolla on vaadittu oikeusalueiden yläraja. Tallenna sen salaisuus, hanki token alueellisella token-päätepisteelläsi ja varmista, että integraatio toimii sen kanssa. Vaihda integraatio käyttämään korvaavaa asiakasohjelmaa ja mitätöi sitten vanha resurssi. Säilytä erillinen hallintatunniste, jotta voit palautua virheellisestä käyttöönotosta. Käyttöoikeustunnisteet eivät voi myöntää enempää kuin asiakasohjelman oikeusalueet ja palvelutilin nykyiset oikeudet sallivat. Tilin oikeuksien poistaminen tai asiakasohjelman mitätöinti ohittaa tokenin jäljellä olevan voimassaoloajan. Älä pidä välimuistissa olevaa tokenia todisteena siitä, että valtuutus on edelleen voimassa. Hanki uusi käyttöoikeustunniste ennen vanhenemista todentamalla asiakasohjelma uudelleen; tämä myöntötapa ei käytä päivitystokeneita (refresh token).