Shibboleth: migrate users to use EPPN

Migrating Shibboleth users

There are two big changes included by #674:

1. Now Mconf-Web uses the value of the EPPN field (abbreviation of "eduPerson-principalName") provided by the federation to identify Shibboleth users uniquely.
2. Now Shibboleth tokens have an attribute called new_account, that is set to true for all user accounts created by Shibboleth.

The migration files for these changes are:

• 20150812180000_add_new_account_to_shib_token.rb
• 20150812180001_migrate_shib_token_identifier_from_email_to_prinpal_name.rb

1. EPPN

Previously it used the user's email for the same purpose, but the EPPN is usually more guaranteed to be unique and tends to change less than the email. This change was made as part of ticket #674.

Note that even if your federation doesn't use the EPPN field, you can simply configure any other field in as if it were the EPPN, as long as it is unique in your federation.

When you update Mconf-Web to the version that uses the EPPN, one of the cases below will happen:

1. Your application is not configured to use Shibboleth: nothing will be done, you will only see a warning in the migration.
2. Your application is configured to use Shibboleth and the field shib_principal_name_field or equal to shib_email_field: this means you are either not using the EPPN or are using it but with the same value of the user's email. In this case Mconf-Web will simply set shib_principal_name_field to the same value of shib_email_field and everything should keep working fine.
3. Your application is configured to use Shibboleth and has both the fields shib_email_field and shib_principal_name_field set: the migration will attempt to search for the EPPN of the users in the database and set it as the identifier for that user in the federation (that is the attribute ShibToken.identifier). This is the case that will most likely cause issues, because not always the data needed is available in the database. If your server falls in this category and you see warning/errors, keep reading this page to find out how to solve the issues.

Case 3. Migrating the data

If the migration failed and you have correctly updated your site's configuration to use your Shibboleth server EPPN, you can migrate the users yourself using a rake task. This task also exists to migrate all your users if you ever need to change the EPPN field in your shibboleth configuration in the future.

The task can be run as shib:migrate_tokens[old_field,new_field], so to migrate from using Shib-inetOrgPerson-mail to using Shib-eduPerson-eduPersonPrincipalName you run it as:

 $ bundle exec rake shib:migrate_tokens[Shib-inetOrgPerson-mail,Shib-eduPerson-eduPersonPrincipalName]

This process should be reversible if both the fields you're using are unique in your shibboleth server so you can revert the process with:

 $ bundle exec rake shib:migrate_tokens[Shib-eduPerson-eduPersonPrincipalName,Shib-inetOrgPerson-mail]

Technically, what this task does is search for the value in ShibToken#data[new_field] and set it in the attribute ShibToken#identifier, for all tokens. Before running it, you can check your database for ShibTokens that don't have the information needed:

ShibToken.all.select{ |t| t.data["new_field"].blank? }

If you get any output in this command, it means the migration will fail for these tokens. Read below for more information.

Possible errors in the migration

Both the rails migration and this rake task print success and failure messages for each migrated user. If there are any errors you'll have to manually find out what's wrong. The most common issues are:

Shibboleth is not detect, even though it is configured

If even with a working shibboleth setup you see this message:

You don't seem to have shibboleth configured. This migration will be skipped.

Probably your Shibboleth configuration is not complete. Sign in as admin and access /site on your website. Make sure you configure the correct values for "Shibboleth: Field for email" and "Shibboleth: Field for principal name (unique ID)". After this you'll have to manually migrate your shibboleth tokens using the rake task shib:migrate_tokens described previously.

Failed to migrate token #123 'Identifier has already been taken'

The email field being used before this change in Mconf-Web was not unique and switching to the EPPN exposed some users which were duplicated, possibly because a user edited his email in the federation side. It's up to a site admin to contact the users and find out which of the two accounts is the correct one and manually delete one and keep the other.

Failed to migrate token #123

If this happens it's probably because the new EPPN field you configured for the site wasn't present on the federation when old users registered for Mconf-Web and thus we don't have it on the database. Unfortunately there's nothing that can be done on Mconf's side and you'll have to come up with a custom solution to migrate your old Shibboleth users to use the newest field.

2. new_account

This attribute is set to true for all user accounts created automatically by Shibboleth. The flag is then used internally mainly to:

• Hide the password inputs when users are editing their account, since the password in a Shibboleth account is not stored on Mconf-Web;
• Automatically update the user information (name, email, etc) with the information received by Shibboleth. This is only done when the account was created by Shibboleth. If a user associated his Shibboleth credentials with an existing account, Mconf-Web will not automatically update the user information.

When running this migration, Mconf-Web will try to detect user accounts that were created by Shibboleth and will automatically set new_account to true. The way it does it, is checking for tokens that were created less than 10 seconds after the account was created.

If this logic does not match your scenario, you can check the code in the migration, adapt it, and run in your console. If, for example, you have accounts that were initially created using Shibboleth, but later you enabled the local authentication for them (by setting a password), you will have to manually edit the shib tokens for these accounts and set new_account to false, otherwise these users will lose access to the local authentication.