# Login 4 of 4 supported Source: https://plasapi.com/features/patron/login/ Let patrons log in the way their library supports, sign up as new patrons, share a device and get back in when they forget their password. ## 2.2.1 Log in — Supported Let the patron identify themselves, so the client can show their loans, reservations and everything else that belongs to them. ### What you can build Login with the methods the library system offers: identifier and password or PIN, identifier alone, or single sign-on through an identity provider. The configuration tells the client which methods and identifier types to offer, so the login screen matches the library. ### Typical flow 1. With a password or PIN, the client sends the identifier and the credential to `AuthenticatePatron`. 2. Without a credential, the client sends the identifier alone to `AuthenticatePatronNoPassword`. 3. With single sign-on, the client fetches the login URL with `GetPatronAuthenticationUrl`, and the patron logs in with the identity provider. 4. The provider returns `code` and `state` to `CallbackPatron`, and the client exchanges the code with `AuthenticatePatronByCodeAndCodeVerifier`. 5. Every method responds with the patron, including the `patronId` the other patron calls use. ### What the API provides - `patron.login` in `GetConfiguration` lists the `identifierTypes`, `credentials` and `identityProviders` the provider accepts. - `patron.login.credentials` says whether the patron logs in with a `password` or a `pin`. The field in the request is called `password` either way. - `AuthenticatePatronNoPassword` is only available when `patron.login.allowWithoutCredential` is true. The specification says it should only be used when absolutely necessary. - Single sign-on uses PKCE: the client sends a `code_challenge` and a `state`, and later the matching `code_verifier`. - When the patron does not exist but can be registered, the callback carries `can_be_registered=true`, and the client continues with sign-up (2.2.3). - A failed sign-on returns `error` on the callback, for example `sso_login_cancelled` or `provider_patron_not_found`. For `sso_access_denied` and `sso_consent_denied`, the patron should be advised to contact their library. ### Calls in the API Enabled in the configuration: `GetConfiguration` Choose one path - With a password: [POST /patron/authentication](https://plasapi.com/provider/v0.6.7/patron-authentication/#AuthenticatePatron) — Authenticate patron - Without a password: [POST /patron/authentication/no-password](https://plasapi.com/provider/v0.6.7/patron-authentication/#AuthenticatePatronNoPassword) — Authenticate patron without use of a password - With single sign-on: [GET /patron/authentication/identity-provider](https://plasapi.com/provider/v0.6.7/patron-authentication/#GetPatronAuthenticationUrl) — This will fetch a SSO URL used for patron login, matching the chosen identity provider. - With single sign-on: [GET /callbacks/patron](https://plasapi.com/vendor/v0.6.7/callback/#CallbackPatron) — Callback endpoint for Patron SSO login and registration. - With single sign-on: [POST /patron/authentication/identity-provider](https://plasapi.com/provider/v0.6.7/patron-authentication/#AuthenticatePatronByCodeAndCodeVerifier) — Authenticate patron by code and code verifier from SSO login. ## 2.2.3 Sign up — Supported Let a new patron register with the library from the client. ### What you can build Patrons become borrowers without visiting the library: with an identifier, or through an identity provider. They choose where to pick up reservations and accept the library's consents as part of the sign-up. ### Typical flow 1. With an identifier, the client checks with `IsPatronRegistrationPossible` that the patron can be registered. 2. The patron chooses a pick-up location and accepts the consents. The client creates the patron with `RegisterPatronByIdentifier`. 3. With single sign-on, the patron goes through the identity provider from `GetRegisterPatronUrl`. The callback `CallbackPatron` carries `can_be_registered` and the consents to accept. 4. When `can_be_registered` is true, the client collects the pick-up location and consents and creates the patron with `RegisterPatronByCodeAndCodeVerifier`. Otherwise the provider has already created the patron, and the client logs in (2.2.1). 5. The response tells how far the registration has come in `status`. ### What the API provides - `patron.registration` in `GetConfiguration` lists the identifier types and identity providers that can be used to register. - `status` is `done`, `in_progress` or `contact_the_library`. When the status is `done`, `patronId` should be set; otherwise the patron logs in again. - `pickupLocation` is required on both registration calls. - The client must make sure the patron has accepted each consent in `consents` before the request is sent. - Consents from the callback are formatted as `type:version`, URL Base64 encoded, and all of them must be included in the registration. ### Calls in the API Enabled in the configuration: `GetConfiguration` Choose one path - With an identifier: [POST /patron/registration/possible](https://plasapi.com/provider/v0.6.7/patron-registration/#IsPatronRegistrationPossible) — This will tell if it is possible to register a new patron, using the given identifier. - With an identifier: [POST /patron/registration](https://plasapi.com/provider/v0.6.7/patron-registration/#RegisterPatronByIdentifier) — This will create a new patron, by the given identifier. - With single sign-on: [GET /patron/registration/identity-provider](https://plasapi.com/provider/v0.6.7/patron-registration/#GetRegisterPatronUrl) — This will redirect the user to the chosen identity provider, for signup. - With single sign-on: [GET /callbacks/patron](https://plasapi.com/vendor/v0.6.7/callback/#CallbackPatron) — Callback endpoint for Patron SSO login and registration. - With single sign-on: [POST /patron/registration/identity-provider](https://plasapi.com/provider/v0.6.7/patron-registration/#RegisterPatronByCodeAndCodeVerifier) — Register patron by code and code verifier from SSO registration. ## 2.2.4 Multiple users — Supported Let several patrons stay logged in on the same device and switch between them. ### What you can build Useful for a household that shares a device: each patron logs in once, and the client switches between them without logging out and in again. ### Typical flow 1. Each patron logs in separately (2.2.1). 2. The client keeps the `patronId` of each patron who is logged in on the device. 3. When the patron switches user, the client uses the chosen patron's `patronId` in the calls that follow. ### What the API provides - The specification has no separate operation for several users. Switching user happens in the client. - Removing a patron from the device happens in the client and does not change the patron's account at the library. ### Calls in the API The API supplies the data — your service performs the action - [POST /patron/authentication](https://plasapi.com/provider/v0.6.7/patron-authentication/#AuthenticatePatron) — Authenticate patron ## 2.2.5 Reset password — Supported Let a patron who has forgotten their password or PIN get a link to set a new one. ### What you can build Patrons get back into their account from the login screen, without contacting the library. ### Typical flow 1. The patron enters their identifier and the email address registered with the library. 2. The client calls `ResetPatronCredential`. 3. The provider sends a reset link to that address, and the patron sets a new credential through it. 4. The patron logs in with the new credential (2.2.1). ### What the API provides - Only offer the feature when `patron.credentials.resettable` in `GetConfiguration` lists a credential. When `credentials` is missing, offer neither reset nor change. - `credential` selects `password` or `pin`. When it is missing, the provider decides which one to reset. - The identifier follows `patron.login.identifierTypes`. `email` is required and only selects one of the patron's addresses: the link is sent only if that address is attached to the patron and verified. - A well-formed request always gets `202`, whether a link is sent or not, so the call never reveals whether a patron exists. - The link is the provider's. Its token must be single use and expire after a short period, and the request carries no URL. ### Calls in the API Enabled in the configuration: `GetConfiguration` - [POST /patron/credential/reset](https://plasapi.com/provider/v0.6.7/patron-authentication/#ResetPatronCredential) — Request that a reset link is sent to the patron.