omniauth-mpassid 0.5.1 → 0.6.1

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 6c9ea1c51d3ddc3c48696d8fa28047dbd410f9a59418cb7f4518c579533d36ad
-  data.tar.gz: c2dc1ef5792ac9363beb524f3e608c19364e7a711e8e2a98e4c57d2bc0919a07
+  metadata.gz: 50b9b5c7f66fc026d4c99975dacd6b4ed74fa375eeaaf9cac28b3d326bf16d3e
+  data.tar.gz: 6181a71513c88a33ebfb549a1b4f3a596e892e1e4e24fbf78f783df7313e5507
 SHA512:
-  metadata.gz: f71ab3a1cb4a99f7ad90071c21742b9203f437496f1ebb9b87a6c402e2d2751458e834f27e35ec8691518ebcd2c2a8a8f4064ff6ecc5efd9943fcb94821a81c8
-  data.tar.gz: 165be346329403c8486d526ca2bcbe6c0b9c630f78b81b325843914523f028bd62dfb28007d5b85e370e55ce12551ff3811a19fb39bde216c2e09f1f99b2505e
+  metadata.gz: 073c27bedb1e4cbb13b5f40fc5683bea48507bf348ac69e32eb585d2d127d78ddc6ea9bf1dda0945189001562967ff24382da382bd825d3357fe8653ac8d2c56
+  data.tar.gz: 5c30c4c96e99c713872f79b64ed3a3c80787d0a014902f766b47b2abc17c06975802e86b2319bed393f62211d623b65c07282cbe6b0d159065cfc14e4ecdb152

data/README.md

@@ -84,6 +84,13 @@ Devise.setup do |config|
 end
 ```
 
+## Testing
+
+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
+
 ## Identification Responses
 
 The user's data is transmitted from MPASSid in the SAML authentication
@@ -109,12 +116,11 @@ 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. The keys marked as `(undocumented)` are not described in the
-MPASSid's own documentation but are available at least in some SAML responses.
+sub-sections.
 
 See also the MPASSid data models documentation for more information:
 
-https://wiki.eduuni.fi/display/CSCMPASSID/Data+models
+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
@@ -128,15 +134,15 @@ is `nil` for both types.
 - SAML FriendlyName: givenName
 - Type: Single (`String`)
 
-The first/given name of the user.
+The given name of the user.
 
-#### `:first_names`
+#### `:first_name`
 
-- SAML URI: http://eidas.europa.eu/attributes/naturalperson/CurrentGivenName
-- SAML FriendlyName: firstName
+- SAML URI: urn:mpass.id:nickname
+- SAML FriendlyName: nickname
 - Type: Single (`String`)
 
-All the first/given names of the user.
+The first name / calling name / nickname of the user.
 
 #### `:last_name`
 
@@ -146,39 +152,45 @@ All the first/given names of the user.
 
 The last/family name of the user.
 
-#### `:municipality_code`
+#### `:provider_info`
 
-- SAML URI: urn:mpass.id:municipalityCode
-- SAML FriendlyName: municipalityCode
-- Type: Multi (`Array`)
+- SAML URI: urn:mpass.id:educationProviderInfo
+- SAML FriendlyName: mpassEducationProviderInfo
+- Type: Multi (`Array<String>`)
 
-The municipality codes of the authenticated user.
+Information about the educational provider, each value contains multiple fields
+separated with a semicolon (`;`) character.
 
-See:
+For instance `1.2.246.562.10.494695390410;Virallinen nimi`.
 
-http://tilastokeskus.fi/meta/luokitukset/kunta/001-2017/index.html
+The description of the fields:
 
-#### `:municipality_name`
+1. The educational provider's OID as specified at the link below (`KOULUTUSTOIMIJA`)
+2. The educational provider's name as specified at the link below
 
-- SAML URI: one of the following (first found attribute)
-  * urn:mpass.id:municipality
-  * urn:educloudalliance.org:municipality
-- SAML FriendlyName: one of the following (first found attribute)
-  * N/A
-  * ecaMunicipality
-- Type: Multi (`Array`)
+The OIDs and information for these OIDs can be found from:
 
-The human-readable names of the municipalities of the authenticated user.
+https://virkailija.opintopolku.fi/organisaatio-service/swagger-ui/index.html
 
-#### `:school_code`
+#### `:school_info`
 
-- SAML URI: urn:mpass.id:municipalityCode
-- SAML FriendlyName: N/A
-- Type: Multi (`Array`)
+- 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 school codes of the authenticated user.
+The values are provided in both of the following formats as separate values:
 
-See (JSON format):
+- `30076;Mansikkalan testi peruskoulu`
+- `1.2.246.562.99.00000000002;Mansikkalan testi peruskoulu`
+
+##### First format
+
+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:
 
@@ -189,37 +201,57 @@ An example for a single school code (04647), JSON format:
 
 https://virkailija.opintopolku.fi/koodisto-service/rest/codeelement/oppilaitosnumero_04647
 
-#### `:school_name`
+##### Second format
 
-- SAML URI: urn:mpass.id:school
-- SAML FriendlyName: school
-- Type: Multi (`Array`)
+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`):
 
