This addon integrates Hybridauth, providing a number of features:

1. Adds many social network (etc) login options to your site (Facebook, Google, Apple, etc)
2. Allows pulling in content from some services, with included support for Atom feed generation and content display using a block
3. Allows syndicating (pushing) content to some services
4. Allows syndicating (pushing) activities to some services (see the activity_feed addon)
5. Allows using YouTube as a video host (effectively, a transcoder)
6. Works as a media renderer (oEmbed-like)

Hybridauth essentially implements the OAuth1, OAuth2, OpenID Connect, and OpenID standards, and proprietary APIs, necessary to unify all the different login integrations of different services.

Hybridauth supports many providers (around 50), and likely will support more in the future. For the purposes of this addon we can confirm the following common ones work well:

• BitBucket (*)
• Discord
• Dropbox
• Facebook
• GitHub
• GitLab
• Google
• MicrosoftGraph (*) (this is Microsoft login, either of your account with Microsoft, or of a private Active Directory installation)
• Reddit
• Twitter
• Vkontakte
• Yahoo
• YouTube

* These do not support avatars/photos, which you might care about when deciding what login options to feature.

For the full list of login options and integration notes refer to the list of providers on the Hybridauth website, and the code comments in the sources_custom/hybridauth/Provider files.
We expect any Hybridauth provider will work with Composr, but we have not tested or optimised any not listed in this documentation.

Setting up providers

On the provider's end

The first thing you do is create an 'app' on the developers section of the provider's website.
The vast majority of providers work via OAuth2.
The actual steps vary from provider-to-provider, but for most you will end up with an OAuth ID and an OAuth secret.
The OAuth Redirect URI used will be both https://yourbaseurl/data_custom/hybridauth.php and https://yourbaseurl/data_custom/hybridauth_admin.php. You will probably need to set it up on the app for security reasons.

On the Composr end

You configure a provider by editing XML in Admin Zone > Setup > Hybridauth Configuration. The XML defined here is mapped automatically to Hybridauth configuration settings as well as whatever settings Composr requires for integration. The XML structure is based on some naming conventions, including the Hybridauth filenames of providers (listed above).

Here is the structure of the basic configuration:

E.g.:

The id and secret values here are standard OAuth2 key parameters. This is of course assuming the provider works via OAuth2, but most do.

Provider-specific notes

Apple (untested)

You may wonder why Apple is not on the list of tested providers. This is supported by Hybridauth but you will need to set up and upload special key files, along with extra PHP software dependencies for Firebase. It likely is not worth the extra effort for you given Apple users likely also have Facebook accounts.

The Apple provider actually takes different values:
See the code comments in sources_custom/hybridauth/Provider/Apple.php for clearer details on these config settings.

Facebook

If you have the facebook_support addon installed then there are friendly configuration options for setting up OAuth2 and enabling login. No XML attributes need setting (but you can do that instead if you prefer, and they take precedence).

Facebook has a wide variety of extra fields, but only if you go through a special approval process and extend the configured scope, e.g.:

Google

There are friendly configuration options for setting up OAuth2 and enabling login. No XML attributes need setting.

Twitter

If you have the twitter_support addon installed then there are friendly configuration options for setting up OAuth2 and enabling login. No XML attributes need setting.

Twitter is using OAuth1 instead of OAuth2. Set XML like:

Twitter apps need to go through an approval process.

LinkedIn (untested)

You may wonder why LinkedIn is not on the list. LinkedIn apps need to go through an approval process and we imagine most users will not want to make the effort. Hybridauth does support it.

MicrosoftGraph

Setting up of MicrosoftGraph on Microsoft's end is a bit complicated. You need to create and configure an "Azure Active Directory" resource on the Azure Portal.
There is an extra tenant option that relates to the "Supported account types" choice you made. You probably will need:

Pinterest (untested)

You may wonder why Pinterest is not on the list. Pinterest was not accepting new apps at the time of testing, although this may no longer be the case. Hybridauth does support it.

StackExchange (suboptimal)

You may wonder why StackExchange is not on the list. StackExchange does not allow transfer of e-mail address, which is important for most sites. Hybridauth does support it.

