MCP-palvelimen tunnistusratkaisun toteutusopas: käytä uusinta spesifikaatiota

Muutama päivä sitten (18. kesäkuuta 2025) MCP (Model Context Protocol) -tiimi julkaisi uusimman version MCP Spesifikaatiosta (2025-06-18). Tämä päivitys sisältää merkittävän muutoksen tunnistusspeksiin. MCP-palvelimet eivät enää jaa käyttöoikeustunnisteita Valtuutuspalvelimena, vaan ne vastaanottavat tunnisteita ja tarjoavat resursseja Resurssipalvelimena.

Yhtenä MCP Auth -kirjaston (plug-and-play MCP Server tunnistuskirjasto) ylläpitäjistä olen implementoinut tuen uusimmalle MCP tunnistusspesille tähän projektiin. Käytännön kokemuksella näytän, kuinka toteutat MCP Serverillesi tunnistusominaisuudet uusinta spesifikaatiota noudattaen.

Tämä artikkeli auttaa sinua:

• Ymmärtämään kuinka MCP-tunnistus toimii uuden MCP-tunnistusspeksin mukaan
• Selkeyttämään, mitä MCP-palvelimen tulee toteuttaa Resource Serverina MCP-tunnistusspeksin vaatimusten mukaisesti
• Tarjoamaan ohjausta MCP Serverisi auth-tuen toteutukseen MCP-tunnistusspeksin mukaisesti
• Tunnistamaan unohdettuja yksityiskohtia ja tietoturvaongelmia MCP-tunnistusspesin implementoinnissa

Huomaathan artikkelissa:

• Oletetaan, että lukijoilla on perustiedot JWT:stä (JSON Web Token). Artikkelissa ei käsitellä yksityiskohtaisesti JWT:n rakennetta, allekirjoitusten tarkistuslogiikkaa tms. Katso lisätietoja Auth Wiki - JWT
• Ei esitellä yksityiskohtaisesti kaikista RFC-dokumenteista, joihin MCP-tunnistusspeksi perustuu. Tarjoaa vain toteutuksia, jotka ovat RFC-vaatimusten mukaisia
• Ei kata MCP Clientin eikä Authorizationin implementointi- ja vuorovaikutusyksityiskohtia. Nämä toteuttavat yleensä LLM-klientit ja MCP-yhteensopivat valtuutuspalvelimet MCP määrittelyiden pohjalta. MCP Server -kehittäjien ei tarvitse eikä voi puuttua niihin. Katso tarkemmin OAuth Client ja Authorization Server
• Kaikki artikkelissa mainitut käyttöoikeustunnisteet oletetaan JWT-muotoisiksi, koska se on markkinoilla yleisin. Muiden tunnisteiden käytöstä katso vastaavan valtuutuspalveluntarjoajan dokumentaatio.

Kuinka MCP-tunnistus toimii?#

Uusimman MCP-tunnistusspeksin mukaan MCP-tunnistusprosessi näkyy alla olevassa kaaviossa:

1. MCP Client pyytää resursseja MCP Serveriltä osoitteesta https://github-tools.com. Koska käyttäjä ei ole vielä kirjautunut sisään, pyynnössä ei ole tunnisteella täytettyä authorization-otsaketta.

2. MCP Server ei löydä käyttöoikeustunnistetta MCP Clientin pyynnön authorization-headerista. Se palauttaa HTTP 401 virheen MCP Clientille. Tähän virhevastaukseen sisältyy WWW-Authenticate-headeri, jossa on MCP Serverin resurssimetadatan URL (resource_metadata-kentän arvo).