-The human-readable names of the schools of the authenticated user.
+https://virkailija.opintopolku.fi/organisaatio-service/swagger-ui/index.html
 
-#### `:class`
+#### `:class_level`
 
-- SAML URI: one of the following (first found attribute)
-  * urn:mpass.id:class
-  * urn:educloudalliance.org:group
-- SAML FriendlyName: one of the following (first found attribute)
-  * N/A
-  * ecaGroup
-- Type: Multi (`Array`)
+- SAML URI: urn:mpass.id:classLevel
+- SAML FriendlyName: N/A
+- Type: Single (`String`)
 
-The class/group-information of the authenticated user.
+The class level information (0-10) of the authenticated user.
 
-For instance: 8A or 3B.
+For instance 8 or 3.
 
-#### `:class_level`
+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).
+
+#### `:learning_materials_charge`
 
 - SAML URI: urn:mpass.id:classLevel
 - SAML FriendlyName: N/A
-- Type: Multi (`Array`)
+- Type: Multi (`Array<String>`)
 
-The class/level-information of the authenticated user.
+Specifies for secondary level education pupils whether their learning materials
+are paid or not, each value contains multiple fields separated with a semicolon
+(`;`) character.
 
-For instance 8 or 3.
+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 pupil
+- `1` = Learning material is paid for the pupil
 
 #### `:role`
 
@@ -229,33 +261,34 @@ For instance 8 or 3.
 - SAML FriendlyName: one of the following (first found attribute)
   * N/A
   * ecaStructuredRole
-- Type: Multi (`Array`)
+- 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 Helsinki;32132;9A;Oppilas.
+For instance `1.2.246.562.99.00000000001;00000;1A;Oppilas;1;1.2.246.562.99.00000000003;`.
 
-#### `:role_name` (undocumented)
+Each value consists of the following fields:
 
-- SAML URI: urn:educloudalliance.org:role
-- SAML FriendlyName: ecaRole
-- Type: Multi (`Array`)
+1. Educational provider OID (e.g. `1.2.246.562.99.00000000001`)
+2. National educational institution code (e.g. `00000`)
+3. Class or group information of the pupil (e.g. `1A`)
+4. Role of the user (e.g. `Oppilas`)
+5. Role code of the user (e.g. `1`)
+6. Educational institution OID (e.g. `1.2.246.562.99.00000000003`)
+7. The office / branch OID (similar format as other OIDs, can be also empty)
 
-NOTE: This attribute is undocumented by MPASSid.
+The OIDs for the educational provider (`KOULUTUSTOIMIJA`), educational
+institution (`OPPILAITOS`) and office / branch (`TOIMIPISTE`) can be found from:
 
-The human readable names of the role (in Finnish).
+https://virkailija.opintopolku.fi/organisaatio-service/swagger-ui/index.html
 
-For instance Oppilas.
-
-#### `:funet_person_learner_id` (undocumented)
+#### `:learner_id`
 
 - SAML URI: urn:oid:1.3.6.1.4.1.16161.1.1.27
-- SAML FriendlyName: N/A
+- SAML FriendlyName: learnerId
 - Type: Single (`String`)
 
-NOTE: This attribute is undocumented by MPASSid.
-
 11-digit identifier, which may be used to identify a person while storing,
 managing or transferring personal data.
 
@@ -263,6 +296,14 @@ See:
 
 https://wiki.eduuni.fi/display/CSCHAKA/funetEduPersonSchema2dot2#funetEduPersonSchema2dot2-funetEduPersonLearnerId
 
