This document describes the RERO+ authentication service based on the OAuth2 protocol. It is used to authenticate RERO ILS users, for example in external services that provide resources to library users.
For general information on how this protocol works, see:
Parameters
- RERO+ Authorization endpoint:
https://bib.rero.ch/oauth/authorize - RERO+ Token endpoint:
https://bib.rero.ch/oauth/token
Data is transmitted in JSON format. The authentication server is only accessible via HTTPS.
Token validity (tokens)
- authorization_code: 30 seconds
- access_token: 1 hour
- refresh_token: 30 days
Register an application access
- Go to https://bib.rero.ch/ or https://bib.test.rero.ch/ (test environment) and create an account (My account > Sign up) with a functional and unique email address (this email address will be displayed to users who use your service).
- Sign in
- Go to https://bib.rero.ch/account/settings/applications/ and choose New application token.
- Fill in the form and take note of your client_id and client_secret.
Test the connection
Please note that if you have been commissioned by a library, to test your OAuth 2 implementation the library must give you a test patron account and indicate which criteria authorise the connection or not (generally: institution, expiration_date). A user account (as created above) will not return all the data unless it is linked to a patron account registered with a library and will therefore not allow authentication criteria to be tested.
Obtain an authorization code
The URL used to authenticate the patron is https://<instance>/oauth/authorize.
| param | value | description |
|---|---|---|
| client_id | identifier | customer identification code |
| response_type | code | token return parameter (fixed value) |
| redirect_uri | url | URL of your authentication service |
| scope | [fullname, birthdate, institution, expiration_date, patron_type] | Delimited by +. This allows you to obtain additional data according to your needs. |
Example of an authentication URL (for readability, line breaks have been added):
GET https://bib.rero.ch/oauth/authorize?
client_id={CLIENT_ID}&
response_type=code&
redirect_uri=https://your_domain/authorize&
scope=fullname+institution+expiration_date+patron_type
Scopes
The API always returns the following information:
patron_info.{institution}.patron_pid: user identifiers within each institution/library in which they are enrolledbarcode: deprecated, do not use.user_id: unique identifier for the user (to be used only if you need to identify users who are NOT registered in a library).
Depending on the information your implementation needs, choose one or more of the following scopes (at least one scope is required):
fullname: First and last name of the userbirthdate: User's date of birth (format YYYY-MM-DD)institution: Institutions in which the user is registered.expiration_date: User's expiry date in each of their institutions/libraries.patron_type: User's category in each of their institutions/libraries.
Manipulate the response
The response is sent to the redirect_uri parameter specified in the base URL. If the reader approves access, a response is returned with an authorisation code. This is valid for 30 seconds and is used for the next request:
POST https://bib.rero.ch/oauth/token
{
client_id: {CLIENT_ID},
client_secret: {SECRET},
redirect_uri: 'https://your_domain/authorize',
grant_type: 'authorization_code',
code: {CODE}
}
It is necessary to send the data with a POST request, as the information contained in this request is sensitive.
A valid response returns a JSON array:
{
"access_token": "4NPtBhoiBmML6k7cDe9RdcrXrHl7XR",
"expires_in": 3600,
"token_type": "Bearer",
"scope": "fullname birthdate institution expiration_date patron_type",
"refresh_token": "iic37JVAq71uLDu3jzHWdT958qh01D"
}
| param | description |
|---|---|
| access_token | the token sent by the server |
| expires_in | token validity period |
| token_type | token type (Bearer is the only value used) |
| scope | list of scopes sent by the request |
| refresh_token | refresh token |
The access token can be used throughout its lifetime (1 hour). Once it has expired, you must use the refresh token to obtain a new one.
Renew the access token
The refresh token is used to renew an expired access token.
https://bib.rero.ch/oauth/token?
client_id={CLIENT_ID}&
client_secret={SECRET}&
redirect_uri=https://your_domain/authorize&
grant_type=refresh_token&
refresh_token={REFRESH_TOKEN}
The response is:
{
"access_token": "2ZERNCx1x4gGcvoh51z2YTFxFPFCfY",
"expires_in": 3600,
"token_type": "Bearer",
"scope": "fullname birthdate institution expiration_date patron_type",
"refresh_token": "mZWszhdCb6T50l0sJYZOZQaQddrL2F"
}
If the refresh token has also expired, you must go back to Obtain an authorization code.
API call
Once the token has been obtained, a request can be made to the API in this form: https://bib.rero.ch/api/patrons/info?access_token={access_token}, which will return the data for the user.
Example of a response for a user registered at two institutions (‘vs’ and ‘rbnj’) and for whom all scopes have been requested. If you have a client library, it must tell you which criteria authorise the connection or not.
{
"barcode": "xxxxxxxxxxx",
"user_id": 7653,
"fullname": "Jean Simon",
"birthdate": "2000-01-01",
"patron_info": {
"vs": {
"expiration_date": "2027-03-30T00:00:00",
"institution": "vs",
"patron_pid": "316784",
"patron_type": "vs-pm"
},
"rbnj": {
"expiration_date": "2029-08-24T00:00:00",
"institution": "rbnj",
"patron_pid": "876"
}
}
}