SAML-autentikointi

SAML 2.0 on XML-pohjainen protokolla, joka välittää käyttäjätietoja identiteetin tarjoajan (Identity Provider, IdP) ja palveluntarjoajan (Service Provider, SP) välillä. Collection Pro toimii palveluntarjoajana ja voidaan yhdistää ulkoiseen identiteetin tarjoajaan.

Collection Pron SAML-metatiedot

Collection Pro tarjoaa metatieto-URL-osoitteen, joka voidaan toimittaa identiteetin tarjoajalle:

https://asiakas.collectionpro.fi/api/saml/metadata

Korvaa asiakas.collectionpro.fi oman instanssisi osoitteella.

Joissain tapauksissa metatiedot täytyy ladata XML-tiedostona ja toimittaa manuaalisesti IdP:lle.

Muut URL-osoitteet

• ACS (Assertion Consumer Service):
  https://asiakas.collectionpro.fi/api/saml/acs
• Kirjautumisen uloskirjaus-URL:
  https://asiakas.collectionpro.fi/api/saml/slo

IdP:n metatieto-URL

Lisää identiteetin tarjoajan metadata-URL Collection Pron asetuksiin. Tämä kenttä on pakollinen.

Palveluntarjoajan EntityID

Valinnainen kenttä. Jos jätetään tyhjäksi, käytetään oletusarvoa:

https://asiakas.collectionpro.fi/api/saml/metadata

Korvaa domain omalla instanssisi osoitteella.

Attribuutit ja käyttäjien yhdistäminen

Käyttäjät yhdistetään Collection Pron käyttäjätileihin SAML-attribuuttien perusteella. Esimerkkejä:

Attribuutti	Kuvaus
%(login)s tai %(sAMAccountName)s	Vastaa käyttäjätunnusta IdP:n datassa
%(displayName)s	Käyttäjän näyttönimi
%(email)s	Käyttäjän sähköpostiosoite (yksilöllinen Collection Prossa)
%(urn:oasis:names:tc:SAML:attribute:subject-id)s	Viiteattribuutti, toimii yksilöllisenä tunnisteena

⚠️ Huom: Sähköpostiosoitteiden on oltava yksilöllisiä Collection Prossa. Jos sama osoite on jo käytössä, SAML-kirjautuminen estetään.

Käyttäjän päivitys

Määritä, minkä attribuutin perusteella tarkistetaan, onko käyttäjällä jo olemassa oleva tili. Oletuksena käytetään Viite-attribuuttia, mutta voit käyttää myös Email tai Login.

Esimerkki:
Jos sähköposti on valittu tunnistamiseen ja käyttäjän osoite muuttuu, järjestelmä luo uuden tilin. Käyttäjällä voi tällöin olla kaksi erillistä tiliä.

Allekirjoita pyynnöt

Valinnainen asetus (oletuksena pois päältä). Joissain ympäristöissä vaaditaan, että Collection Pro allekirjoittaa autentikointipyynnöt. Tämä vaatii vähintään version v6.12.0.

Testaus: mocksaml.com

Voit testata SAML-konfiguraatiota käyttämällä mocksaml.com -palvelua.

1. Sertifikaatin ja avaimen luominen

openssl genrsa -out private.key 4096
openssl req -new -x509 -key private.key -out publickey.cer -days 365

Common Name: käytä Collection Pron osoitetta, esim. asiakas.collectionpro.fi.

2. Sertifikaatin syöttäminen Collection Prohon

Syötä private.key ja publickey.cer -tiedostojen sisältö Collection Pron hallintaliittymään.

3. Perusasetukset

• Metadata-URL: Käytä mocksaml.comin osoitetta:
  https://mocksaml.com/api/saml/metadata
• Lokitus: Suositellaan valitsemaan ”Kirjoita vaiheet lokiin”
• Käyttäjien yhdistäminen: Määritä, miten käyttäjät yhdistetään

4. Yhteyden testaus

Kirjaudu ulos tai käytä yksityistä selainta. Siirry kirjautumissivulle ja valitse SAML-kirjautuminen. Kirjautumisen jälkeen tarkista, että käyttäjä on luotu Collection Prohon (vain pääkäyttäjät näkevät tämän).

Microsoft Entra -integraatio

1. Siirry kohtaan Enterprise apps
   
2. Valitse New application
   
3. Valitse Create your own application
   
4. Nimeä sovellus ja valitse Non-gallery, klikkaa Create
   
5. Siirry sovelluksen asetuksiin → Single sign-on → valitse SAML
   
6. Valitse Edit kohdassa ”Basic SAML Configuration”.
7. Syötä seuraavat tiedot.
   Korvaa domain omalla instanssisi osoitteella.
   • Identifier (Entity ID)
     https://asiakas.collectionpro.fi/api/saml/metadata
     tai vaihtoehtoisesti Collection Pron asetuksissa määritelty kustomoitu Entity ID.
   • Reply URL (Assertion Consumer Service URL):
     https://asiakas.collectionpro.fi/api/saml/acs
   • Logout Url (Kirjautumisen uloskirjaus-URL):
     https://asiakas.collectionpro.fi/api/saml/slo
     
   • Tallenna asetukset
     
8. Ryhmäclaimien määrittäminen
   • Siirry kohtaan Attributes & Claims
   • Klikkaa Edit → Add a group claim
     
     
     
   • Valitse tarpeen mukaan mitä ryhmätietoja halutaan sisällyttää SAML-tunnisteeseen. Suositellaan käytettäväksi asetusta ”Groups assigned to the application”.
     
     None – Ei sisällytetä ryhmätietoja
     All groups – Sisällyttää kaikki ryhmät (ei suositella)
     Security groups -Sisällyttää vain turvaryhmät
     Directory roles – Sisällyttää hakemistoroolit
     Groups assigned to the application – Sisällyttää vain sovellukselle määritetyt ryhmät (suositeltu)
   • Tallenna ja poistu
     
9. Kopioi App Federation Metadata URL ja lisää se Collection Pron IdP URL-osoite -kenttään tai toimita se Collection Pron tukeen.
   
   
10. Kirjautumisen testaus
    Kun asetukset on määritetty sekä identiteetin tarjoajassa (Microsoft Entra) että Collection Prossa, voit testata kirjautumisen. Kirjautumissivu ohjaa käyttäjän IdP:n kirjautumissivulle, ja onnistuneen kirjautumisen jälkeen käyttäjä luodaan tai päivitetään Collection Prossa.