+#### `:original_issuer`
+
+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`.
+
 ## License
 
 MIT, see [LICENSE](LICENSE).

data/lib/omniauth/strategies/mpassid.rb

@@ -39,44 +39,41 @@ module OmniAuth
 
       # The request attributes for MPASSid
       option :request_attributes, [
-        # 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.
-        # (single value)
-        {
-          name: 'urn:mpass.id:uid',
-          name_format: 'urn:oasis:names:tc:SAML:2.0:attrname-format:uri',
-          friendly_name: 'mpassUsername'
-        },
-        # Funet EDU person learner ID
+        # The last/family name of the user.
         # (single value)
         {
-          name: 'urn:oid:1.3.6.1.4.1.16161.1.1.27',
+          name: 'urn:oid:2.5.4.4',
           name_format: 'urn:oasis:names:tc:SAML:2.0:attrname-format:uri',
-          friendly_name: 'learnerId'
+          friendly_name: 'sn'
         },
-        # The first/given name of the user.
+        # The given name of the user.
         # (single value)
         {
           name: 'urn:oid:2.5.4.42',
           name_format: 'urn:oasis:names:tc:SAML:2.0:attrname-format:uri',
           friendly_name: 'givenName'
         },
-        # All the first/given names of the user.
+        # The first name/nickname of the user (calling name / kutsumanimi).
         # (single value)
         {
-          name: 'http://eidas.europa.eu/attributes/naturalperson/CurrentGivenName',
+          name: 'urn:mpass.id:nickname',
           name_format: 'urn:oasis:names:tc:SAML:2.0:attrname-format:uri',
-          friendly_name: 'firstName'
+          friendly_name: 'nickname'
         },
-        # The last/family name of the user.
+        # 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.
         # (single value)
         {
-          name: 'urn:oid:2.5.4.4',
+          name: 'urn:mpass.id:uid',
           name_format: 'urn:oasis:names:tc:SAML:2.0:attrname-format:uri',
-          friendly_name: 'sn'
+          friendly_name: 'mpassUsername'
         },
-        # The school code of the authenticated user. See
+        # Combination of the school code and official name of the educational
+        # institution separated with semicolon.
+        # For instance: 30076;Mansikkalan testi peruskoulu AND 1.2.246.562.99.00000000002;Mansikkalan testi peruskoulu
+        #
+        # Contains the school code of the authenticated user. See
         # https://virkailija.opintopolku.fi/koodisto-service/rest/json/oppilaitosnumero/koodi
         # (JSON format)
         # https://virkailija.opintopolku.fi/koodisto-service/rest/oppilaitosnumero/koodi
@@ -85,93 +82,77 @@ module OmniAuth
         # https://virkailija.opintopolku.fi/koodisto-service/rest/codeelement/oppilaitosnumero_04647
         # for school code 04647.
         # (multi value)
-        {
-          name: 'urn:mpass.id:schoolCode',
-          name_format: 'urn:oasis:names:tc:SAML:2.0:attrname-format:uri',
-          friendly_name: 'mpassSchoolCode'
-        },
-        # The human-readable name of the school of the authenticated user.
-        # (multi value)
-        {
-          name: 'urn:mpass.id:school',
-          name_format: 'urn:oasis:names:tc:SAML:2.0:attrname-format:uri',
-          friendly_name: 'school'
-        },
-        # Combination of the school code and official name of the educational
-        # institution separated with semicolon.
-        # For instance: 00000;Tuntematon
+        #
+        # The OIDs for educational institution (`OPPILAITOS`) can be found from:
+        # https://virkailija.opintopolku.fi/organisaatio-service/swagger-ui/index.html
         {
           name: 'urn:mpass.id:schoolInfo',
           name_format: 'urn:oasis:names:tc:SAML:2.0:attrname-format:uri',
           friendly_name: 'mpassSchoolInfo'
         },
-        # The class/group-information of the authenticated user.
-        # For instance: 8A or 3B.
-        # (multi value)
-        {
-          name: 'urn:mpass.id:class',
-          name_format: 'urn:oasis:names:tc:SAML:2.0:attrname-format:uri',
-          friendly_name: 'mpassClass'
-        },
-        {
-          name: 'urn:educloudalliance.org:group',
-          name_format: 'urn:oasis:names:tc:SAML:2.0:attrname-format:uri',
-          friendly_name: 'ecaGroup'
-        },
         # The class/level-information of the authenticated user.
         # For instance 8 or 3.
-        # (multi value)
+        # (single value)
         {
           name: 'urn:mpass.id:classLevel',
           name_format: 'urn:oasis:names:tc:SAML:2.0:attrname-format:uri',
           friendly_name: 'mpassClassLevel'
         },
-        # The role name of the user.
-        # For instance Oppilas.
+        # The learning material charge.
+        # For instance 0;00000 AND 0;1.2.246.562.99.00000000003.
         # (multi value)
         {
-          name: 'urn:educloudalliance.org:role',
+          name: 'urn:mpass.id:learningMaterialsCharge',
           name_format: 'urn:oasis:names:tc:SAML:2.0:attrname-format:uri',
-          friendly_name: 'ecaRole'
+          friendly_name: 'mpassLearningMaterialsCharge'
         },
         # The role of the user in four parts, divided with a semicolon (;)
         # character. First educational provider's organization OID, followed by
-        # school code, group and role in the group.
-        # For instance 1.2.246.562.10.12345678907;99900;7B;Oppilas.
+        # school code, group (e.g. the class), role in the group (e.g.
+        # "Oppilas"), the role code (e.g. "1"), the educational institution's
+        # OID and finally the office OID (can be undefined).
+        # For instance 1.2.246.562.99.00000000001;00000;1A;Oppilas;1;1.2.246.562.99.00000000003;
         # (multi value)
         #
-        # The educational providers' organization OIDs can be found from:
-        # https://github.com/Opetushallitus/aitu/blob/master/ttk-db/resources/db/migration/V11_2__koulutustoimijat.sql
+        # The OIDs for educational providers (`KOULUTUSTOIMIJA`), educational
+        # institutions (`OPPILAITOS`) and offices/branches (`TOIMIPISTE`) can be
+        # found from:
+        # https://virkailija.opintopolku.fi/organisaatio-service/swagger-ui/index.html
+        #
+        # The test entries are in:
+        # https://github.com/Opetushallitus/aitu/blob/master/ttk-db/resources/db/migration/V12_0__oppilaitosten_puuttuvat_koulutustoimijat.sql
         {
           name: 'urn:mpass.id:role',
           name_format: 'urn:oasis:names:tc:SAML:2.0:attrname-format:uri',
           friendly_name: 'mpassRole'
         },
-        # The educational provider's permanent organization OID.
-        # (multi value)
-        #
-        # The educational providers' organization OIDs can be found from:
-        # https://github.com/Opetushallitus/aitu/blob/master/ttk-db/resources/db/migration/V11_2__koulutustoimijat.sql
-        {
-          name: 'urn:mpass.id:educationProviderId',
-          name_format: 'urn:oasis:names:tc:SAML:2.0:attrname-format:uri',
-          friendly_name: 'mpassEducationProviderOid'
-        },
-        # The educational provider's human-readable name.
-        # (multi value)
+        # Funet EDU person learner ID
+        # (single value)
         {
-          name: 'urn:mpass.id:educationProvider',
+          name: 'urn:oid:1.3.6.1.4.1.16161.1.1.27',
           name_format: 'urn:oasis:names:tc:SAML:2.0:attrname-format:uri',
-          friendly_name: 'mpassEducationProviderName'
+          friendly_name: 'learnerId'
         },
         # Combination of the education provider's organisation-OID and official
         # name. Separated by semicolon.
         # For instance: 1.2.246.562.10.494695390410;Virallinen nimi
         # (multi value)
+        #
+        # The OIDs for educational providers (`KOULUTUSTOIMIJA`) can be found
+        # from:
+        # https://virkailija.opintopolku.fi/organisaatio-service/swagger-ui/index.html
         {
           name: 'urn:mpass.id:educationProviderInfo',
           name_format: 'urn:oasis:names:tc:SAML:2.0:attrname-format:uri',
           friendly_name: 'mpassEducationProviderInfo'
+        },
+        # The relaying organization for the information.
+        # For instance: 1.2.246.562.10.00000000000
+        # (single value)
+        {
+          name: 'urn:mpass.id:originalIssuer',
+          name_format: 'urn:oasis:names:tc:SAML:2.0:attrname-format:uri',
+          friendly_name: 'originalIssuer'
         }
       ]
 
@@ -179,31 +160,35 @@ module OmniAuth
       # https://github.com/omniauth/omniauth/wiki/Auth-Hash-Schema#schema-10-and-later
       option(
         :attribute_statements,
-        # Given name or all first names (in case given name is not found)
-        first_name: ['urn:oid:2.5.4.42', 'http://eidas.europa.eu/attributes/naturalperson/CurrentGivenName'],
-        last_name: ['urn:oid:2.5.4.4'],
-        # The education provider (e.g. municipality) of the person (literal format in Finnish)
-        location: ['urn:mpass.id:educationProvider']
+        # First name/calling name or given name (in case first name/calling name is not found)
+        first_name: ['urn:mpass.id:nickname', 'urn:oid:2.5.4.42'],
+        last_name: ['urn:oid:2.5.4.4']
       )
 
       info do
         # Generate the full name to the info hash
         first_name = find_attribute_by(
           [
-            'urn:oid:2.5.4.42',
-            'http://eidas.europa.eu/attributes/naturalperson/CurrentGivenName'
+            'urn:mpass.id:nickname',
+            'urn:oid:2.5.4.42'
           ]
         )
         last_name = find_attribute_by(['urn:oid:2.5.4.4'])
         display_name = "#{first_name} #{last_name}".strip
-        display_name = nil if display_name.length.zero?
+        display_name = nil if display_name.length.zero? # rubocop:disable Style/ZeroLengthPredicate
 
         found_attributes = [[:name, display_name]]
 
+        provider = find_attribute_by(['urn:mpass.id:educationProviderInfo'])
+        if provider
+          provider_parts = provider.split(';')
+          found_attributes << [:location, provider_parts[1]] if provider_parts[1]
+        end
+
         # Default functionality from omniauth-saml
         found_attributes += options.attribute_statements.map do |key, values|
           attribute = find_attribute_by(values)
-          [key, attribute]
+          [key.to_sym, attribute]
         end
 
         found_attributes.to_h
@@ -222,43 +207,27 @@ module OmniAuth
       option(
         :saml_attributes_map,
         given_name: ['urn:oid:2.5.4.42'],
-        first_names: ['urn:oid:2.5.4.42'],
+        first_name: ['urn:mpass.id:nickname'],
         last_name: ['urn:oid:2.5.4.4'],
-        provider_id: {
-          name: ['urn:mpass.id:educationProviderId'],
+        provider_info: {
+          name: ['urn:mpass.id:educationProviderInfo'],
           type: :multi
         },
-        provider_name: {
-          name: ['urn:mpass.id:educationProvider'],
+        school_info: {
+          name: ['urn:mpass.id:schoolInfo'],
           type: :multi
         },
-        school_code: {
-          name: ['urn:mpass.id:schoolCode'],
-          type: :multi
-        },
-        school_name: {
-          name: ['urn:mpass.id:school'],
-          type: :multi
-        },
-        class: {
-          name: ['urn:mpass.id:class', 'urn:educloudalliance.org:group'],
-          type: :multi
-        },
-        class_level: {
-          name: ['urn:mpass.id:classLevel'],
+        class_level: ['urn:mpass.id:classLevel'],
+        learning_materials_charge: {
+          name: ['urn:mpass.id:learningMaterialsCharge'],
           type: :multi
         },
         role: {
-          name: ['urn:mpass.id:role', 'urn:educloudalliance.org:structuredRole'],
-          type: :multi
-        },
-        role_name: {
-          name: ['urn:educloudalliance.org:role'],
+          name: ['urn:mpass.id:role'],
           type: :multi
         },
-        # Extra
-        # Unique learner ID
-        funet_person_learner_id: ['urn:oid:1.3.6.1.4.1.16161.1.1.27']
+        learner_id: ['urn:oid:1.3.6.1.4.1.16161.1.1.27'],
+        original_issuer: ['urn:mpass.id:originalIssuer']
       )
 
       # Defines the SAML attribute from which to determine the OmniAuth `uid`.
@@ -297,6 +266,8 @@ module OmniAuth
         authn_request = OneLogin::RubySaml::Authrequest.new
         lang = lang_for_authn_request
 
+        session['saml_redirect_url'] = request.params['redirect_url']
+
         with_settings do |settings|
           url = authn_request.create(settings, additional_params_for_authn_request)
           url += "&lang=#{CGI.escape(lang)}" unless lang.nil?

data/lib/omniauth-mpassid/version.rb

@@ -2,6 +2,6 @@
 
 module OmniAuth
   module MPASSid
-    VERSION = '0.5.1'
+    VERSION = '0.6.1'
   end
 end

metadata

@@ -1,14 +1,14 @@
 --- !ruby/object:Gem::Specification
 name: omniauth-mpassid
 version: !ruby/object:Gem::Version
-  version: 0.5.1
+  version: 0.6.1
 platform: ruby
 authors:
 - Antti Hukkanen
 autorequire: 
 bindir: bin
 cert_chain: []
-date: 2022-09-01 00:00:00.000000000 Z
+date: 2024-02-06 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: omniauth-saml
@@ -150,7 +150,7 @@ required_rubygems_version: !ruby/object:Gem::Requirement
     - !ruby/object:Gem::Version
       version: '0'
 requirements: []
-rubygems_version: 3.0.3
+rubygems_version: 3.2.33
 signing_key: 
 specification_version: 4
 summary: Provides an MPASSid strategy for OmniAuth.