Integrating to Facebook, Google, and other social providers can be a pain. Do you want to deal with Facebook and Google tokens and their idiosyncrasies every time you build a new app? Probably not.
We at Stormpath frequently get requests to automate social login and integration for our customers so that they don’t have to build it themselves. Well, we’ve done that— Hooray! This post is about some of the design challenges and solutions we worked through while implementing this feature for our customers.
Social Login with Stormpath – Quick Description
Stormpath’s first OAuth integration makes it easy to connect to Google and Facebook in one simple API call. It’s a simple and secure way to retrieve user profiles and convert them into to Stormpath accounts so that no matter the service you’re using, you have one simple user API.
Goals and Design Challenges
My primary goal was to make this easy for developers. At the same time, it needed to be robust enough so that Stormpath could use it as the foundation to integrate with future identity providers like Twitter and GitHub.
This came with some design challenges:
How Do We Model Social Account Data in Stormpath?
We decided to let users configure external providers (like Google or Facebook) as a Stormpath Directory. In Stormpath, a Directory is a high-level ‘bucket’ of users and groups. Adding social integration at the Directory level means that all Facebook identities would exist in a Facebook directory— same for Google. This give a developer two big benefits:
You can map your Facebook or Google Directory to multiple applications in the same domain, allowing your apps to share those users without any additional code and improving your user experience.
You can define authorization policies for your social identities by assigning specific groups, roles, and permssions to them. Note— this particular feature is coming soon.
What Fields Should the Developer be Able to Update in a Social Account?
Google and Facebook do not allow you to write changes back to one of their accounts. This poses a problem. How do you add your own app-specific data to the record? As a solution, Stormpath creates a “mirror” of a social identity and allows you to add your own data to the “mirror” record via customData.
Do We Allow Password Resets?
Many applications with social integration rely solely on the external credentials hosted on the social network. This poses another problem. What if your registers with Google or Facebook but they later forget and try to log in directly with a username and password? This scenario is extremely common and often creates user confusion. They try all the passwords they remember and then eventually try a password reset, before finally contacting your help desk. At scale, this can clog your support staff.
To solve this problem, Stormpath allows you to create a new password for a social account in Stormpath. If you want, the user can specificy a password upon first registering and/or by initiating a password reset flow. Ultimately, the user can now choose how they want to log in regardless of how they registered.
How Do We Sync Data?
You can pull in profile data from social integrations and host it in Stormpath, but how do we keep the account information up-to-date without eating through a bunch of API calls? We decided to perform “on demand sync” – every time a user accesses your application with their social credentials, their Stormpath account information will be automatically updated with the information retrieved by the social provider.
How Will the Application Know the Difference Between New and Existing Social Accounts?
When retrieving an account from a social provider, you can tell whether the account is new to your application or if it already existed by checking the HTTP response status code. Stormpath will return a 201 Created status for newly obtained social accounts and a 200 OK when returning an existing/known account.
Making Google Access Tokens Painless
Getting an access token for a Google user in a web server application is not as easy as one might hope. Once the end-user has authorized your application, Google will send an “authorization code” as query parameter to the “redirect_uri” you specified in the developers console when you created your “Google project”. Finally, you’ll have to exchange the “authorization code” for an access token.
Of course, each of these calls require their own set of headers, parameters, etc. Fun times.
We wanted to reduce this burden for developers, so our Google integration conveniently automates the “exchange code” flow for you. This allows you to POST the authorization code and then receive a new (or updated) account, along with the access token, which can be used for further API calls.
Security
At Stormpath one of our main responsibilities is securing user data. When it comes to social integration, we ensure that Facebook and Google client secrets are encrypted using strong AES 256 (CBC) encryption, using secure-random Initialization Vectors. Every encryption key is tenant-specific, so you can guarantee that your encrypted secrets are only accessible by you.
Also, Facebook Login Security recommends that every server-to-server call is signed to reduce the risk of misuse of a user access token in the event it’s stolen. If your access token and you don’t require all your server calls to be signed, the thief can use your application as spam or read user’s private data.
Securing Facebook requests makes your application less vulnerable to attacks, and that’s why we recommend you to enable the Require proof on all calls setting for your Facebook application. Stormpath does this by default.
How does this work? Signing a call to Facebook just means adding the “appsecret_proof” parameter to every server request you make.
The content of the additional parameter is the hash value (SHA-256) of the user’s access with the Facebook application secret. Finally, the generated bytes are encoded using Hexadecimal characters.
How To Get Started With Stormpath Social Integration
To use Google or Facebook with Stormpath, follow these three steps:
Create a Facebook or Google Directory in Stormpath to mirror social accounts. You can do this via the Stormpath Admin Console, or our REST API using a POST like this:
Assign the created directory to your application in Stormpath.
Populate your directory with social accounts from Google or Facebook using the application’s accounts endpoint.
That is it! Your application can now access social accounts. And you didn’t have to touch any OAuth!
Future Stormpath releases will support additional social account providers. Please give us your feedback and let us know which ones we should release next!