{"id":19402820,"url":"https://github.com/cscfi/shibboleth-attrchecker","last_synced_at":"2025-07-26T11:41:10.043Z","repository":{"id":9599787,"uuid":"55046159","full_name":"CSCfi/shibboleth-attrchecker","owner":"CSCfi","description":"Shibboleth SP attribute checker template","archived":false,"fork":false,"pushed_at":"2022-06-27T08:36:12.000Z","size":12,"stargazers_count":4,"open_issues_count":1,"forks_count":4,"subscribers_count":3,"default_branch":"master","last_synced_at":"2025-01-07T12:25:49.771Z","etag":null,"topics":[],"latest_commit_sha":null,"homepage":null,"language":"HTML","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":null,"status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/CSCfi.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":null,"license":null,"code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null}},"created_at":"2016-03-30T08:30:05.000Z","updated_at":"2022-06-27T08:36:16.000Z","dependencies_parsed_at":"2022-07-21T21:18:53.018Z","dependency_job_id":null,"html_url":"https://github.com/CSCfi/shibboleth-attrchecker","commit_stats":null,"previous_names":[],"tags_count":0,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/CSCfi%2Fshibboleth-attrchecker","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/CSCfi%2Fshibboleth-attrchecker/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/CSCfi%2Fshibboleth-attrchecker/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/CSCfi%2Fshibboleth-attrchecker/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/CSCfi","download_url":"https://codeload.github.com/CSCfi/shibboleth-attrchecker/tar.gz/refs/heads/master","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":240577853,"owners_count":19823529,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2022-07-04T15:15:14.044Z","host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":[],"created_at":"2024-11-10T11:25:57.183Z","updated_at":"2025-02-25T00:24:20.132Z","avatar_url":"https://github.com/CSCfi.png","language":"HTML","funding_links":[],"categories":[],"sub_categories":[],"readme":"## Shibboleth SP attribute checker\n\nThe list of attributes released by an IdP varies heavily and occasionally required attributes needed by an SP are not released by the user's IdP. This leads to failed logins and the error page doesn't give clear information of the failure reason (eg. what attributes are missing). You can always check the attributes on an application level. The approach described here is done on the Shibboleth SP level (requires Shibboleth 2.5+) and does not require changes to the application using the attibutes.\n\nShibboleth SP provides a hook for performing attribute checks for required attributes and a attribute extractor for fetching IdP metadata attributes where the login was performed.\n\n### Attribute Checker Handler\n\nThe AttributeChecker validates the user session against attributes specified as a required. If requirements are fulfilled, the login completes otherwise an error page is displayed instead. Note that the required attributes have to be \"hard coded\" here and kept in sync with the required attributes expressed in the Metadata.\n\n#### Configuration\n\nAdd a sessionHook for attribute checker: sessionHook=\"/Shibboleth.sso/AttrChecker\" to ApplicationDefaults. Also add the metadataAttributePrefix=\"Meta-\" (This will be explained later).\n\n''In context: /etc/shibboleth/shibboleth2.xml -\u003e ApplicationDefault element''\n\n```\n\u003cApplicationDefaults entityID=\"https://\u003cHOST\u003e/shibboleth\"\n  REMOTE_USER=\"eppn persistent-id targeted-id\"\n  signing=\"front\" encryption=\"false\"\n  sessionHook=\"/Shibboleth.sso/AttrChecker\"\n  metadataAttributePrefix=\"Meta-\" \u003e\n```\n\nAdd the attribute checker handler with the list of required attributes to Sessions (in the example below: eppn, displayName).\n\n''/etc/shibboleth/shibboleth2.xml -\u003e Sessions element''\n\n```\n\u003cHandler type=\"AttributeChecker\" Location=\"/AttrChecker\" template=\"attrChecker.html\" attributes=\"eppn displayName\" flushSession=\"true\"/\u003e\n```\n\nIf you want to describe more complex scenarios with required attributes, operators such as \"AND\" and \"OR\" are available.\n\n```\n\u003cHandler type=\"AttributeChecker\" Location=\"/AttrChecker\" template=\"attrChecker.html\" flushSession=\"true\"\u003e\n \u003cOR\u003e\n   \u003cRule require=\"displayName\"/\u003e\n   \u003cAND\u003e\n     \u003cRule require=\"givenName\"/\u003e\n     \u003cRule require=\"surname\"/\u003e\n   \u003c/AND\u003e\n \u003c/OR\u003e\n\u003c/Handler\u003e\n```\n\nNow we have an session hook for the attribute checker to check specified attributes before a user login is completed. For customization of the error page (attrChecker.html) we want to enable the \"Attribute Extractor\" with the type \"metadata\" to be able to fetch IdP attributes from the metadata feed. The Attribute we need is the email address of the IdP support contact. We already added metadataAttributePrefix to the ApplicationDefaults element.\n\nAdd the AttributeExtractor element of the type metadata next to the already existing type XML: (\u003cAttributeExtractor type=\"XML\" validate=\"true\" path=\"attribute-map.xml\"/\u003e)\n\n''/etc/shibboleth/shibboleth2.xml -\u003e ApplicationDefault element''\n\n```\n\u003c!-- Extracts support information for IdP from its metadata. --\u003e\n\u003cAttributeExtractor type=\"Metadata\" errorURL=\"errorURL\" DisplayName=\"displayName\"\n                    InformationURL=\"informationURL\" PrivacyStatementURL=\"privacyStatementURL\"\n                    OrganizationURL=\"organizationURL\"\u003e\n  \u003cContactPerson id=\"Support-Contact\"  contactType=\"support\" formatter=\"$EmailAddress\" /\u003e\n  \u003cLogo id=\"Small-Logo\" height=\"16\" width=\"16\" formatter=\"$_string\"/\u003e\n\u003c/AttributeExtractor\u003e\n```\n\nWhen you modify shibboleth2.xml you can test validity of the configuration file with command \"shibd -t\". If configuration file is still valid XML you can now restart your shibboleth with \"sudo service shibd restart\". Shibboleth should anyways reload configuration file if it detects any change on it.\n\n#### Logging\n\nShibboleth SP doesn't track nor log failed logins due to missing attributes. The Shibboleth SP web server can be used for \"pixel tracking\". This means that you load an image (eg: containing only one transparent pixel) from the web server  from where you can monitor logs and observe access for you image. In the url of your image you can also insert details you want to see, eg: Authentication source (IdP) and missing attributes.\n\nReplace the image with your existing one from the following code or comment it out if you dont need it. Example below loads track.png from document root and adds variables like \"idp\" containing the entityID of the authentication source and \"miss\" denoting missing attributes.\n\n''Pixel tracking''\n\n```\n\u003cimg title=\"track\" src=\"/track.png?idp=\u003cshibmlp entityID/\u003e\u0026miss=\u003cshibmlpifnot displayName\u003e-displayName\u003c/shibmlpifnot\u003e\u003cshibmlpifnot givenName\u003e-givenName\u003c/shibmlpifnot\u003e\u003cshibmlpifnot cn\u003e-cn\u003c/shibmlpifnot\u003e\u003cshibmlpifnot sn\u003e-sn\u003c/shibmlpifnot\u003e\u003cshibmlpifnot eduPersonPrinpalName\u003e-eduPersonPrinpalName\u003c/shibmlpifnot\u003e\u003cshibmlpifnot schacHomeOrganization\u003e-schacHomeOrganization\u003c/shibmlpifnot\u003e\u003cshibmlpifnot schacHomeOrganizationType\u003e-schacHomeOrganizationType\u003c/shibmlpifnot\u003e\" alt=\"\" width=\"1\" height=\"1\" /\u003e\n```\n\n#### Template customization\n\nThe attrChecker.html is located in the \"/etc/shibboleth\" directory. If you don't want to edit it by yourself, you can use the ready made template. The template has links to external components such as jquery and bootstrap. They are fetched on the fly from third party sources. Basically there are three locations needing modifications:\n\n* The pixel tracking link after the comment \"PixelTracking\". The Image tag and all required attributes after the variable must be configured here. After \"miss=\" define all required attributes you updated in shibboleth2.xml using shibboleth tagging. Eg `\u003cshibmlpifnot $attribute\u003e-$attribute\u003c/shibmlpifnot\u003e` (this echoes $attribute if it's not received by shibboleth). This example uses \"-\" as a delimiter.\n\n* The table showing missing attributes between the tags \"TableStart\" and \"TableEnd\". You have to insert again all the same attributes as above.\n\n'' Define row for each required attribute (eg: displayName below) ''\n\n```\n\u003ctr \u003cshibmlpifnot displayName\u003e class='warning text-danger'\u003c/shibmlpifnot\u003e\u003e\n  \u003ctd\u003edisplayName\u003c/td\u003e\n  \u003ctd\u003e\u003cshibmlp displayName /\u003e\u003c/td\u003e\n\u003c/tr\u003e\n```\n\n* The email template between the tags `\u003ctextarea\u003e` and `\u003c/textarea\u003e`. After \"The attributes that were not released to the service are:\". Again define all required attributes using shibboleth tagging like in section 1 ( eg: `\u003cshibmlpifnot $attribute\u003e * $attribute\u003c/shibmlpifnot\u003e`). Note that for SP identifier target URL is used instead of entityID. There arent yet any tag for SP entityID so you can replace this target URL manually.\n\nYou can also update attrChecker.html with a Perl-script (attrChecker.pl). The script extracts the required attributes from the Attribute Checker handler element in shibboleth2.xml and modifies attrChecker.html accordingly (Note that script doesnt work with complex scenarios using AND and OR operators, it uses only \"attributes\" attribute from the handler). If you customize attrChecker.html and execute the Perl-script, make a backup of attrChecker.html before executing attrChecker.pl. If the script doesn't find the tags it needs for replacing content, it might break the template. The script updates the PixelTracking link by replacing shibboleth tags between miss= and following \", attribute table rows between \"TableStart\" and \"TableEnd\" and after line \"The attributes that were not released to the service are:\" until the next empty line.\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fcscfi%2Fshibboleth-attrchecker","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fcscfi%2Fshibboleth-attrchecker","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fcscfi%2Fshibboleth-attrchecker/lists"}