Entra ID tekninen dokumentaatio

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.

• UusiApp registration - PowerShell
• UusiApp registration - GUI
• Client secret -vaihtoprosessi

Lista tiedoista, jotka lisätään MPASSid-hallintapalvelussa

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.

Huom! mikäli käytätte on extensionAttribute-muotoisia attribuutteja, ne näkyvät Graph API:n kautta poikkeavasti verrattuna muihin attribuutteihin. Hallintapalveluun ne tulee määritellä muodossa: "onPremisesExtensionAttributes.extensionAttribute2", "onPremisesExtensionAttributes.extensionAttribute14" jne.

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 {
    param (
        [Parameter()]
        [string] $clientID,
        [Parameter()]
        [string] $clientSecret,
        [Parameter()]
        [string] $tenantID,
        [Parameter()]
        [string] $userPrincipalName,
        [Parameter()]
        [string] $optionalAttributes
    )
 
 
    $ReqTokenBody = @{
        Grant_Type    = "client_credentials"
        Scope         = "https://graph.microsoft.com/.default"
        client_Id     = $clientID
        Client_Secret = $clientSecret
    }
     
    $TokenResponse = Invoke-RestMethod -Uri "https://login.microsoftonline.com/$TenantID/oauth2/v2.0/token" -Method POST -Body $ReqTokenBody
 
    if ( !$optionalAttributes )
    {
        $apiUrl = "https://graph.microsoft.com/v1.0/users/" + $userPrincipalName
    } else {
        $apiUrl = "https://graph.microsoft.com/v1.0/users/" + $userPrincipalName + "?`$select=displayName,givenName,surname,userPrincipalName,id,$optionalAttributes "
    }
 
    $Data = Invoke-RestMethod -Headers @{Authorization = "Bearer $($Tokenresponse.access_token)"} -Uri $apiUrl -Method Get
 
    return ( $data )
}
 

# 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-hallintapalvelussa lisättävät tiedot integraatiotyypistä riippumatta

MPASSid-integraation rakentamista varten jokaisen koulutustoimijan on lisättävä alla olevat tiedot MPASSid-hallintapalvelussa.

1. Oppilaitostyypit, joilla aiotte MPASSid:tä käyttää. Hyväksytyt oppilaitostyypit koodiarvoineen löytyvät täältä: https://koski.opintopolku.fi/koski/dokumentaatio/koodisto/oppilaitostyyppi/latest

2. Kunnan/koulutustoimijan logotiedoston, jonka haluatte näytettävän MPASSid:n koulunvalintasivulla.

   • Logo: png-muodossa, koko 125x36 px.