When changing from one authentication provider to another, existing users either need to be switched over to match users in the new provider or deleted.
- DELETE: If admins choose to delete users, all users will be removed permanently from the platform and their local content will be soft deleted. When users are deleted by this process, all their private data (the discoveries, publications, and so on that are stored in their My Content Folder) is "soft deleted." Soft deleted files are moved into the Deleted users content folder and can be restored by an admin if needed.
- CONVERT: If admins choose to convert users, admins need to map existing users to users in the new Authentication Provider. This process is iterative, offering admins an opportunity to preview the mapping process and make adjustments before committing the changes. Users that are successfully mapped will seamlessly transition with their content. Users that are not matched are disabled and their content is not deleted.
Mapping Pyramid Users
Once you have launched the change provider process, with a new initial user, you will be prompted to go through the user conversion process.
For the conversion process, you will need to prepare an upload-able CSV file with the user mapping from the old to new.
Creating your Upload File
The CSV file that you use to map your users has different columns depending on your target Authentication Provider and whether you have supplied User Provisioning Settings to allow Pyramid to search for user details held by your Authentication Provider. You can download blank template CSV files below:
See below for details of the fields that you need to complete for each of these file types.
Important: The first row in the CSV file is always treated as a header row. Your spreadsheet must include all the columns described below. Where a column is described as "optional," the column may be left empty but still needs to be present in the spreadsheet.
Uploading your file
This process begins at the end of the Change Provider process. Once you click Apply to change your provider, you will be prompted either to DELETE or CONVERT existing users:
- If you are happy to delete your current Pyramid users and their content, select that option in the dialog and then click DELETE USERs to continue.
- If you want to migrate your existing users, select that option in the dialog. Next browse to and select your CSV mapping file. Then click the CONVERT USERs to continue.
- If you are unsure, click Cancel to stop the provider change-over process.
Conversion
If you chose CONVERT, the conversion process begins with an evaluation of the mapping for each user supplied. Once it is complete, the user mapping dialog will open and report results.
Mapped Users
The Convert Users dialog lists each user in the CSV mapping and indicates:
- Status: The status field indicates whether the user has been converted (green) or not (red). The user may not be converted because:
- The Search Value and Target User Name do not match.
- There is no user that matches the Search Value.
- There are mandatory details that are not supplied for the user.
- Error: Where the status is red, an error is displayed indicating the cause of the failure.
It is important to note that users that are not converted will be disabled in Pyramid.
Exporting the status list
Click Export to download the list of users and their status (mapped successfully or failed). This file has the same structure as your import file but with an additional Error Messages column. . This may help you resolve any mapping problems.
Canceling the Mapping
If you choose to cancel the mapping exercise, the entire Change Provider process is canceled without committing ANY changes. This means, if you want to proceed, you must start from the beginning of the Change Provider process again.
Mapping File Structures
SAML and OpenID Users
Without Search
Where the Authentication Provider is SAML or OpenID and Pyramid is not set up to search for user details on that Authentication Provider, the import file needs to include the following columns:
- Source user name
- Password
- External ID - The Mandatory External ID for the user in Pyramid. You need to supply this value where search is not being used.
With Search
Where the Authentication Provider is SAML or OpenID and Pyramid is set up to search for user details on that Authentication Provider (Provider Provisioning Settings are set up), the import file needs to include the following columns:
- Source user name
- Search value - The value used to search for the user on the Authorization Provider. This is typically the Principal Name or User Name, although it can be Display Name where the Vendor is Azure and will always be Email where the Vendor is Google.
- Password
Active Directory Users
Where the Authentication Provider is Active Directory, the import file needs to be in comma delimited format (CSV) where each row represents a user in the Active Directory that you want to map to a user in Pyramid. The following columns are required:
- Source user name
- Search value - The value used to search for the user on the Authorization Provider. This is typically the Principal Name or User Name, although it can be Display Name where the Vendor is Azure and will always be Email where the Vendor is Google.
Internal Database Users
Where the Authentication Provider is Database (internal), the import file needs to include the following columns:
- Source user name
- Password