09.04.2018 | Joonas Westlin

Azure Active Directoryn v2 endpoint julkaistiin viime vuonna, ja tässä artikkelissa selvitämme mikä se on, miten se eroaa v1-endpointista, ja mihin sitä voidaan käyttää.

MIKÄ V2 ENDPOINT ON?

Azure AD:n v2 endpoint mahdollistaa ns. yhdistetyn autentikaation.

Se tarjoaa joitain uusia kykyjä, huomattavimpana kyvyn autentikoitua käyttäen joko:

  • Organisaation Office 365-tiliä (Azure AD)
  • tai henkilökohtaista Microsoft-tiliä (esim. outlook.com)

Microsoftin Graph API-rajapintaa voidaan käyttää molemmilla tilityypeillä. Sovellukselle joka käyttää tätä rajapintaa, tämä voi olla erinomainen asia.

UUSI PORTAALI SOVELLUSTEN REKISTERÖINTIIN

Käytettäessä v1 endpointia, sovellukset tulee rekisteröidä Azure AD:en esim. Azure Portalin kautta.

Mutta v2-sovellusten määritykseen käytetään toista portaalia, jonka voit löytää täältä: https://apps.dev.microsoft.com/.

Tämä on kuitenkin väliaikaista! Sovelluksia voidaan tulevaisuudessa hallita Azure-portaalissa.

Voit käyttää joko henkilökohtaista Microsoft-tiliä tai organisaatiosi Office 365-tiliä rekisteröidäksesi sovelluksia. Ero on se, että organisaatiotunnuksilla luodut sovellukset rekisteröidään käyttäjän kotitenanttiin. Tämä tarkoittaa että muut käyttäjät samasta tenantista voivat nähdä ja muokata sovellusta myös (olettaen että heidät lisätään ownereiksi sovellukseen). Sovellukset jotka rekisteröidään henkilökohtaisilla tunnuksilla näkyvät ainoastaan tälle käyttäjälle.

Eli: Jos teet sovelluksia organisaatiossa, käytä organisaatiosi tunnusta rekisteröintiportaalissa.

YKSI IDENTITEETTI KAIKILLE SOVELLUKSEN OSILLE

Azure AD v2:ssa et valitse alustaa sovellukselle luodessasi sitä kuten v1:ssä. Sen sijaan voit lisätä alustoja sovellukseen.

Add Platform dialogi

Web-alusta sisältää nyt sekä front-end Single Page Appit, että back-end Web-sovellukset. Jos teet mobiilisovellusta (tai muuta sovellusta joka ajetaan käyttäjän laitteella, pl. SPAt), se voidaan lisätä Native Applicationina. Web-rajapinnat sovelluksessasi voidaan määrittää Web API-tyyppisinä. Niihin voidaan myös määrittää nk. scopeja, joilla voitaisiin hallita mitä kaikkea toiset sovellukset voivat tehdä rajapinnassa.

Tämä on kuitenkin aika mahtava asia, koska v1:ssä sinun pitää luoda erillinen sovellus jokaiselle osalle (joka on suositeltu käytäntö), tai jakaa identiteetti osien kesken (joka ei ole mahdollista esim. API:n ja natiivisovelluksen tapauksessa).

SCOPET

Pyydettäessä access tokenia v1 endpointilta, sinun tulee määrittää resource-parametri pyynnössä. Tämä kertoo mille rajapinnalle sovelluksesi haluaa tokenin. Esimerkiksi, Microsoft Graph API:n resource URI on https://graph.microsoft.com. Tämä parametri ei kuitenkaan ole OpenID Connect-standardin mukainen. Sovelluskirjastot jotka on suunniteltu toimimaan Azure AD:n kanssa sallivat kuitenkin sen määrityksen. Muut yleiset työkalut ja sovelluskirjastot eivät kuitenkaan toimi.

Scope-parametri korvaa resource-parametrin v2:ssa. Tätä OpenID Connect-standardin mukaista parametria käytetään edelleen kertomaan mitä rajapintaa sovelluksesi haluaa kutsua. Mutta sen avulla voimme kertoa mitä oikeuksia sovelluksemme tarvitsee rajapinnassa. Esimerkiksi, sanotaan että haluamme lukea käyttäjän kalenteritapahtumat Microsoft Graph API:sta. Voit määrittää tämän vaatimuksen näin:

