XF 2.3 Single sign on and more with OAuth2 in XenForo 2.3

We're approaching the conclusion of the 'Have you seen...?' series for XenForo 2.3. While it may seem like a bittersweet moment, we've intentionally saved one of the most exciting revelations until last. In the upcoming weeks, we might delve into a few more miscellaneous changes and improvements and provide a more developer-centric round up. However, our primary goal is to have XenForo 2.3 up and running on XenForo.com by the end of November. Beyond that milestone, we're excited to share a couple more surprises with you, which will include an overview of the latest enhancements in XenForo Resource Manager, Enhanced Search, and Media Gallery 2.3.

But, back to today, and not only is this an exciting revelation, but it also signals the implementation of our most popular suggestion of all time. Your XenForo installation will be able to act as an OAuth2 server and this opens up a whole array of advanced use cases:

• Single sign on between your forum and another XenForo installation
• Single sign on between your forum and another software
• Building a different front end for your forum, such as a single page app
• Building a native smartphone app for your forum
• Integration between your forum and another application
• Accessing the XenForo REST API as a specific user with a OAuth token

As ever, let's take a look at how to set this up in XenForo 2.3. In the following example we're going to configure an OAuth2 client on a primary XenForo instance and use a secondary XenForo instance to use that primary instance as a connected account provider.

You can add as many OAuth2 clients as you need and this can be done from your admin control panel under Setup > OAuth2 clients (which lists all clients you have created) and clicking "Add OAuth2 client".

And this is what it looks like all filled in:

Most of this is self explanatory. Title, Description, Homepage URL and Image URL are used for branding any OAuth authorization page. Let's take a closer look at a couple of other inputs on ths page.

Client type​

The difference between "Public" and "Confidential" client types may not be immediately obvious but it is crucial. For the sheer majority of OAuth integrations you might have experience with in the past, you are most likely more familiar with the default option which is the "Confidential" type.

For most applications the "Confidential" type is fine. This means you're able to keep the client secret confidential - in other words, the client secret isn't stored or revealed anywhere by the client. This would be appropriate for a XenForo to XenForo connected account.

For situations where it's not safe to store a secret in the client application (like in JavaScript, single-page apps, or native apps), you should choose the 'Public' client type. When using the 'Public' type, you employ the Proof Key for Code Exchange (PKCE) authorization flow. Instead of sharing a secret, you create a random string. This random string serves as a secure way to confirm your identity during the authorization and token exchange process.

It should be noted that PKCE is required for public clients and recommended for confidential clients. A deeper dive into PKCE is beyond the scope of this post, but rest assured everything will be documented via the manual and/or developer documentation before XenForo 2.3 is released.

Authorization / Token / Revocation endpoints​

These are simply the endpoints you need to communicate with in order to authorize, retrieve a token and revoke tokens as per the OAuth 2.0 specs.

Redirect URIs​

Here you can add one or more redirect URIs. These are the approved redirect URIs that the secondary instance may use. Occasionally you might need more than one redirect URI to support different domains or different endpoints that may get called as part of the process. In this example, as we're going to be communicating from a second XenForo forum, its connected_account.php is sufficient as a redirect URI.


Once the client is created you will be able to view your credentials:

Armed with these, we can now set up a connected account provider on the secondary XenForo instance.

The connected account side of things is all very familiar if you've ever set up any of the existing ones before. The crucial thing is to make sure you get the target board URL correct.

But what you really want to see is the authorization process, don't you?

Via the login, registration or Account > Connected accounts page, as soon as you click the button that corresponds to your new XenForo connected account provider, you will be redirected to the authorization page:

Clicking Authorize will complete the usual steps to authenticate you using OAuth and redirect you back:

If you have approved any applications to access your XenForo account then you can see a list of them under Account > Applications:

While exciting in itself, this is merely a single use case amongst many that our OAuth implementation will open up. And this is where we will leave it for this week. Next week we'll be focusing an entire 'Have you seen...?' entry on what's new for developers in XenForo 2.3. This will enable us to provide a more detailed dive into some smaller, developer-centric changes, including a closer look at some more advanced parts of OAuth such PKCE, authenticating against the REST API and refresh tokens.

