Tässä pieni ohje kuinka Azure AD:lla suojattuja funktioita kutsutaan Single Page – sovelluksesta. Tämä saattaa kuulostaa triviaalilta, mutta ajantasaisten ohjeiden löytäminen vaati tällä kertaa noin kaksi työpäivää. Toteutus kesti tämän jälkeen noin tunnin.

Tavoite

Lyhyesti: Haluan kutsua Azure AD:lla suojattuja Funktioita Single Page (SPA) sovelluksestani.

Valitsin kokeilujeni pohjaksi “microsoft msal.js demo app for vanilla javascript” – esimerkin. Yksinkertainen html-sivu, joka kutsuu puhtaalla javascriptillä ulkoisia rajapintoja. Voin laittaa sen kutsumaan omaa AAD suojattua Azure funktiota muuttamalla esimerkkikoodia hieman.

Menetelmästä: Tällä hetkellä Microsoft haluaa kehittäjien käyttävän MSAL.js – kirjastoa käyttäjän sisäänkirjaukseen ja tokenien noutamiseen javascript-sovelluksissa. Käytössä oleva protokolla on AADv2. Esimerkkisovellus näyttää mallikkaasti kuinka kirjastoa käytetään alustamaan käyttäjän sisäänkirjaus, ja sen jälkeen miten sen avulla kutsutaan ulkoisia API-rajapintoja. Tästä on hyvä jatkaa.

Esimerkkisovelluksen muutokset

Muutin mallisovelluksen readEmail() – funktiota niin, että se kutsuu minun omaa Azure AD:lla suojattua funktiota, eikä sähköposteja noutavaa Graph APIa. Alla täsmällisempi lista mitä sovellukseni lopulta teki:

  • Käyttäjä avaa SPA-sovelluksen staattisen html-sivun selaimessa.
  • Käyttäjä klikkaa “Login”-nappia.
  • msal.js avaa ponnahdusakkunan, joka vie käyttäjän Microsoftin Azure AD:n loginsivulle.
  • Käyttäjä kirjautuu sisään, ja mahdollisesti samalla antaa luvan sovellukselle tehdä mitä sovelluksen pitää tehdä.
  • Login-toiminnon päätteeksi login-sivu lähettää taustalla käyttäjän selaimeen käyttäjätietoja sisältävän keksin, ja tämän jälkeen msal.js hävittää popup-akkunan.
  • Seuraavaksi haluaisimme kutsua omaa funktiota.
  • Ennen funktiokutsua käytämme jälleen msal.js – kirjastoa noutamaan Auth – tokenin Azure AD:sta.
  • Tämän jälkeen kutsumme funktiota normaalisti. Ainoa ero on, että laitamme kutsuun “Authorization”: “Bearer “+tokenin jonka saimme msal-kutsun tuloksena.
  • Tee mitä haluat saamallasi funktion vastauksella. Alert on aina hyvä vaihtoehto testauksessa.

401 – forbidden

Ongelmat alkoivat kun vaihdoin esimerkin readMail() kutsun osoittamaan omaan funktiooni. Vastaus oli tyly: 401 – Forbidden. Virheilmoitus ei sisältänyt minkäänlaista selitystä tähän.

Ongelma oli lopulta App Registration – osuudessa. Mallisovellus vaati ainoastaan SPA-sovelluksen rekisteröinnin Azure AD:hen. Jos kutsut omaa API rajapintaasi etkä valmiita Microsoftin rajapintoja, oma rajapintasi on myös rekisteröitävä erikseen AAD:ssa. Ongelma ryhtyi avautumaan kun löysin sivun, joka kuvaa eri tunnistautumisvaihtoehdot: Tutorial – Enable your Web Apps to sign-in users and call APIs with the Microsoft identity platform for developers. Edellisen alta löytyy alisivu, “Call your own API“, jossa tässä tapauksessa tarvittava sovellusten rekisteröintitapa oli kuvattu. Sivun ohjeita seuraamalla päädyt lopulta seuraavan kaltaiseen rakenteeseen:

Kuva: Kuva: Single page -sovellus, funktiot ja sovellusten AAD-rekisteröinnit.

Mikä on Scope?

Kun molemmat sovellusrekisteröinnit on nyt luultavasti tehty oikein, esimerkkisovelluksessa oli jäljellä enää yksi mysteeri: Mikä on scope, joka välitetään tokenin noutokutsun mukana? En oikeastaan vieläkään tiedä. Se on vain jotain, mikä on oltava kutsussa mukana.

const loginRequest = {
   scopes: ["openid", "profile", "User.Read"]
}

const tokenRequest = {
   scopes: ["Mail.Read"]
};

Koodi: Esimerkkisovelluksen Scope-määritelmät

Esimerkkisovellus käytti näitä kutsuakseen loginia, ja myöhemmin Graph APIa hakeakseen käyttäjän sähköpostit. Mitä scope – määritystä minun on käytettävä omassa funktiokutsussani? Jos arvaat väärin – 401 Forbidden. Vastaus löytyy omasta Function App Registration – määrityksestäsi. Jatka lukemista.

“Function App Azure AD Login Express setup”

Kun laitat päälle Azure AD-tunnistautumisen funktiollesi, oletuksena tarjottu “Express setup” tekee Azure AD App registrationin oletus AD:seen. Voit katsoa tarkemmin rekisteröintiä Azure-portaalissa valitsemalla vasemmasta palkista Azure Active Directory, ja sen alla App Registrations. Voit ehkä joutua vielä klikkaamaan näytä “All app registrations” löytääksesi sovelluksesi. Valitse sovellus nähdäksesi rekisteröinnin tiedot.

Azure AD:lla suojattujen API – sovellusten täytyy julkaista API – Expose an API – jotta muut sovellukset pystyvät käyttämään rajapintaa ilman 401 Forbidden – ilmoitusta. Express-asetus on jo julkaissut APIn – näet jo yhden Scopen listalla. Klikkaa riviä. Etsimäsi merkkijono löytyy täältä:

 

Expose Api

Scope Name

Kuva: Expose an API – Scope Name

Ylläolevan kaltainen merkkijono on Scope, joka sinun täytyy laittaa SPA-koodiisi!

Jos rekisteröit Single Page – sovelluksen tämän sivun ohjeiden mukaisesti, teoriassa kaikki on nyt paikoillaan. Varmista vielä, että SPA koodin msalConfig viittaa Single Page App – rekisteröintiin (client id ja joissain tapauksissa tenant id), ei function appin. Ja tietysti – vaihda kutsun https endpoint osoittamaan omaan funktioosi, eikä sähköposteja noutavaan Graph APIin…

// initialize MSAL
    const msalConfig = {
        auth: {
            clientId: "Enter_your_client_id",
            authority: "https://login.microsoftonline.com/common",
            validateAuthority: true
        },
        cache: {
            cacheLocation: "localStorage",
            storeAuthStateInCookie: false
        }
    };

const funcObjScope = {
    scopes: ["https://anotherv.azurewebsites.net/user_impersonation"]
};

Koodi: msalConfig sojottaa Single Page App – rekisteröintiin. Tee itsellesi oma scope, joka on todennäköisesti muotoa  “https://funkkarin.osoite.net/user_impersonation”.

Siinäpä se suurinpiirtein oli. Funktiokutsun pitäisi nyt toimia oikein. Kuten huomasit, monta liikkuvaa osaa täytyy osua kohdalleen jotta kokonaisuus toimii. Kunhan oikeat esimerkit ja dokumentit lopulta löytyivät, itse toteutus oli tässäkin tapauksessa muutaman minuutin juttu.

Linkit

 

Kun huomaat että tässä kuvattu menetelmä ei enää toimi, laita kommenttia tulemaan!

Siihen asti – Enjoy!