3. MCP Client poimii resource_metadata-arvon palaavasta WWW-Authenticate-headerista (esimerkiksi: https://github-tools.com/.well-known/oauth-protected-resource). Tämän jälkeen MCP Client pyytää resurssimetatiedot MCP Serveriltä, joka toimii Resurssipalvelimena tältä osoitteelta. Metadata sisältää esimerkiksi authorization_servers- ja scopes_supported-sisällöt, jotka auttavat MCP Clientia ymmärtämään, miten käyttöoikeustunniste saadaan MCP Serverille pääsyyn, eli minkä valtuutuspalvelimen kautta ja millä oikeuksilla.

4-8. MCP Client hakee authorization serverin metatiedot resource metadata -kohdasta löytyvän valtuutuspalvelimen metadata-URL:n perusteella. Tämän jälkeen MCP Client tekee OAuth 2.1 -valtuutuspolun valtuutuspalvelimen kanssa ja saa tunnistuksen saatuaan käyttöoikeustunnisteen.

9. MCP Client lähettää käyttötunnisteen valtuutuspalvelimelta saatuna ja tekee uuden resurssipyynnön MCP Serverille.

10. MCP Server tarkistaa tunnisteen kelvollisuuden ja palauttaa pyydetyn resurssin. Jatkossa MCP Client ja MCP Server kommunikoivat voimassa olevalla tunnisteella.

Seuraavaksi selitämme MCP Serverin tunnistusmekanismin toteutuksen vaihevaiheelta MCP auth -prosessin perusteella.

Käsittele valtuuttamattomat pyynnöt: palauta 401-virhe ja WWW-Authenticate-headeri#

Kuten yllä olevasta prosessista näkyy, kun MCP Client lähettää pyynnön ilman käyttöoikeustunnistetta MCP Serverille, palvelin palauttaa HTTP 401 Unauthorized -virheen, jonka mukana on WWW-Authenticate-headeri. Headeriin laitetaan osoite MCP Serverin resurssimetadatan hakemista varten.

MCp-tunnistusspeksin virhekäsittelyn mukaan, mikäli MCP Clientin pyyntöön ei ole liitetty tunnistetta, tai saatava tunniste on viallinen, MCP Serverin on palautettava 401-virhe WWW-Authenticate-headerilla.

Milloin palautetaan 401-virhe, mutta miten rakennetaan palaava WWW-Authenticate-headeri?

RFC9728 Section 5.1 mukaan WWW-Authenticate-headeriin tulee sisällyttää resource_metadata-parametri, joka osoittaa resurssimetadatan URL:n.

Perusmuoto on:

Tässä Bearer on autentikointiskerma, joka kertoo, että pääsy OAuth 2.0 -suojattuihin resursseihin vaatii bearer-tunnisteen (katso: MDN-dokumentaatio). resource_metadata-parametrina annetaan MCP Serverin resurssimetadatan päätepisteen koko URL.

Koodiesimerkki voisi näyttää esimerkiksi tältä:

Kun MCP Client saa tällaisen 401-virheen, se hakee MCP Serverin resurssimetadatan käyttämällä WWW-Authenticate-headerista löytyvää resource_metadata-arvoa. Saatujen metatietojen perusteella se aloittaa valtuutuspyynnön osoitteessa mainittuun valtuutuspalvelimeen ja hakee käyttöoikeustunnisteen MCP Serverin käyttöä varten.

Nyt tiedämme, koska palautamme 401-virheen ja että meidän pitää palauttaa resource_metadata-URL. Emme kuitenkaan vielä tiedä, miten muodostetaan resurssimetadatan URL ja mitä metadata sisältää. Seuraavaksi käymme nämä läpi.

Toteuta resurssimetadatan löytämismekanismi#

MCP-tunnistusprosessin mukaan MCP Clientin saatua 401-virheen, se pyytää välittömästi resurssimetadatan MCP Serveriltä. MCP Serverin Resurssipalvelimena tulee siis tarjota resurssimetadatan löytämismekanismi.

Määrittele metadata endpointin polku#

OAuth-järjestelmässä käytämme URL:eja resurssien tunnisteina. Tätä kutsutaan "resource indicatoriksi". RFC9728:n mukaan resurssimetadatan tulee sijaita tietyssä /.well-known -polussa.

Jos MCP Serverisi (esim. https://github-tools.com) tarjoaa vain yhtä palvelua, metadata endpoint kannattaa olla:

Jos samalla alustalla tarjotaan useita MCP-palveluja, kullekin määritellään oma metadata endpoint. Esim. yritysalustalla https://api.acme-corp.com on seuraavat palvelut:

• https://api.acme-corp.com/github - GitHub-integraatiopalvelu
• https://api.acme-corp.com/slack - Slack-integraatiopalvelu
• https://api.acme-corp.com/database - Tietokantakyselypalvelu

Näiden metadata endpointit olisivat:

• https://api.acme-corp.com/.well-known/oauth-protected-resource/github
• https://api.acme-corp.com/.well-known/oauth-protected-resource/slack
• https://api.acme-corp.com/.well-known/oauth-protected-resource/database

Hyödyt: jokaisella palvelulla voi olla omat oikeusalueet ja valtuutuspalvelinasetukset. Esimerkiksi:

• GitHub käyttää GitHub OAuth -palvelinta, tarvitsee github:read, github:write -oikeudet
• Slack käyttää Slack OAuth -palvelinta, tarvitsee slack:channels:read, slack:messages:write -oikeudet
• Tietokanta käyttää sisäistä valtuutuspalvelinta, tarvitsee db:query -oikeuden

Yhteenvetona metadata endpoint -URL:t noudattavat kaavaa:

Voimme muodostaa resurssin metadata endpointin seuraavasti:

Rakenna resurssimetadatan vastaus#

Kun endpointin URL on määritetty, endpointin tulee palauttaa JSON-muotoista metatietoa, joka noudattaa RFC9728:n määrittelyä.

Käytännössä tärkeimmäksi nousee neljä ydinkenttää.

Ensinnäkin resource-kenttä, joka on resurssin tunniste ja jonka tulee vastata MCP Clientin pyytämää osoitetta.

Seuraavaksi authorization_servers -lista, jossa kerrotaan, mistä authorization serverista MCP Clientin tulee hakea käyttöoikeustunnisteen. OAuth 2.0 Protected Resource Metadata (RFC 9728) mukaan tämä on valinnainen, mutta MCP auth -speksissä tämä on pakollinen MCP Clientin valtuutusprosessin onnistumiseksi.

Kolmantena scopes_supported -lista, jossa ilmoitetaan kaikki resurssipalvelimen tukemat oikeusalueet.

Lopuksi bearer_methods_supported-kenttä, joka kertoo MCP Clientille, millä tavoin palvelin haluaa vastaanottaa tunnisteet. Yleensä asetetaan ["header"], jolloin MCP Client toimittaa tunnisteen HTTP Authorization -headerina.

Esimerkki määrittelystä. Oletetaan, että rakennetaan resurssimetadata https://github-tools.com MCP Serverille:

Tämä kertoo MCP Clientille, että sen täytyy hakea käyttöoikeustunniste tunnistetta varten valtuutuspalvelimelta https://auth.github-tools.com, mahdollisia oikeusalueita ovat github:read, github:write, repo:admin ja tunniste tulee välittää HTTP Authorization -otsakkeella.

Perusskenaarioissa nämä neljä kenttää riittävät MCP Clientin toimintaan. Monimutkaisemmissa tapauksissa kannattaa lukaista RFC9728:n kaikki vaihtoehdot.

Tarkista käyttöoikeustunnisteet#

Kun MCP Client on saanut valtuutuspalvelimelta käyttöoikeustunnisteen, se liittää sen tuleviin MCP Server -pyyntöihin.

Käytännössä MCP Serverin tulisi ottaa huomioon tunnisteen tarkistuksessa seuraavat asiat:

1. Tarkista tunniste MCP Serverin backend-konfiguraation mukaan, älä pelkän tunnisteen sisältämän tiedon perusteella.
2. Tarkista, että tunnisteen audience (kohdeyleisö) on MCP Server itse eli tunniste on tarkoitettu kyseisen resurssin käyttöön.
3. Varmista oikeusalueiden (scope) tarkistus

Käytä MCP Serverin konfiguraatiota tunnisteen tarkistuksessa#

Kun MCP Server saa käyttöoikeustunnisteen, koska se itse sisältää valtuutuspalvelimen tiedon (issuer), jotkut kehittäjät tarkistavat tunnisteen vain tällä perusteella. Tämä on riskialtista: jos MCP Serverin metadata sallii useita valtuutuspalvelimia kuten:

Kehittäjä voi ottaa unverified tokenista issuer-kentän ja käyttää sitä validointipalvelimen määritysten mukaan. Mutta haitallinen käyttäjä voisi perustaa oman fake-authorization serverin ja tehdä väärennetyn tunnisteen, jonka issuer viittaa tähän ja tätä kautta tunniste saattaisi kelvata, jos validation perustuu pelkkään tokenin sisältöön.

Oikea tapa:

• Jos on vain yksi sallittu authorization server: hyväksy tunniste vain backend-konfiguroidulta valtuutuspalvelimelta
• Jos sallittu useita authorization servereita: irrota issuer unverified tokenista ja salli validointi VAIN jos se löytyy MCP Serverin confista. Jos ei löydy, tunniste hylätään.

Tarkista myös tunnisteen issuer tiukasti.

Esim. jose JWT-kirjastolla:

Tarkista tunnisteen audience (aud)#

MCP-tunnistusspeksin Token Audience Binding and Validation -osio määrää: kun asiakas pyytää valtuutuspalvelimelta käyttöoikeustunnisteen, tulee sen määritellä mihin resurssipalvelimeen tunniste on tarkoitettu. MCP Serverin tulee validoinnissa tarkistaa, että audience on juuri tämä palvelin.

Tämä perustuu Resource Indicators for OAuth 2.0 (RFC 8707) -standardiin. Prosessi pähkinänkuoressa:

1. Pyyntö: MCP Client pyytää käyttöoikeustunnistetta valtuutuspalvelimelta ja liittää mukaan resource-parametrin (esim. https://github-tools.com)

2. Tunnisteen myöntö: Authorization server kirjaa pyydetyn resource-osoitteen tokeniin, yleensä JWT:n aud-kenttään (audience)

3. Tarkistus: MCP Serverin on tarkistettava, että JWT:n audience täsmää omaan resource-tunnisteeseensa

Esim. https://github-tools.com MCP-serverin toteutuksessa:

Tämä tarkistus on keskeinen suojausmekanismi väärinkäyttöä vastaan. Jos audience-tarkistusta ei tehdä, hyökkääjä voi yrittää käyttää muulle palvelulle myönnettyjä tunnisteita väärin.

Scope-tarkistus#

Jos MCP Server hallinnoi resurssikohtaisia oikeuksia, eri käyttäjillä voi olla erilaiset scopes-arvot.

Tunnisteen validoinnin jälkeen tarkistetaan, sisältyykö vaadittu scope tokenin scopeihin:

MCP-tunnistusspeksin mukaan, jos tokenilta puuttuu vaadittu scope, palautetaan 403 Forbidden.

Yhteenveto#

Tämän artikkelin avulla osaat implementoida MCP Serverillesi tunnistusominaisuudet uusimman spesifikaation mukaan. Muista: tarkista tunnisteet turvallisesti, konfiguroi metadata oikein ja vaadi tarkka audience!

Jos rakennat MCP-palvelinta, kokeile MCP Auth -kirjastoa. Se sisältää kaikki tämän artikkelin toiminnot ja tukee nopeaa tunnistuksen liittämistä.

Keskustele kysymyksistäsi GitHubissa. Kehitetään MCP-ekosysteemiä yhdessä.