If developers want us to talk about anything specific in more detail that we might have mentioned in the last few weeks, please do let us know.

 

[KartaL]

To clarify my reference to November in the original post was intended to be 2024. The mention of 2026 above was me poking a little fun.

I understand. What month is 2024? I want to update my license with the new version. That's why I'm asking. We are so excited

 

[whynot]

What month is 2024?

The lucky thirteenth.

 

[KartaL]

The lucky thirteenth.

I think you're a little loose.

 

[SelamT]

So what I understand from what you wrote is that I can register Site1 with the new feature that will come and use the Site2?

 

[cwe]

If I owned two (or more) XF sites and wanted to use this OAuth feature to allow members to register on one of my sites and then log in on any of my other sites, I understand that the act of logging in on a secondary (or tertiary etc.) site will cause the secondary site to create a user account in the database without the member having to go through the registration steps (again). Both of my XF sites will have a user entry in their respective databases for a given member that has done this.

My question now relates to the capabilities of OAuth for synching other account details between XF sites. If, for example, a member is assigned/promoted to a special user group on site A, can OAuth communicate this to site B (so that site B could effect a similar/related user group promotion)?

 

[Alpha1]

What profile fields and settings can be populated by OAuth?
Are secondary usergroups, account state, discouraged, privacy also set by OAuth?

 

[btmgreg]

The lucky thirteenth.

Smarch right?

 

[Kirby]

What profile fields and settings can be populated by OAuth?
Are secondary usergroups, account state, discouraged, privacy also set by OAuth?

OAuth is just for authorization, it does not do anything more than this.
But OAuth can be used to authorize API calls.
I am not a XenForo developer, but I'd assume that that the "XenForo" connected account provider will make use of API call me.

So theoretically everything returned by that call could be consumed - but I would expect that basically only username and email are used.
(Maybe also avatar, birthday, website, location, about)

Populating profile fields, settings or usergroups would IMHO pretty much be out-of-scope (at least for now) as that would require more complex logic (mapping, validation, etc.)
But thats just my 0,02 €

I understand that the act of logging in on a secondary (or tertiary etc.) site will cause the secondary site to create a user account in the database without the member having to go through the registration steps (again)

Somewhat.
They will have to go through the registration process, but they will not have to enther their email address (and maybe username) and they will not have to confirm the email.
But they will have to fill out required registration form fields and confirm the terms of service / privacy.
If the "customer" XenForo system is configured to to require account approval the accounts must be approved.
(All that is assuming the XenForo connected account provider behaves like any other connected account provider).

My question now relates to the capabilities of OAuth for synching other account details between XF sites.

As said before: OAuth is just for authorization, it does not do anything more than this.
So: Basically don't expect it to sync anything.

If, for example, a member is assigned/promoted to a special user group on site A, can OAuth communicate this to site B

No.

 

[beerForo]

To clarify my reference to November in the original post was intended to be 2024.

XF won't run 2.3 for another year?

 

[beerForo]

Cool feature, and I'll assume the clarification was supposed to be 2023.

 

[⭐ Alex ⭐]

People seem very confused about how this works. Let me explain.

Let's say XF1 is an OAUTH provider, and XF2 accepts XF1 SSO.

Bill has an account on XF1. He visits XF2 but does not yet have an account there. He is presented with the create an account page. Here are his options:

• Sign up using email.
• Sign up using XF1 account.

Bill chooses "Sign up using XF1 account".
Bill is redirected to XF1 which asks Bill, would you like to give permission to XF2 to access your email address?
Bill delightfully pushes the yes button.
XF2 creates an account for Bill using the email address from XF1 and logs him in.
Bill logs out from XF2.

Tomorrow, Bill comes back to XF2 and wants to login. Bill chooses login with XF1. Bill is redirected to XF1 which validates that Bill is logged in to XF1 and tells XF2 that Bill is authenticated and legitimate, and XF2 logs Bill in without a password.

Bill is delightfully pleased that he does not have an additional password to remember for XF2.

 

