This document describes the RERO+ authentication service based on the OAuth2 protocol. It is used to authenticate readers of the RERO+ network, for example in external services that provide resources to library users.
For information on how this protocol works, see:
Get access
- Go to https://bib.rero.ch/ and create an account (My Account > Register) with a unique, functional email address.
- Sign in
- Go to https://bib.rero.ch/account/settings/applications/ and choose New application token.
- Fill in the form and note your client_id and your client_secret.
Params
- Authorization endpoint for RERO+:
https://bib.rero.ch/oauth/authorize - Token endpoint for RERO+:
https://bib.rero.ch/oauth/token
Data is transmitted in JSON format. The authentication server is only accessible via HTTPS.
Token validity
- authorization_code: 30 seconds
- access_token: 1 hour
- refresh_token: 30 days
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, patron_types] | value delimited by a space. This provides additional information about the patron. |
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=http://your_domain/authorize&
scope=fullname+institution+expiration_date+patron_type+patron_types
Manipulate the response
The response is sent to the redirect_uri parameter specified in the base URL. If the patron approves access, a response is returned with an authorization code. This is used for the next request.
POST https://bib.rero.ch/oauth/token
{
client_id: {CLIENT_ID},
client_secret: {SECRET},
redirect_uri: 'http://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 patron_types",
"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=http://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 patron_types",
"refresh_token": "mZWszhdCb6T50l0sJYZOZQaQddrL2F"
}
If the refresh token has also expired, you must go back to Obtain an authorization code.
API call
After obtaining the token, you can make a request to the API in this form:
`https://bib.rero.ch/api/patrons/info?access_token={access_token}`
Depending on the scopes, you'll get a response like this
{
"barcode": "xxxxxxxxxxx",
"fullname": "Jean Simon",
"birthdate": "2000-01-01",
"patron_types": [
{
"patron_type": "xx-xx",
"institution": "VS"
"expiration_date": "2020-03-30T15:00:00+02:00"
},
{
"patron_type": "xx-xx",
"institution": "FR",
"expiration_date": "2017-07-16T20:00:00+02:00"
}
]
}
Test the connection
Please note that to test the OAuth connection, the library must give you a patron-account and indicate which criteria authorise the connection (institution, patron_type, expiry_date, etc.). The OAuth connection will not work with a simple user account (as created above) unless it is linked to a patron account in a library.