Tech Blog

Leveraging Social Login with Alma

As a part of efforts to support additional methods of authentication, staff users can now log into Alma using social networks such as Google and Facebook. And patrons will be able to login to Primo using social authentication as well, including the option for self registration if enabled by the institution. More information about how to configure social authentication in Alma is available in the online help and the Developer Network documentation, including details about how to set up your application in the social network and how to allow users to attach their Alma account with a social network account.

Third party applications can also leverage social login via Alma, which means that you can add social login to your library portal, digital deposit tool, or discovery solution. Performing social login via Alma also allows for a single sign on experience for users when interacting with services provided by Alma, such as the fulfillment services mash-up.

The basic flow for integrating social login via Alma into your application is as follows:

  • Link to the Alma social login page, which lists the configured social networks
  • User selects their social network, authenticates if required, and authorizes Alma (or your library) to have access to their basic profile information (if it’s the first time logging in)
  • Alma validates the user authorization code received by the social network
  • Alma redirects the user’s browser to a specified back URL along with a JSON Web Token (JWT) which includes details about the user
  • The application creates a session for the authenticated user the user is logged in

This flow is represented in the diagram below:

Link to Alma

The link to Alma from your application https://YOUR_ALMA_URL/view/socialLogin and should include the following parameter:

Parameter NameDescription
institutionCodeYour institution code in Alma
backUrlThe URL to which Alma should redirect after authentication

Parsing the JWT

After authenticating with the social network, Alma will redirect to the specified back URL with a ‘jwt’ parameter on the querystring. JWTs are made up of three parts- a header with the signing algorithm, a payload with data, and a signature. Alma uses a signature with a SHA 256 hash algorithm (HS256). The key used to hash the token is specified in User Configuration — Other Settings — jwt_signature_secret.

In addition to the standard JWT fields, the payload sent by Alma includes the following:

  • id: user primary identifier
  • name: user’s display name
  • email: user’s primary email address
  • provider: social network provider used to authenticate (i.e. GOOGLE or FACEBOOK)

There are libraries in many languages that can be used to parse the token and verify the signature. A comprehensive list is available on the JWT homepage. Here’s an example in Ruby:

decoded_token = 
   JWT.decode params[:jwt], 
   { :algorithm => 'HS256' }

user_name = token["name"]
session[:user_id] = token["id"]

Single Sign On with the Mash-Up

Now that we have created a session locally, we can participate in a single sign on session with Alma. On the link to the fulfillment services page, we include the following two parameters:
  • oauth=true

With these parameters, Alma will validate the user session with the social network provider and the user will be automatically logged in.


Social authentication in Alma provides users with a convenient way to log in and reduces the number of passwords they need to remember. Using the methodology explained here, you can easily add this functionality to your own application and enjoy single sign on with Alma.

Leave a Reply