This is an unofficial OmniAuth strategy for authenticating with the MPASSid
identification service used by comprehensive schools and secondary education
facilities in Finland. This gem is mostly a configuration wrapper around
omniauth-saml
which uses
ruby-saml
for SAML 2.0 based
authentication implementation with identity providers, such as MPASSid.
The gem can be used to hook Ruby/Rails applications to the MPASSid identification service. It does not provide any strong authorization features out of the box, as it does not know anything about the application users, but those can be implemented using this gem and the data provided by the MPASSid identification responses.
The gem has been developed by Mainio Tech.
The development has been sponsored by the City of Helsinki.
The MPASSid service is owned by the Ministry of the Education and Culture in Finland and operated by CSC - Tieteen tietotekniikan keskus Oy. Neither of these parties are related to this gem in any way, nor do they provide technical support for it. Please contact the gem maintainers in case you find any issues with it.
In order to start using the MPASSid authentication endpoints, you will need to send a join request to the MPASSid operator for them to configure the identity provider server for your service. Please refer to the MPASSid documentation on how to join the service:
https://wiki.eduuni.fi/display/CSCMPASSID/Testipalveluun+liittyminen
Follow the instructions for the SAML2 protocol.
The details that you need to send to MPASSid are similar to the following information (apply to your service's domain) for non-Rails+Devise applications:
- SAML2 entity ID: https://www.service.fi/auth/mpassid/metadata
- Callback URL (ACS): https://www.service.fi/auth/mpassid/callback
When applying this gem to Rails and Devise, the URLs can also include a path
prefix to separate the scope of the authentication requests. For example, if
you are using a :user
scope with Devise, the URLs would look like following:
- SAML2 entity ID: https://www.service.fi/users/auth/mpassid/metadata
- Callback URL (ACS): https://www.service.fi/users/auth/mpassid/callback
This gem has been only tested and used with Rails applications using Devise, so
this installation guide only covers that part. In case you are interested to
learn how you can use this with other frameworks, please refer to the
omniauth-saml
documentation and
apply it to your needs (changing the strategy name to :mpassid
and strategy
class to OmniAuth::Strategies::MPASSid
).
To install this gem, add the following to your Gemfile:
gem 'omniauth-mpassid'
For configuring the strategy for Devise, add the following in your
config/initializers/devise.rb
file:
Devise.setup do |config|
config.omniauth :mpassid,
# The mode needs to be either :production or :test depending on which
# MPASSid enviroment you want to hook into. Please note that you will need
# to complete the preparation phases even for the test environment.
mode: :test, # :production (default, can be omitted) or :test
# The service provider entity ID that needs to match the ID you have sent to
# the MPASSid operator with your joining request.
sp_entity_id: 'https://www.service.fi/auth/mpassid/metadata'
end
Once the gem is installed and configured properly, it can be tested with the test accounts available at:
https://wiki.eduuni.fi/display/OPHPALV/Test+accounts+available+for+testing
The user's data is transmitted from MPASSid in the SAML authentication response. This data will be available in the OmniAuth extra hash.
In order to access the response data, you can fetch the OmniAuth extra has and the corresponding user data in the OmniAuth callback handler, e.g. in Rails Devise controllers as follows:
def saml_attributes
raw_hash = request.env["omniauth.auth"]
extra_hash = raw_hash[:extra]
extra_hash[:saml_attributes]
end
The user's personal information transmitted from MPASSid can be found under
the :saml_attributes
key in the OmniAuth extra hash described above.
This attributes hash will contain the keys described in this following sub-sections.
See also the MPASSid data models documentation for more information:
https://wiki.eduuni.fi/display/OPHPALV/MPASSid%3An+tietomalli
The attributes can be either single or multi type defining whether they can
have a single or multiple values. The single type values are strings and multi
type values are arrays of string when the value exists in the SAML response.
When the value was not returned from the identity provider's endpoint, the value
is nil
for both types.
- SAML URI: urn:oid:2.5.4.42
- SAML FriendlyName: givenName
- Type: Single (
String
)
The given name of the user.
- SAML URI: urn:mpass.id:nickname
- SAML FriendlyName: nickname
- Type: Single (
String
)
The first name / calling name / nickname of the user.
- SAML URI: urn:oid:2.5.4.4
- SAML FriendlyName: sn
- Type: Single (
String
)
The last/family name of the user.
- SAML URI: urn:mpass.id:educationProviderInfo
- SAML FriendlyName: mpassEducationProviderInfo
- Type: Multi (
Array<String>
)
Information about the educational provider, each value contains multiple fields
separated with a semicolon (;
) character.
For instance 1.2.246.562.10.494695390410;Virallinen nimi
.
The description of the fields:
- The educational provider's OID as specified at the link below (
KOULUTUSTOIMIJA
) - The educational provider's name as specified at the link below
The OIDs and information for these OIDs can be found from:
https://virkailija.opintopolku.fi/organisaatio-service/swagger-ui/index.html
- SAML URI: urn:mpass.id:schoolInfo
- SAML FriendlyName: mpassSchoolInfo
- Type: Multi (
Array<String>
)
Information about the school, each value contains multiple fields separated with
a semicolon (;
) character.
The values are provided in both of the following formats as separate values:
30076;Mansikkalan testi peruskoulu
1.2.246.562.99.00000000002;Mansikkalan testi peruskoulu
The first value format specifies the national educational institution code as
the first column separated with a semicolon (;
) as specified at the national
educational institution registry.
For the list of codes, see:
- JSON format: https://virkailija.opintopolku.fi/koodisto-service/rest/json/oppilaitosnumero/koodi
- XML format: https://virkailija.opintopolku.fi/koodisto-service/rest/oppilaitosnumero/koodi
An example for a single school code (04647), JSON format:
https://virkailija.opintopolku.fi/koodisto-service/rest/codeelement/oppilaitosnumero_04647
The second value format specifies the OID of the educational institution as
the first column separated with a semicolon (;
). These values are specified
at (filter with OPPILAITOS
):
https://virkailija.opintopolku.fi/organisaatio-service/swagger-ui/index.html
- SAML URI: urn:mpass.id:classLevel
- SAML FriendlyName: N/A
- Type: Single (
String
)
The class level information (0-10) of the authenticated user.
For instance 8 or 3.
For further information, see:
https://www.stat.fi/meta/kas/vuosiluokka.html
This information is available for pre-primary education and comprehensive education students.
This information is not available for secondary level students (upper secondary education or vocational education).
- SAML URI: urn:mpass.id:classLevel
- SAML FriendlyName: N/A
- Type: Multi (
Array<String>
)
Specifies for secondary level education pupils whether their learning materials
are paid or not, each value contains multiple fields separated with a semicolon
(;
) character.
The values are provided in both of the following formats as separate values:
0;00000
0;1.2.246.562.99.00000000003
Similarly to the :school_info
field, the values are provided with the national
educational institution code as well as the educational institution's OID.
The first column specifies the value for the field which is explained as follows:
0
= Learning material is free for the pupil1
= Learning material is paid for the pupil
- SAML URI: one of the following (first found attribute)
- urn:mpass.id:role
- urn:educloudalliance.org:structuredRole
- SAML FriendlyName: one of the following (first found attribute)
- N/A
- ecaStructuredRole
- Type: Multi (
Array<String>
)
The roles 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 1.2.246.562.99.00000000001;00000;1A;Oppilas;1;1.2.246.562.99.00000000003;
.
Each value consists of the following fields:
- Educational provider OID (e.g.
1.2.246.562.99.00000000001
) - National educational institution code (e.g.
00000
) - Class or group information of the pupil (e.g.
1A
) - Role of the user (e.g.
Oppilas
) - Role code of the user (e.g.
1
) - Educational institution OID (e.g.
1.2.246.562.99.00000000003
) - The office / branch OID (similar format as other OIDs, can be also empty)
The OIDs for the educational provider (KOULUTUSTOIMIJA
), educational
institution (OPPILAITOS
) and office / branch (TOIMIPISTE
) can be found from:
https://virkailija.opintopolku.fi/organisaatio-service/swagger-ui/index.html
- SAML URI: urn:oid:1.3.6.1.4.1.16161.1.1.27
- SAML FriendlyName: learnerId
- Type: Single (
String
)
11-digit identifier, which may be used to identify a person while storing, managing or transferring personal data.
See:
Information about the user's home organization that is relying the information to MPASSid. This information is added by the Finnish National Agency for Education.
For instance 1.2.246.562.99.00000000001
.
MIT, see LICENSE.