[⭐ Alex ⭐]

It seems most people want a family of forums to use single sign on (not me though, nopers). How will they be able to augment that the account they created was created on a decentralized forum/site? Because the most straight forward setup would be, say someone has apple forum and strawberry forum. Say their company is called Fruit. Therefore they should name their SSO, the Fruit account.

It's bad user experience to say, register for your Fruit account at apple forum then use it to register at strawberry forum. Is XF 2.3 providing some sort of solution to this? Would it have to be someone configuring their web server to proxy strawberry.com/register to apple.com/register? If we say apple forum provides the OAUTH.

If we can use our forum as an OAUTH provider we ought to have a special account creation page we can name anything we like right? And have the ability to change the registration page on a secondary forum to load an iframe of the primary forum's registration page and perform single sign on, on completion.

 

[whynot]

Smarch right?

Correct:

 

[cwe]

It seems most people want ...

For my part, I'm asking questions just to understand how this OAuth stuff works. I don't own a family of sites that I want to integrate. I am considering the potential of reaching out to the admins of a few 3rd party XF communities that might be good fits for a mutual OAuth connection (same topic niche, different country focus for example).

 

[Chris D]

Cool feature, and I'll assume the clarification was supposed to be 2023.

It’s been well documented that I have no idea what year it is, okay?

Cool feature, and I'll assume the clarification was supposed to be 2023.

Yes

 

[cwe]

I see where Mediawiki has an OAuth extension:

Extension:OAuth - MediaWiki

www.mediawiki.org

Does this mean that I could make my own wiki site, install the OAuth extension, do configuration magic and my XF forum members could easily log in (via the forum) and edit my Mediawiki site?

 

[cwe]

Follow up question: Can the XF OAuth system be permissioned so that sign ins are restricted to certain user groups? In the example I mentioned above, can I limit OAuth log ins to the wiki site to members of my XF forum that are in certain user groups?

 

[Alpha1]

Can banned or discouraged members use OAuth to sign in at site2?
If we spam clean a user on site1, can they use SSO and continue to spam on site2?

 

[⭐ Alex ⭐]

For my part, I'm asking questions just to understand how this OAuth stuff works. I don't own a family of sites that I want to integrate. I am considering the potential of reaching out to the admins of a few 3rd party XF communities that might be good fits for a mutual OAuth connection (same topic niche, different country focus for example).

Yeah, so the main feature is users of sister forums don't need to create a password. They authenticate using the login system of another forum (the OAUTH provider).

I see where Mediawiki has an OAuth extension:

Extension:OAuth - MediaWiki

www.mediawiki.org

Does this mean that I could make my own wiki site, install the OAuth extension, do configuration magic and my XF forum members could easily log in (via the forum) and edit my Mediawiki site?

No, because they don't have an account on your media wiki site until they register. But if you want you can configure your wiki to only allow register and login using XF.

EDIT: Also from reading that extension you linked, it's talking about MediaWiki becoming the OAUTH server aka provider (aka what XenForo announced they are releasing for XF) As in, you can login on another website using MediaWiki and provide some grants (some limited access to their media wiki account "to which users can give a limited set of permissions ("grants"), so that the application can use the MediaWiki action API on the user's behalf.").

Follow up question: Can the XF OAuth system be permissioned so that sign ins are restricted to certain user groups? In the example I mentioned above, can I limit OAuth log ins to the wiki site to members of my XF forum that are in certain user groups?

No, but if XF implements oauth grants, you can edit the oauth grants to include access to usergroup membership IDs (instead of only accessing email and username). Then when someone is logging into or attempting to modify your wiki, you can check the XF's users usergroup IDs and verify they are still a member of your special usergroup. Otherwise when they attempt to register, login, or edit your wiki you shall present them with a permission error.

 

[cwe]

... you can configure your wiki to only allow register and login using XF.
...

That's what I was hoping for.

No, but if XF implements oauth grants, ...

I'd appreciate some XF confirmation on whether XF will allow user group permissions/restrictions on which user accounts are eligible for OAuth verifications/log ins.