Tässä dokumentissa kuvataan MPASSid palvelun käyttöönottaminen Azure AD -integraatiota hyödyntäen. Ennakkovaatimuksena integraatiolle on että MPASSid tietomallin mukaiset tiedot ovat luettavissa käyttäjähakemistosta. Lisätietoja tietosisällöllisistä vaatimuksista löytyy täältä: https://wiki.eduuni.fi/x/8rMID
App registration luonti
MPASSid tarvitsee Azure AD tenanttiinne App registration sovelluksen, jonka kautta käyttäjän attribuutit noudetaan kirjautumisen yhteydessä. Alla olevien ohjeiden avulla voit luoda Azure AD tenanttiisi MPASSid:n tarvitseman App registration:n tarvittavilla asetuksilla. App registration:n luodaan joko GUIn tai PowerShellin kautta, voit itse valita kumpaa tapaa käytät.
Suosittelemme myös tutustumaan jo etukäteen Client secret vaihtoprosessiin.
Lista vaadittavista tiedoista
Selite | Azure AD attribuutti (Graph API:n tarjoama kirjoitusasu) | Pakollinen | Huomioita |
---|---|---|---|
Huom! attribuutteihin saattaa tulla muutoksia, huomioi voimassaoleva tietomalli | |||
Sukunimi | x | ||
Etunimi | x | ||
Kutsumanimi | Tietomallissa 1.4 alkaen | ||
Koulukoodi | x | ||
Luokka tai ryhmä | (x) | Pakollinen perusasteen oppilaille. | |
Luokka-aste | (x) | Pakollinen perusasteen oppilaille. | |
Rooli | x | ||
Kansallinen oppijanumero | x | ||
Oppimateriaalien maksullisuus | (x) | Pakollinen toisen asteen opiskelijoille. | |
Muut pakolliset tiedot | |||
Directory (tenant) ID | x | ||
Application (client) ID | x | ||
Client secret (Value EI Secret ID) | x | Tämä tulee lähettää turvapostilla. Toimita myös avaimen voimassaolon päättymisajankohta | |
Application ID URI | x | Muoto: (api://<guid>) | |
Oppilaitostyypit | x - jos uusi integraatio | ||
Logo | x - jos uusi integraatio | 125x36px png-muodossa | |
Koulutuksenjärjestäjän OID | x - jos uusi integraatio | ||
Redirect URI | OPH toimittaa tämän koulutuksenjärjestäjälle |
Huom! attribuuttien nimet eivät Azure AD:n graafisessa hallintaliittymässä vastaa Graph API:n kautta haettavia nimiä. Voit tarkistaa attribuuttien oikeellisuuden Microsoftin API-dokumentaation avulla, tai tämän sivun lopusta löytyvällä PowerShell funtiolla. Voit myös hyödyntää tämän sivun lopun "Esimerkki funktion käytöstä" optionalAttributes -listaa, jossa on listattu iso osa MPASSid:n muissa Azure AD integraatiossa käytössä olevia attribuutteja.
Azure AD attribuuttien nimien varmistaminen
Azure AD:ssa attribuuttien tekniset nimet saattavat poiketa graafisen käyttöliittymän nimistä. MPASSid hakee tiedot Microsoft Graph API:n kautta. Sitä kautta noudettaessa tulee tietää attribuuttien tekniset nimet ja attribuuttien kirjainkoonkin tulee olla oikein (surname vs Surname).
Alla olevan powershell funktion avulla voi varmistaa attribuuttien kirjoitusasun hakemalla esimerkiksi jonkin Azure AD:ssa olevan testitunnuksen tiedot. Onkin suositeltavaa testata ensin sen avulla attribuuttien oikea kirjoitusasu.
Funktio copy-pastetaan powershell ikkunaan ja sen jälkeen sitä kutsutaan getAccountAttributes -komennolla samassa ikkunassa.
function getAccountAttributes { |
# Esimerkki funktion käytöstä. # Ilman -optionalAttributes parametria komento hakee käyttäjäobjektin perustiedot (näyttönimi, etunimi, sukunimi ja UPN). # Voit lisätä -optionalAttributes parametriin lisää attribuuttien nimiä pilkulla eroteltuina. # Vaihda x, y, ja z arvoiksi yllä luomasi App registration:n ja Azure AD tenantin tiedot. getAccountAttributes -clientID "xxxxxxxxxxxxxxxxxxxxxxx" -clientSecret "yyyyyyyyyyyyyyyyy" -tenantID "zzzzzzzzzzzzzzzzzzzz" -userPrincipalName "<haettavatunnus@domain.onmicrosoft.com>" -optionalAttributes "city,companyName,Department,department,faxNumber,jobTitle,officeLocation,onpremisesextensionattributes,postalCode,state,streetAddress"
MPASSid-integraation rakentamista varten jokaisen koulutustoimijan on ilmoitettava seuraavat tiedot palveluosoitteeseemme mpass(at)oph.fi . Kunnan/koulutustoimijan logotiedoston, jonka haluatte näytettävän MPASSid:n koulunvalintasivulla. Kun nämä tiedot on lähetetty MPASSid:lle ja liittymissopimukset ovat allekirjoitettuna molempien osapuolten toimesta, saadaan integraatio päälle usein parin arkipäivän kuluessa.OPH:lle toimitettavat tiedot integraatiotyypistä riippumatta