api.clever package¶
Module contents¶
- api.clever.AuthenticationProvider¶
alias of
CleverAuthenticationAPI
- class api.clever.CleverAuthenticationAPI(library, integration, analytics=None)[source]¶
Bases:
OAuthAuthenticationProvider- CLEVER_API_BASE_URL = 'https://api.clever.com'¶
- CLEVER_API_VERSION = '3.0'¶
- CLEVER_API_VERSIONED_URL = 'https://api.clever.com/v3.0'¶
- CLEVER_TOKEN_URL = 'https://clever.com/oauth/tokens'¶
- DESCRIPTION = l' An authentication service for Open eBooks that uses Clever as an OAuth provider.'¶
- EXTERNAL_AUTHENTICATE_URL = 'https://clever.com/oauth/authorize?response_type=code&client_id=%(client_id)s&redirect_uri=%(oauth_callback_url)s&state=%(state)s'¶
- LIBRARY_SETTINGS = []¶
- LOGIN_BUTTON_IMAGE = 'CleverLoginButton280.png'¶
- NAME = 'Clever'¶
- SETTINGS = [{'key': 'username', 'label': l'Client ID', 'required': True}, {'key': 'password', 'label': l'Client Secret', 'required': True}, {'key': 'token_expiration_days', 'type': 'number', 'label': l'Days until OAuth token expires'}]¶
- SUPPORTED_USER_TYPES = ['student', 'teacher']¶
- TOKEN_DATA_SOURCE_NAME = 'Clever'¶
- TOKEN_TYPE = 'Clever token'¶
- URI = 'http://librarysimplified.org/terms/auth/clever'¶
- oauth_callback(_db, code)[source]¶
Verify the incoming parameters with the OAuth provider. Exchange the authorization code for an access token. Create or look up appropriate database records.
- Parameters:
code – The authorization code generated by the authorization server, as per section 4.1.2 of RFC 6749. This method will exchange the authorization code for an access token.
- Returns:
A ProblemDetail if there’s a problem. Otherwise, a 3-tuple (Credential, Patron, PatronData). The Credential contains the access token provided by the OAuth provider. The Patron object represents the authenticated Patron, and the PatronData object includes information about the patron obtained from the OAuth provider which cannot be stored in the circulation manager’s database, but which should be passed on to the client.
- remote_exchange_code_for_bearer_token(_db, code)[source]¶
Ask the OAuth provider to convert a code (passed in to the OAuth callback) into a bearer token.
We can use the bearer token to act on behalf of a specific patron. It also gives us confidence that the patron authenticated correctly with Clever.
- Returns:
A ProblemDetail if there’s a problem; otherwise, the bearer token.
- remote_patron_lookup(token)[source]¶
Use a bearer token for a patron to look up that patron’s Clever record through the Clever API.
This is the only method that has access to a patron’s personal information as provided by Clever. Here’s an inventory of the information we process and what happens to it:
The Clever ‘id’ associated with this patron is passed out of this method through the PatronData object, and persisted to two database fields: ‘patrons.external_identifier’ and ‘patrons.authorization_identifier’.
As far as we know, the Clever ID is an opaque reference which uniquely identifies a given patron but contains no personal information about them.
If the patron is a student, their grade level (“Kindergarten” through “12”) is converted into an Open eBooks patron type (“E” for “Early Grades”, “M” for “Middle Grades”, or “H” for “High School”). This is stored in the PatronData object returned from this method, and persisted to the database field ‘patrons.external_type’. If the patron is not a student, their Open eBooks patron type is set to “A” for “All Access”).
This system does not track a patron’s grade level or store it in the database. Only the coarser-grained Open eBooks patron type is tracked. This is used to show age-appropriate books to the patron.
The internal Clever ID of the patron’s school is used to make a _second_ Clever API request to get information about the school. From that, we get the school’s NCES ID, which we cross-check against data we’ve gathered separately to validate the school’s Title I status. The school ID and NCES ID are not stored in the PatronData object or persisted to the database. Any patron who ends up in the database is presumed to have passed this check.
To summarize, an opaque ID associated with the patron is persisted to the database, as is a coarse-grained indicator of the patron’s age. No other information about the patron makes it out of this method.
- Returns:
A ProblemDetail if there’s a problem. Otherwise, a PatronData with the data listed above.