The most popular address book sources use an authorization framework called OAuth to enable applications to request access to users’ data. Users are shown information about the application and the access being requested and given the opportunity to approve or reject the request.
The request for access is handled by the address book source (Google, Yahoo or Microsoft), so they need to know a bit about your application in order to display it in the request. You tell them about your application by registering a free developer account and giving them some information, such as your product’s name and website. They give you a set of OAuth credentials that you will configure in your CloudSponge account so we can use their API on your behalf.
The Valet Key
OAuth has been likened to a valet key for a person’s data. The person can choose to temporarily allow an application to have specific access to their data without giving up their entire account. If the user grants consent, then the page is redirected to your website to hand off the “valet key” to your application.
When you use CloudSponge to integrate with the address book sources, you need a special page to forward this “valet key” to our application so our app can do to heavy lifting for you. We’ve already created a static HTML file for you to host on your site that implements this valet key forwarding; we call it the Proxy URL. It is critical to your integration and it can be a sticky point for completing a successful integration.
Putting It All Together
There are 3 main steps to white-labelling imports for Google, Yahoo and Microsoft (Outlook.com and Office 365).
- Set up a Proxy URL on your domain
- Create developer accounts with Google, Yahoo! and Microsoft
- Configure CloudSponge to use your OAuth credentials
Because each source has a slightly different process for setting up your OAuth credentials, we have created detailed steps for each under the OAuth Credentials section.
Watch Your Language!
We try to be consistent with our language because we know that it’s important when communicating about an unfamiliar topic. Sometimes we slip up when providing support over Slack or email. If we use any of the following phases, we mean the same thing which is this thing that we’re talking about:
- OAuth credentials
- OAuth client id
- OAuth consumer credentials
- Consumer credentials
- Developer credentials
Please forgive any slip-ups. The concept behind OAuth has been around for a decade or more. Over that time it has become more standardized. (We celebrated hard when Microsoft made the switch from their proprietary “DelAuth” implementation to OAuth 2.0.) And even with that standardization today, each address book source has its own implementation with slight variations in names and conventions.
You Are Not Alone
It can be intimidating to get into this unfamiliar process, so do reach out if you need our support. We’ve been doing it for ages and have helped to guide a lot of folks to get it working properly. We offer a Setup Concierge Service for a one-time fee. Please reach out to discuss further.