Register a new EZProxy/OverDrive customer in our SSO system
Disclaimer and intended audience
This section describes the internal process for registering a new EZProxy/OverDrive customer in our SSO stack. It is not customer-facing material and should only be used by Statista staff involved in maintaining or extending this integration.
The intended audience is:
- Developers working on the
platform-sso-servicesproject. - Maintainers responsible for our Auth0 and EZProxy/OverDrive integration.
- Customer Success Managers coordinating onboarding for eligible existing customers.
To follow this process, you must:
- Have access to our GitHub organization and the
platform-sso-servicesrepository (read and write). - Have permissions to run GitHub Actions workflows.
- Have permissions to create branches, push changes, and merge pull requests in
platform-sso-services.
Overview
This section explains how to register a new EZProxy/OverDrive customer in our internal SSO setup so that their EZProxy instance can authenticate users to Statista via the OverDrive-style flow.
At a high level, you will add a new customer entry to our platform-sso-services configuration, commit the changes to
GitHub, and deploy so that ezproxy-auth-service can validate hashes and map EZProxy tokens to the correct Statista
group account.
All changes for live customers must be added to the platform-sso-services/data/prod_ezproxy-domains.json file.
Note: This file is only intended for production configuration. For testing and development, there are already test accounts registered; do not add demo or staging entries to
prod_ezproxy-domains.json.
What you need for this case
Before starting, make sure you have the following customer details:
- EZProxy customer domain (used for mapping, for example:
statista.com). - EZProxy customer groupAccountId (the internal group account ID holding the Statista license, for example:
1050918). - EZProxy customer name (human-readable label, for example:
Statista University). - Additional domains (comma-separated list used for grouping or alternative hostnames, for example:
lib.example.edu,proxy.example.edu).
Steps
1. Runt the GitHub Action to add the new customer
Head on to the Add EZProxy Customer github action section on github. This action has a trigger dispatch button to run the workflow manually. Click on it and fill in the required parameters:
This will initiate the workflow which will create a new branch, add the new customer to the prod_ezproxy-domains.json
file, commit the changes, and open a pull request for review.
2. Review and merge the pull request
Wait for all check to be completed and review the changes. If everything looks good, merge the pull request to the
main branch.
3. Provide the customer details to the CSM
After merging, provide the customer details from the PR description including the 'Secure Download Link' to complete the registration, important the link expires after 7 days, so make sure to share it with the CSM as soon as possible.
Troubleshooting
In case of any issues during the process, check the following:
- Verify that the GitHub Action ran successfully and that the pull request was created without errors.
- Check the pull request for any merge conflicts or issues that may have prevented it from being merged.
- Ensure that the customer details were correctly added to the
prod_ezproxy-domains.jsonfile and that the PR was merged into themainbranch. - If the 'Secure Download Link' was not generated or shared, check the GitHub Action logs for any errors related to the link generation step.
We order the entries alphabetically, which lowers the risk of creating merge conflicts when multiple customers are added around the same time. If you encounter a merge conflict, resolve it by ensuring the new entry is correctly placed in alphabetical order and that no existing entries are modified.
In case the customer failed to retrieve the file via the 'Secure Download Link' and the link has expired, we are working to provide a separate GH action to recreate the 'Secure Download Link'.