internetarchive / internetarchive/openlibrary
Implement Bookshare OAuth Integration for Print Disability Qualification Flow
- Dominant language
- Python
- Stars
- 6.7k
- Forks
- 2k
- Avg merge
- 2d 19h
- Merged PRs (30d)
- 138
Description
### Feature Request
### Background
BookShare represents 15%+ of all print disability requests. They've deprecated their simple auth in favor of BookShare Oauth.
* Docs: https://apidocs.bookshare.org/auth/index.html
* Migration Guide: https://www.bookshare.org/partner-with-us/technology-developers/bookshare-api-v1-0-getting-started/api-v1-0-to-api-v2-0-migration-guide
### Policy Considerations
To prevent exploitative bookshare account sharing, it will be required that a patron's archive.org account email matches their bookshare email returned by OAuth flow.
cc: @bfalling
### Steps
- [ ] **Update the Web Component.** Create an example in isolation of extending and building the disability-eligibility-form component from offshoot which includes a button that triggers `bookshare` OAuth and fails on the callback. Latom+ @iisa can help
- [ ] **Update the Callback**. See keys at https://github.com/internetarchive/olsystem/pull/279; Update https://git.archive.org/ia/petabox/-/blob/master/www/sf/services/disability_eligibility.php and https://git.archive.org/ia/petabox/-/blob/master/www/common/DisabilityAccess.inc to work with/as the callback with OAuthClient Jim Nelson mentions. @mekarpeles, @gdamdam, and @jimbonator can help.
- [ ] **Update About Page.** Edit https://archive.org/editxml/printdisabled page description to include `disability-eligibility-form` component for `bookshare` that redirects to BookShare OAuth w/ registered callback url to disability_eligibility.php. May be tricky to test; do we create a fake archive.org item to test flow or localhost? (The oauth flow likely won’t work on localhost)
### Problem / Opportunity
Patrons with print disabilities can now qualify for special access on Open Library by selecting a qualifying program during account creation. The next step is to allow patrons who select "bookshare" as their print disability authority (PDA) to use Bookshare's OAuth flow to automatically link their accounts. This will streamline the qualification process and improve accessibility for users who rely on Bookshare.
- The original issue @internetarchive/openlibrary/issues/10457 initiated this qualification flow.
- The PR @internetarchive/openlibrary/pull/10724 implemented much of this, including the registration flow and cookie logic.
- A refactor in @internetarchive/openlibrary/pull/11052 dried up print disability checks into the account audit workflow and should be cherry-picked for a good baseline.
This feature will:
- Add Bookshare OAuth integration to the qualification flow for print disability accounts.
- Allow users to authenticate with Bookshare and automatically link their accounts via OAuth.
- Store the Bookshare OAuth secret using the key `bookshare_oauth` in olsystem.yml (see usage in core/lending.py).
- Implement business logic for Bookshare OAuth in core/auth.py.
- Add `bookshare.html` template to templates/account/ for the Bookshare qualification UI.
- Update plugins/upstream/account.py to handle GET (serve bookshare.html) and POST (process Bookshare OAuth) for the new controller.
- Consider relevant changes from @internetarchive/openlibrary/pull/11052 and update accounts/model.py where needed.
### Justification
This integration will make it easier for qualified patrons to gain access and reduce manual review steps, improving the user experience and maintaining security.
## Legacy Breakdown
This was relevant when BookShare was going to be prototyped through Open Library. Instead, use the Steps above.
### Related files
- Review @internetarchive/openlibrary/issues/10457 for background and requirements.
- Review @internetarchive/openlibrary/pull/10724 for implemented registration and qualification flow.
- Cherry-pick/refactor relevant code from @internetarchive/openlibrary/pull/11052 (account audit workflow, refactor of print disability checks).
- Add/modify files:
- openlibrary/core/auth.py (Bookshare OAuth models and logic)
- openlibrary/templates/account/bookshare.html (Bookshare qualification UI)
- openlibrary/plugins/upstream/account.py (GET/POST controller for Bookshare OAuth)
- openlibrary/accounts/model.py (as needed for user model updates)
- Use Bookshare OAuth Python code example provided for reference (see conversation above).
- Reference Bookshare API documentation: https://apidocs.bookshare.org/auth/index.html
- Use Bookshare OAuth secret from olsystem.yml (`bookshare_oauth`).
- Migration guide (if needed): https://www.bookshare.org/partner-with-us/technology-developers/bookshare-api-v1-0-getting-started/api-v1-0-to-api-v2-0-migration-guide
### Steps
* [ ] Familiarize with original issue #10457 and and PR #10724.
* [ ] Review and cherry-pick/refactor code from #11052
* [ ] Implement Bookshare OAuth logic (core/auth.py) and controller (plugins/upstream/accounts.py) for POST and GET.
* [ ] Add Bookshare qualification UI template (templates/auth/bookshare.html).
* [ ] Have staff member test end-to-end flow from registration to qualification to account linking.
Contributor guide
Research direction
Start by reviewing issue #10457, PR #10724, and PR #11052, then inspect core/auth.py, plugins/upstream/account.py, templates/account/bookshare.html, and the listed Petabox callback files. Done means the Bookshare OAuth flow links a matching account through qualification, with the web component, callback, About page, and staff end-to-end check updated as described.
Written by the indexing model from the issue text.
Assessment
- Tech stack
- python
- Domain
- authentication, backend, frontend
- Issue type
- Feature
- Difficulty
- 5/5
- Estimated time
- Over a week
- Activity status
- Stale
- Clarity
- Mostly clear
- Newbie friendliness
- 25/100