Misago 0.28 and later comes with the OAuth2 client built in. This client is useful when you are already using another service for user registrations, login and accounts keeping. If this service implements OAuth 2 protocol, you can delegate user login and registration for your Misago site to it.

Enabling OAuth 2 client in Misago will cause your forum to disable registration form as well as options for changing username, email and password. "Register" button will also be hidden and "Sign in" button will redirect users to your OAuth 2 provider.

Redirect URL to Misago OAuth 2 client

The redirect URL for OAuth 2 server is https://YOURFORUM.COM/oauth2/complete/ (remember to change the YOURFORUM.COM part with your own forum's domain!)

This is where the server's login forum will redirect the user after they complete the auth.

OAuth 2 client setup

To setup OAuth 2 client on your site, sign in to your forum's admin panel, then go to settings and click on either of "OAuth 2" links:

For rest of this guide we will be using "Login with Facebook" as example OAuth 2 provider for the site, but client is configurable enough to support all OAuth 2 clients that expose single API endpoint to retrieve user's id and email.

Basic settings

For now we will skip the "Enable OAuth 2 client". Misago requires that the form is completed before it will let us to enable the client.

Next setting is the "Provider name". This is the name of provider that will be displayed in UI and API messages. For example, if there's a problem with signing in to the site through the provider, Misago will display the "Could not sign in with Provider" error. If API client tries to use the Misago's auth APIs, those will now reply with "This feature has been disabled. Please use Provider to sign in." We will enter "Facebook" into this field.

Client ID and client secret are the values obtained when OAuth 2 is enabled on the OAuth 2 server. OAuth 2 client uses them to prove to the server that it is who it claims to be. In case of Facebook those can be retrieved by configuring new app on the "Meta for Developers" site.

OAuth 2 process settings

For the rest of this guide please keep on mind that OAuth 2 login is a five step process:

OAuth 2 client (your Misago forum) redirects user to a login form on OAuth 2 server (here its "Login to Misago Forum?" app on Facebook)
User logins (or not) using the OAuth 2 form displayed by the OAuth 2 server.
OAuth 2 server redirects user back to the OAuth 2 client (your Misago forum) with information if login was completed or not.
If login was completed Misago retrieves the access token for signed in user from the OAuth 2 server.
If access token could be retrieved, Misago uses it to retrieve the profile of user who has signed in.

Login initialization settings

Those settings setup the first step of the login process - its initialization:

"Login form URL" is the url with login form that users will be redirected to when they click the "Sign in" button on Misago forum. For Facebook this URL is "https://www.facebook.com/v15.0/dialog/oauth".

"Scopes" are names of permissions the user needs to grant to the OAuth 2 clients for login to complete. Misago requires that OAuth 2 server provides at least user ID and email. On some OAuth 2 servers scopes are already configured for clients, while on others the client needs to declare the scopes themselves. Facebook is an example of the latter. For user ID we need the public_profile scope, and for their e-mail we need the email scope. We can write both into this field, separating them with space: "public_profile email".

Access token configuration

Those settings control the fourth step of the OAuth 2 process.

"Access token retrieval URL" is the URL of the API implemented by the OAuth 2 server that Misago will send a request to to retrieve the JSON with access token. For Facebook this URL is "https://graph.facebook.com/v15.0/oauth/access_token".

"Request method" is the HTTP method to use to make the request. Some OAuth 2 servers require the request for access token to be made using GET request while others use POST. For Facebook the valid choice is "GET".

"Extra HTTP headers in token request" is list of extra headers. Facebook doesn't require any extra headers in the request for the access token, but some OAuth 2 servers do. Its common to enter Accept: application/json into this field to tell the server that Misago expects response with the access token to be a JSON.

"JSON path to access token" is a path to the access token in the JSON returned by the server. Facebook's JSON with token looks like this:

{
    "access_token": "...",
    "token_type": "bearer",
    "expires_in":  21370
}

The valid path to the token in Facebook JSON is "access_token".

However if this token was buried deeper in the JSON, we would have to specify the full path separating each segment with a period ("."):

{
    "result": {
        "token": "..."
    }
}

For the above JSON, the valid path would be "result.token".

User data retrieval from the OAuth 2 server

Those settings control the fifth and final step of the OAuth 2 process.

"User data URL" is the URL of the API implemented by the OAuth 2 server that Misago will send a request to to retrieve JSON with user profile. For Facebook this URL is "https://graph.facebook.com/v15.0/me/?fields=id%2Cname%2Cemail%2Cpicture.type%28large%29".

"Request method" is the HTTP method to use to make the request. Some OAuth 2 servers require the request for user data to be made using GET request while others use POST. For Facebook the valid choice is "GET".

"Access token location" is the location of the access token in the user data request that Misago will make. Some OAuth 2 servers require that access token is passed in query string (as part of the "User data URL"), while others require "Authorization: Bearer" or "Authorization" header instead. For Facebook valid choice is "Query string".

"Access token name" controls the name of query string value with the token, or header name (eg. "Authorization"). For Facebook valid value is "access_token".

"Extra HTTP headers in user request" is list of extra headers. Facebook doesn't require any extra headers in the request for the user profile, but some OAuth 2 servers do. Its common to enter Accept: application/json into this field to tell the server that Misago expects response with the user data to be a JSON.

Welcome e-mail settings

This setting only controls if Misago should send a welcome e-mail to the users on first time they signed in.

This option is turned off by default, but its useful for Misago setups where welcome e-mail's template was customized or new user logins require admin activation.

Extracting user data from the JSON returned by the OAuth 2 server

Those settings control the data extraction that occurs on the fifth and final step of the OAuth 2 process.

Valid values for the JSON with user profile returned by the Facebook are:

"User ID path": "id"
"User name path": "name"
"User e-mail path": "email"
"User avatar path": "picture.data.url"

Those paths correspond roughly to this JSON:

{
    "id": 2137,
    "name": "John Doe",
    "email": "john-doe@example.com",
    "picture": {
        "data": {
            "url": "https://placekitten.com/600/500"
        }
    }
}

Remember that if you don't want Misago to download user's profile picture from the OAuth 2 server, you can leave the avatar path setting empty. All other fields are required.

OAuth 2 client configuration guide