Authenticated Feeds

Unless you allow anonymous access to your collection, you'll need to have some kind of software that guards access to your books, and possibly even to the OPDS feeds themselves. There are a variety of ways of doing this, but most of the time this means implementing HTTP Basic Auth and looking up credentials in some kind of data store.

Token service

The token service is only necessary in one case:

• You are a distributor who sells access to your collection to libraries.
• But you don't want the libraries downloading your books, rehosting them, and serving them to their patrons.
• Instead, you want the library patrons to come to you whenever they want to download a book.

To see the problem here, consider a specific case. I come to your site and say "I'm a patron of library X; give me this book." You've agreed to hand out copies of this book to patrons of library X, but how do you know I'm really a patron of library X? Am I supposed to show you my library card? How do you know it's legitimate?
When you set up the contract with library X, you sent out a username and password for that library to use when accessing your OPDS server. If I, the patron, had that username and password, I could access your OPDS server and download the book. But I shouldn't be given that username and password. I'm not library X, I'm just a patron of library X.
Library X shouldn't have to give out its credentials to every patron who asks. It should be able to delegate its authority to a patron for purposes of downloading a specific book from your server. This is what bearer token propagation is for, and it's covered in a separate document.

Authentication For OPDS

An Authentication For OPDS document explains what it takes for a person to actually get access to your collection. You can advertise three authentication techniques in your Authentication for OPDS document:

• Anonymous access (no authentication)
• HTTP Basic Auth (username/password)
• OAuth client credentials grant (used only by the token service below)

We also support a wrapper around OAuth's authorization code grant. For a working example, see Clever login in the Open Ebooks app. However, the situation there is so unusual that we don't want to give general advice. If you authenticate your users with an OAuth authorization code grant, contact us and we'll figure out how to work you into this strategy.
Collection metadata extensions (e.g. Library Registry) The library registry and the SimplyE mobile client also recognize a large number of extensions to Authentication For OPDS which let you specify detailed information about your collection: things like a description, the audiences and geographic locations you serve, the estimated number of titles you have in various languages, and even the color scheme to use when displaying your collection.
The automatic library registration process (not yet designed) takes your Authentication For OPDS document as its input. These extensions contain the information it needs–description, geographic locations, and so on–to put your OPDS server in the library registry and help people find it.

SAML Access

• SimplyE Client application initiates a SAML workflow using a link from the CM’s authentication document.
• The Circulation Manager redirects a patron to the IdP.
• IdP asks the patron to enter their credentials.
• IdP checks credentials and if they’re correct sends a SAML assertion to CM.
• The Circulation Manager verifies the SAML assertion, extracts a unique ID of the patron and generates a bearer token based on that patron ID.
• The Circulation Manager redirects the client application to the callback URL specified in the authentication request.
• SimplyE Client application receives the bearer token and understand that the patron has been successfully authenticated
• The patron tries to borrow a book.
• The SimplyE Client application calls the Circulation Manager's fulfill method and passes the bearer token in the HTTP Authorization header (it also passes SAML cookies to the protected URL of the content host).
• The Circulation Manager redirects the client to the provider URL using they cookies provided by the IDP.

• The content provider (SP) redirects the request to the IdP (if a patron hasn’t used this SP before) which is responsible for validating cookies which then sends a SAML assertion back to the content provider SP who then provides access to the content.

• The SimplyE Client application receives a book accessible via vendor URL.

Signed URLS

When content is locally hosted in S3 there will be no need for SAML cookies because the Circulation Manager won’t need to pass cookies from the client and  via redirects to get access to content (Circulation Manager will have direct access to the S3 buckets).  It merely needs to the client to authenticate or be authenticated.

The following is an example workflow with SAML based patron Auth:

• SimplyE Client application initiates a SAML workflow using a link from the CM’s authentication document
• The Circulation Manager redirects a patron to the IdP
• IdP asks the patron to enter their credentials
• IdP checks credentials and if they’re correct sends a SAML assertion to CM
• The Circulation Manager verifies the SAML assertion, extracts a unique ID of the patron and generates a bearer token based on this
• The Circulation Manager redirects the client application to the callback URL specified in the authentication request
• SimplyE Client application receives the bearer token and understand that the patron has been successfully authenticated
• The patron tries to borrow a book
• The SimplyE Client application calls the Circulation Manager's fulfill method and passes the bearer token in the HTTP Authorization header (it also passes SAML cookies but they’re not required in this case because of the reasons described above)
• The Circulation Manager fulfills a book link to S3 URL, then signs it using the expiration time setting set up by an administrator and redirects to it
• The SimplyE Client application receives a book accessible via a expirable pre-signed S3 URL

Anonymous access

Even if your OPDS server allows anonymous access, you can't join the SimplyE library registry without an Authentication For OPDS document. There are two reasons for this. First, you need to explicitly state that your OPDS server allows anonymous access, and the Authentication For OPDS document is the place to do that. Second, the library registry needs all that extension information–your colleciton's description, audiences and languages, and so on–and that stuff goes in the Authentication for OPDS document.
Static generation In most cases the Authentication For OPDS document can be a static document. You only need to regenerate it if something about your server's code or configuration changes.