scope=https://graph.microsoft.com/Calendars.Read

Scopen täysi nimi muodostuu siis API:n tunnisteesta (esim. https://graph.microsoft.com) ja oikeudesta joka halutaan (esim. Calendars.Read). Voit määrittää monta scopea erottamalla ne välilyönneillä. Koska token käy aina ainoastaan yhteen rajapintaan, voit määrittää ainoastaan yhden API:n scopeja pyytäessäsi tokenia. Normaalisti sinun pitää käyttää täyttä nimeä scopelle, mutta MS Graph API on erikoistapaus. Se sallii myös ns. "lyhyen muodon":

scope=Calendars.Read

Tästä uudesta kyvystä määrittää tarvitut oikeudet on hyvä siirtyä seuraavaan aiheeseen.

Yksi v1:n isoimmista ongelmista, erityisesti multi-tenant-sovelluksissa on että sinun pitää määrittää kaikki oikeudet mitä sovelluksesi voi ikinä tarvita etukäteen. Ja käyttäjän pitää hyväkysä kaikki vaaditut oikeudet. Esimerkiksi jos sovelluksesi tarjoaa valinnaisen kalenteri-integraation Office 365:en, sinun pitää pyytää pääsy käyttäjän kalenteriin vaikkei sovelluksesi koskaan käyttäisi sitä. Tämä voidaan kiertää tosin käyttämällä toista sovellusta. v2:ssa voit määrittää oikeudet joita sovelluksesi tarvitsee kun lähetät käyttäjän kirjautumaan.

Tämä tarkoittaa, että sinun ei tarvitse määrittää oikeuksia jotka sovelluksesi tarvitsee etukäteen, vaan ne voidaan määrittää ajon aikana. Eli jos käyttäjä haluaisi ottaa käyttöön kalenteri-integraation, voimme ohjata hänet kirjautumaan uudelleen ylimääräisen scopen kanssa! Tämä yhdistettynä yksi sovellus - monta alustaa ideaan ovat ehkä parhaat osat v2-endpointissa.

KAIKKI SOVELLUKSET OVAT MULTI-TENANT

Toinen suuri ero v1:en on, että kaikki sovellukset ovat multi-tenant. Tämä muuttuu myöhemmin, jolloin pystyt määrittämään kohdeyleisön sovelluksellesi. Tämä tarkoittaa että käyttäjä voi kirjautua sovellukseesi millä tahansa henkilökohtaisella Microsoft-tunnuksella tai Azure AD-tunnuksella sovellukseesi. Jos et halua tätä, voit rajoittaa mahdollisia tyyppejä muokkaamalla kirjautumis-URL:a

  • https://login.microsoftonline.com/common/v2.0
    • Sallii minkä vain tilin
  • https://login.microsoftonline.com/organizations/v2.0
    • Sallii ainoastaan Office 365/Azure AD-tilit
  • https://login.microsoftonline.com/consumers/v2.0
    • Sallii ainoastaan henkilökohtaiset Microsoft-tilit
  • https://login.microsoftonline.com/{tenant-id}/v2.0
    • Sallii vain yhden Azure AD-tenantin

Mutta totta kai käyttäjä voi muokata tätä URL:a, joten et voi luottaa vain siihen. Sinun tulisi myös lisätä tarkistus sovelluksen puolelle, että käyttäjä tuli todellakin oikeasta lähteestä. Tenant id henkilökohtaisille Microsoft-tileille on aina sama: 9188040d-6c67-4c5b-b112-36a304b66dad. Tähän on tulossa asetus myöhemmin jolla sovellukselle voidaan määrittää kohdeyleisö. Tämä mahdollistaa myös single-tenant-skenaariot.

VAIN OPENID CONNECT JA OAUTH

Tuetut protokollat v2 endpointissa ovat OpenID Connect ja OAuth, jotka ovat erittäin yleisiä moderneissa sovelluksissa. Se ei tue vielä kaikki OAuthin kirjautumistapoja jotka ovat olleet tuettuja v1:ssä, kuten Device Profilea ja Resource Owner Password Credentials Grantia. SAML ja WS-Federation eivät ole tuettuja v2:ssa (ainakaan vielä). Ne ovat protokollia jotka ovat tuettuja v1:ssä joita käyttävät pääasiassa vanhemmat sovellukset.

MSAL

Jos olet kehittänyt sovelluksia v1 endpointille, tunnet todennäköisesti ADAL:n (Azure AD authentication Library). Koska v2 koki merkittäviä muutoksia, Microsoft päätti tehdä eri sovelluskirjaston endpointille kokonaan. Tämä uusi kirjasto on Microsoft Authentication Library (MSAL).

Tällä hetkellä kirjastosta löytyy versio .NET:lle (MSAL.NET), JavaScriptille (MSAL.JS), ja Androidille (MSAL for Android). JavaScript-versio on tehty TypeScriptillä, ja voidaan myös ottaa käyttöön ES5/ES6-moduulina. Kirjaston rajapinta muuttui jonkin verran, tässä on esimerkki access tokenin hakemisesta Authorization Code flow:lla käyttäen .NET-versiota kirjastosta:

//Hae käyttäjän tunniste
string signedInUserID = context.Ticket.Principal.FindFirst(ClaimTypes.NameIdentifier).Value;
//Luo cache tokeneille
TokenCache userTokenCache = new MSALSessionCache(signedInUserID, context.HttpContext).GetMsalCacheInstance();
//Luo objekti jolla haetaan tokeneita
var cca = new ConfidentialClientApplication(AzureAdB2COptions.ClientId, AzureAdB2COptions.Authority, AzureAdB2COptions.RedirectUri, new ClientCredential(AzureAdB2COptions.ClientSecret), userTokenCache, null);
//Hae access token (ja id token)
AuthenticationResult result = await cca.AcquireTokenByAuthorizationCodeAsync(code, AzureAdB2COptions.ApiScopes.Split(' '));
context.HandleCodeRedemption(result.AccessToken, result.IdToken);

Isoin ero on, että ADAL:lla käytetään AuthenticationContext-luokkaa tokenien hakemiseen, kun tass MSAL:ssa käytetään ConfidentialClientApplication- tai UserAgentApplication/PublicClientApplication-luokkaa, riippuen ajetaanko sovellusta back-endissä vai käyttäjän laitteella. Huomaa, että kaikki MSAL-versiot ovat "Tuotanto-valmiissa previewssä" kirjoituksen aikana. Eli kirjastot ovat täysin tuettuja, mutta ne ovat edelleen keskeneräisiä.

TÄMÄNHETKISET RAJOITUKSET JA ONGELMAT

Tässä osiossa käsittelemme v2 endpointin rajoituksia sekä ongelmia joita olemme kohdanneet. Nämä rajoitukset poistuvat ajan myötä kuitenkin! Virallista aikataulua ominaisuuksien saapumisesta ei ole. Mutta ne ovat tulossa.

Ehkä isoin rajoitus tällä hetkellä on erittäin pieni setti rajapintoja joita sovellukset voivat käyttää. Sovelluksesi voi käyttää:

  1. Omaa Web-rajapintaansa
  2. Outlook Mail, Calendar, ja Contacts REST-rajapintoja
  3. Microsoft Graph API (joka sisältää Outlookin rajapinnat)

Jos haluat käyttää mitä tahansa muuta rajapintaa, tällä hetkellä ainoa vaihtoehtosi on v1 endpoint.

Ja tällä hetkellä itsenäisten Web APIen teko ei ole mahdollista. Ainoastaan sovellus jolla on sama Application ID voi pyytää access tokenin API:lle. Eli et voi rekisteröidä API:a ja käyttää sitä toisesta sovelluksesta vielä.

Jos haluat lukea enemmän tämänhetkisistä rajoituksista, voit nähdä ne dokumentaatiosta: Azure AD v2 endpoint limitations.

Rajapinta token cacheille MSAL.NET:ssä on vähän erikoinen. Ensinnäkin, TokenCache-luokka on sealed, joten siitä ei voi periyttää omaa luokkaa kuten ADAL:ssa. Ainoa tapa on luoda instanssi TokenCache:sta ja asettaa pari tapahtuman kuuntelijaa joita kutsutaan kun dataa pitää ladata välimuistista ja kun dataa pitää tallentaa välimuistiin. Tämä ei ole sinällään huono asia, mutta funktioiden joita siinä voi käyttää on pakko palauttaa void. Mitä tämä tarkoittaa on, että emme voi käyttää asynkronista ohjelmointia vaan säie pitää tukkia kokonaan latausten ja tallennusten ajaksi. ASP.NET Core-sovelluksissa jos tulee tarpeeksi pyyntöjä sisään samanaikaisesti, tämä saattaa kaataa sovelluksen pahasti, vaatien palvelimen uudelleenkäynnistyksen. Tämän ongelman kehitystä voi seurata GitHubissa.

Tässä on pieni ote token cache-luokasta näyttäen tärkeimmät kohdat (esim. logitus poistettu):

public TokenCache GetMsalCache()
{
  //Cache luotu jo:  _cache = new TokenCache();
  _cache.SetBeforeAccess(BeforeAccessNotification);
  _cache.SetAfterAccess(AfterAccessNotification);
  return _cache;
}

private void BeforeAccessNotification(TokenCacheNotificationArgs _)
{
  byte[] cacheData = _distributedCache.Get(_cacheKey);
  if (cacheData != null)
  {
    _cache.Deserialize(_protector.Unprotect(cacheData));
  }
}
private void AfterAccessNotification(TokenCacheNotificationArgs args)
{
  if (_cache.HasStateChanged)
  {
    try
    {
      _distributedCache.Set(_cacheKey, _protector.Protect(_cache.Serialize()));
    }
    catch (Exception e)
    {
      throw;
    }
    _cache.HasStateChanged = false;
  }
}

Nyt emme voi hyötyä asynkronisista funktioista joita IDistributedCache tarjoaa, ja tukimme koko säikeen kunnes saamme vastauksen cachesta. Sama ongelma on myös ADAL:ssa kylläkin.

On myös tärkeää huomata, että v1 sovellukset eivät voi käyttää v2 endpointia. Vastaavasti v2 sovellukset eivät voi käyttää v1 endpointia. Migraatiopolkua v1 sovelluksille ei ole vielä. Mutta v2 sovellusten hallinta on suunniteltu siirtymään Azure-portaalin puolelle, jossa v1 sovelluksia hallitaan nyt. Kun se tapahtuu, nykyiset v1 sovellukset kykenevät käyttämään v2 endpointia, ja migraatiopolku tulee olemaan dokumentoitu.

Törmäsimme myös jonkin aikaa sitten ongelmaan, joka ei enää tapahdu. Ongelma oli siis, että consentin antaminen ei toiminut kunnolla. Meni noin 15 sekuntia consentin antamisesta että oikeudet toimivat. Tämä ongelma näyttää olevan korjattu nyt.

KOSKA V2-ENDPOINTIA KANNATTAA KÄYTTÄÄ

Tällä hetkellä sovellukset joihin v2 endpoint sopii parhaiten:

  1. Sallivat pääsyn sekä henkilökohtaisilla MS-tileillä että organisaatioiden Azure AD-tileissä
  2. Käyttävät ainoastaan omaa Web API:a/MS Graph API:a/Outlook-rajapintoja

Suurimpaan osaan muista skenaarioista Azure AD v1 on edelleen parempi vaihtoehto. Microsoft suosittelee v1:n käyttöä sovellukselle jotka haluavat ainoastaan sallia Azure AD/Office 365-käyttäjät. Kun v2 endpoint kehittyy ja saa enemmän v1 endpointin ominaisuuksista, siitä tulee paras vaihtoehto uusille sovelluksille.

YHTEENVETO

Azure AD:n v2 endpointissa on monta todella hyvää ideaa. Dynaaminen consent sekä kyky määrittää alustoja sovellukseen ovat todella loistavia ominaisuuksia. Se on kuitenkin edelleen keskeneräinen. Mutta Microsoft kehittää sitä jatkuvasti, ja lisää ominaisuuksia v1 endpointista lisätään ajan myötä.

LINKKEJÄ DOKUMENTAATIOON