There is an extra site option that relates to the particular StackExchange site you want to use. It must be set. For example:

Vkontakte

The terminology displayed on Vkontakte's end is a little different:

• App ID is the OAuth2 ID.
• Secure key is OAuth2 secret.

YouTube

The Google configuration options will also be used for YouTube, so don't need configuring in the XML.
E-mail login is not supported.
Video transcoding is supported, and documented further down.

Button display

All the providers mentioned in this documentation are guaranteed to have a nice button icon bundled with Composr, and a human-friendly label. Others may or may not.

You can customise the button display for any provider via more options:

Some notes:

• The button-precedence allows manual sorting (lower numbers are higher precedence)
• The icon is any theme image path under icons/

Admin integration

As well as member login, there is also the ability for the admin to establish a log in for other integrations.

The settings are configured in the same way as member login. However, if you need them different to member logins (maybe setting an extended scope, for example), you can set them under an <admin> node in the XML:

After configuring XML you establish a log in from Admin Zone > Setup > Setup API access by clicking the link under “Connected” for the provider.

Out of the box the following integrations exist, for providers supporting Hybridauth Atom API operations. At the time of writing:

• Facebook
• Instagram
• Twitter
• YouTube

Many providers have an app review process for certain features that broadly overlap with the admin integration here. However, as you are authorising against your own account (which added the app), usually app reviews will not actually be required.

Atom feed display

https://yourbaseurl/data_custom/hybridauth_admin_atom.php?provider=<Provider> will generate an Atom feed for a provider.

There are a couple of extra GET parameters to filter the feed:

• includeContributedContent=0|1 – whether to include 3rd party content posted on the provider feed (if relevant)
• categoryFilter=<categoryFilter> – pass a category ID to filter to a specific category (what categories are depends on the provider; for Facebook blank is the personal feed and a numeric value is for a Facebook page you administer)

Content display (pull)

The main_hybridauth_admin_atoms block allows you to display content from a provider in a way similar to the main_rss or main_news blocks.
A lot of data is passed into the templates for a high degree of flexibility.

Syndication (push)

You can syndicate content (as much of the full content as the provider can handle, combined with a link back to the original content), as well as activities (logs of site actions with a link back to what the action happened on).

Out of the box the following integrations exist, for providers supporting Hybridauth Atom API write operations. At the time of writing:

• Facebook
• Twitter
• YouTube

It needs to be enabled in the XML, each provider needs to specifies what addons/content-types it can syndicate from:

In this example we are configuring Twitter to syndicate from:

• The news addon (content syndication)
• The image content-type (content syndication)
• The video content-type (content syndication)
• The activity_feed addon (this is how you enable activities syndication, which requires the non-bundled activity_feed addon)

And we are saying that by default news will be pre-selected for content syndication (others will need manually selecting on the content add/edit form).

At the time of writing, content syndication is supported for the following content-types:

• catalogue_entry
• download
• event
• image (from the galleries addon)
• news
• quiz
• video (from the galleries addon)

Note that if content syndication is supported for a content-type, activity syndication will be un-selected by default, to avoid unnecessary noise.

Remote hosting / Transcoding

For YouTube combined with gallery videos (only), you can choose to use YouTube as a host after syndication happens.
The video is uploaded to YouTube then the local video is altered to point to it, discarding the uploaded file.

This is done using the remote_hosting configuration property, like:

Media renderer

URLs to content owned by a connected provider (e.g. a Facebook post) can be used with the media rendering system. For example, posting a link within Comcode will provide an embed box.

This works in two possible ways:

• Loading atoms via URLs, and displaying in a media box
• Doing oEmbed through the authenticated API (supported for Instagram and Facebook, as oEmbed needs API keys on these providers)

For Facebook oEmbed, an extra setting is needed, from some values that will be available from the main app…
The main oAuth keys are not shown here as usually this will be done in the Composr configuration UI for Facebook.
The client token is under Settings > Advanced.

And also Instagram…

System Requirements / Dependencies

stats, commandr, PHP curl extension, PHP sessions extension, PHP xml extension

Website Software Requirements

Minimum version: 11

Optional recommendations

activity_feed

Licence

MIT License