Log into external services with RERO ILS (OAuth)

  • api
Last updated: 20-08-2024

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

  1. Go to https://bib.rero.ch/ and create an account (My Account > Register) with a unique, functional email address.
  2. Sign in
  3. Go to https://bib.rero.ch/account/settings/applications/ and choose New application token.
  4. 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.


Interoperability applications | Access MARC data (SRU)