Henri Mikkonen edited this page Nov 19, 2018 · 26 revisions

Welcome to the MPASSid-proxy wiki!

This wiki contains documentation for MPASSid proxy. The documentation contains also descriptions about our automation processes, which might occasionally be Finland specific and needs to be modified when MPASSid proxy is used elsewhere.

If you are implementing a service which would use MPASSid as an authentication method, you are implementing a SAML service provider.

Technical documentation

Architecture

SAML Profile

The SAML profile is based on SAML2int profile v0.2.1 with the following constraints:

  • All the production service endpoints must use https-scheme
  • Only urn:oasis:names:tc:SAML:2.0:nameid-format:transient name identifier format is supported

Request message

SP must send the SAML authentication request message using the urn:oasis:names:tc:SAML:2.0:bindings:HTTP-Redirect binding. An example of such a message is as follows (one sent by the test-application:

GET https://mpass-proxy-test.csc.fi/idp/profile/SAML2/Redirect/SSO?SAMLRequest=fZJfb8IgFMW%2FSsN7S2nrnxHbxOnDTNw0ttvDXhaKOEkodFy66bcfWrfoiwlPcO459%2FzCBFijWjrt3F5vxFcnwAWHRmmg54ccdVZTw0AC1awRQB2n5fR5SZMopq01znCjUDAFENZJo2dGQ9cIWwr7Lbl43SxztHeupRiThyQiw3EUR2QQ43Iv69oo4fYRgMEnzwSvV2WFgrlfQmp2suuHwU83LQMIfeLhGDoviDjwaCex3LbY3%2B6kEheTjdhKK7jDZblCwWKeo4%2BHbLgd7diIjHmW1mld72JSJ%2F7wLKuzwcDLADqx0OCYdjlKYjIMSRImaRWPaZzSLH1HwfpS91HqrdSf99nUvQjoU1Wtw77Ym7BwLuUFqJicCNNzsL1ift%2BW%2FYFGxS0Z1raRMpwpDP9kJ%2Fgqos9r6Yv3XMzXRkl%2BDKZKmZ%2BZFcyJHBGEi37k9kMUvw%3D%3D&RelayState=ss%3Amem%3Abac1532652ab535b61b858e9e3ce81d38e2f3d00aa40f0465301711b7a461a7f HTTP/1.1

The decoded SAMLRequest -parameter looks as following:

<samlp:AuthnRequest xmlns:samlp="urn:oasis:names:tc:SAML:2.0:protocol"
                    AssertionConsumerServiceURL="http://192.168.0.150/Shibboleth.sso/SAML2/POST"
                    Destination="https://mpass-proxy-test.csc.fi/idp/profile/SAML2/Redirect/SSO"
                    ID="_946d7fa718c43b3bbf01b21b2c44b455"
                    IssueInstant="2016-12-23T08:03:43Z"
                    ProtocolBinding="urn:oasis:names:tc:SAML:2.0:bindings:HTTP-POST"
                    Version="2.0"
                    >
    <saml:Issuer xmlns:saml="urn:oasis:names:tc:SAML:2.0:assertion">https://mpass-app.local/shibboleth</saml:Issuer>
    <samlp:NameIDPolicy AllowCreate="1" />
</samlp:AuthnRequest>

Response message

The response message is sent via urn:oasis:names:tc:SAML:2.0:bindings:HTTP-POST binding. The response contains one signed SAML assertion, containing the attributes defined in the next section.

Data models

Data model 1.0

The MPASS proxy issues the following SAML attributes about authenticated users:

  • urn:oid:2.5.4.4 (single value): The last/family name of the user.
  • urn:oid:2.5.4.42 (single value): The first/given name of the user.
  • http://eidas.europa.eu/attributes/naturalperson/CurrentGivenName (single value): All the first/given names of the user.
  • urn:mpass.id:uid (single value): The unique identifier of the authenticated user. Currently recommended identifier for identifying the user. NOTE: will change if the user moves to another user registry.
  • urn:mpass.id:legacyCryptId (single value): The legacy (national) cryptID of the user divided to two parts with @ -character. The left-side contains the cryptID of the user as right-side contains an identifier to the source registry. For instance: f0ba7691aeff3ef2302d6edce5303641@ldap_test. This attribute is issued for legacy reasons, avoid using it if possible.
  • urn:mpass.id:legacyCryptIde (single value): A strengthened version of the legacy cryptID (see above) of the user, divided to two parts with @ -character. The left-side contains the strengthened (encrypted by MPASS proxy) version of the cryptID of the user as right-side contains an identifier to the source registry. For instance: 9ecb8b0256d0c177320037322cf87e4f1211f2df45a2f8e4a667ca5b24a10e89@ldap_test.
  • urn:mpass.id:municipalityCode (multi value): The municipality code of the authenticated user. See http://tilastokeskus.fi/meta/luokitukset/kunta/001-2017/index.html for mappings in Finland.
  • urn:mpass.id:municipality (multi value): The human-readable name of the municipality of the authenticated user.
  • urn:mpass.id:schoolCode (multi value): The school code of the authenticated user. See https://virkailija.opintopolku.fi/koodisto-service/ for the mappings in Finland. For example, https://virkailija.opintopolku.fi/koodisto-service/rest/codeelement/oppilaitosnumero_04647 for school code 04647.
  • urn:mpass.id:school (multi value): The human-readable name of the school of the authenticated user.
  • urn:mpass.id:class (multi value): The class/group-information of the authenticated user. For instance: 8A or 3B.
  • urn:mpass.id:classLevel (multi value): The class/level-information of the authenticated user. For instance 8 or 3.
  • urn:mpass.id:role (multi value): The role of the user in four parts, divided with a semicolon (;) character. First municipality, followed by school code, group and role in the group. For instance Helsinki;32132;9A;Oppilas.

All the attributes are issued in the SAML NameFormat urn:oasis:names:tc:SAML:2.0:attrname-format:uri.

Old data model

In addition to the data model 1.0, the MPASS proxy currently issues also the following SAML attributes about authenticated users. However, the same information exists in the data model 1.0:

  • urn:educloudalliance.org:OID (single value): The object identifier of the user.
  • urn:educloudalliance.org:municipality (multi-value): The municipality of the user.
  • urn:educloudalliance.org:school (multi-value): The school of the user.
  • urn:educloudalliance.org:structuredRole (multi-value): The role of the user in four parts, divided with a semicolon (;) character. First municipality, followed by school, group and role in the group.

All the attributes are issued in the SAML NameFormat urn:oasis:names:tc:SAML:2.0:attrname-format:uri.

Dependencies

Other services used

Customer eXperience

With customer we include municipalities and service providers. This Chapter describes the processes for each group. Aim is to automate the process as far as possible to minimize human errors, delays and need for people in the process.

  1. On-boarding new municipality
  2. On-boarding new service provider

Developer eXperience

Integration (APIs)

What APIs; name and purpose, link to code repository and link to API management

How to take API into use?

You can’t perform that action at this time.
You signed in with another tab or window. Reload to refresh your session. You signed out in another tab or window. Reload to refresh your session.
Press h to open a hovercard with more details.