4.3: Sign in from other sites using OAuth

The best way to convert guests into members is to make the onboarding process as simple as possible.

Over the years, we've added special log in methods for Facebook, Google, LinkedIn and Microsoft. We've carefully hand coded these integrations to allow guests to sign up with just a few clicks using services they're already a member of.

These services used to use proprietary methods to link with other websites, but a new standard has emerged.

OAuth
You may not know it, but you're probably familiar with OAuth already. If you have enabled the ability for users of your community to sign in with their Facebook, Twitter, Google, LinkedIn or Microsoft account, you may have noticed that the process for setting up each of these is quite similar. This is because they all use the OAuth protocol.

In Invision Community 4.3, we are introducing several exciting new features:

• In addition to all of the existing social networks above, which retain their "easy setup" status, we have also added Wordpress. Users on your community can now sign in with any Wordpress site you control (you will need to install a Wordpress plugin to enable OAuth capabilities).
• As well as those "easy setup" options, we have also added the ability for you to allow users on your site to sign in with any OAuth 2.0 based provider. This means, for example, if your community is based in a location where other social networks are popular, if they use OAuth, you can set those up too. While the setup is a little bit more complicated, this doesn't require any custom programming - you'll just need to find out a few more pieces of information from the provider (an example is provided below).
• Invision Community itself can now also serve as an OAuth 2.0 server so you can set up other sites to be able to facilitate logins using credentials from your community. This works in conjunction with our REST API, allowing you to make API calls as an authenticated member, which will return just the information that user has access to.
• With the ability for Invision Community to serve as both an OAuth server and client, this now provides standard integration for multiple Invision Communities together, which will now replace the old IPS Connect feature.
• We have also taken this opportunity to make a few other minor tweaks to login, registration and account management features, especially for communities which rely heavily on non-standard login methods (more details below).

Setting Up a Custom OAuth Provider

For this example, I'm going to use vk.com, which is a popular social network in Europe. While Invision Community doesn't provide this as one of the "easy setup" options, it is based on OAuth 2.0 so we can use the new functionality in Invision Community 4.3 to set it up.

In older versions, the list of login handlers in the AdminCP had all of the providers listed with enable/disable toggles - because now you can add as many custom handlers as you like in 4.3, it's now a list where you can add/delete options:

When clicking the "Create New" button, you'll see all of the different handlers Invision Community supports. Since vk.com isn't in the list, but is still OAuth 2.0-based, I'll choose the "Other OAuth 2.0" option:

You'll now need to use the documentation provided by the site you want to integrate with to fill out this form. While no custom programming is required, the documentation is usually quite technical in nature - but you only need a few key pieces of information. We anticipate that for some of the more popular options, guides will be provided to help you find the information you need.

I have created an application in vk.com's developer center and so I will copy and paste my credentials into the form:

I then need to find the endpoints from vk.com's documentation and input those too.

Next I need to find the endpoint where I can access the user's information within their API and the parameters they are returned by. The only required piece of information is an ID, but you can also provide the parameters for accessing the display name, email address and profile photo. If display name/email address isn't available/provided, the user will be asked for this the first time they sign in. vk.com's API doesn't provide access to the email, but I can use the screen name as the display name, and they do provide access to the photo:

Finally, provide a logo and a color for the sign in button and some final settings:

And now vk.com login is set up. A button will now show up on the front end which I can use to sign in. I didn't provide a way to access the email address, so on the first sign in, the user will be prompted to provide that, but the screen name and profile photo from vk.com will be used:

Using Invision Community as an OAuth Server

You can also set up Invision Community itself to be an OAuth Server. This may be useful for two main reasons:

• If you want to integrate two communities together, or integrate with something else which supports adding custom OAuth clients.
• If you are a developer and want to use the REST API using OAuth for authentication rather than an API Key. You can either make requests as an authenticated user (by obtaining an access token) or using Client Credentials.

The screenshots below show the full capabilities which are quite technical and mostly aimed at developers. If you will just use this feature to link two communities, don't be concerned if it looks too complicated, an easy-to-follow guide will be available to achieve that.

You will set up the clients from the AdminCP:

When creating the OAuth Client, you can control which scopes are available, and which endpoints of the REST API they provide access to:

The login process is then the standard OAuth flow, and users have the ability to view authorisations in the account settings:

The REST API has new and updated endpoints to be aware of the authenticated user:

Other Login System Tweaks

• Users can now choose if they want to change their local display name or email address if it is changed by an external login method (or the administrator can choose this behaviour). If there is an issue with this (for example, it wants to change the email to one that is already taken), or profile photo syncing, this is now better communicated to the user.
• You can now control per-login-handler if new registrations are allowed using it. This addresses some confusion from previous versions as to if the "Allow New Registrations" setting applies to accounts being created by social network logins.
• The Standard login handler can be disabled if you rely totally on an alternate login method. To allow this to happen:
  •  All areas where a user is prompted to re-enter their password (some areas of the account settings) now allow reauthentication using any login handler.
  • You can disable local registration but still allow accounts to be created by other login handlers, or redirect users to an external URL to register an account.
  • You can also disable or redirect to an external URL for changing email address / password or the Forgot Password tool.
• You can now create multiple instances of the external MySQL database and LDAP login methods which have also had some other minor tweaks:
  • The external MySQL database handler now has PHP's password_hash() function as an available option for password encryption type, and defining a custom encryption method is now much easier, done entirely in the AdminCP without needing to modify PHP files.
  • You can now choose if changes to the local display name / email address / password is synced back to the external database / LDAP database.
  • You can optionally show these handlers in the Account Settings pages like other login handlers to allow users with an existing account to link their accounts.
  • You can define a Forgot Password URL for the external database which the user will be redirected to if they try to use the Forgot Password tool and that is how their account is authenticated.