OAuth SSO

[gwbischof]

Lemmy 0.20.0 adds support for SSO using OAuth2 Code Flow and is planned to be released in January.

This document described how it works: https://privacyportal.org/blog/sign-in-with-privacy-portal-tutorial

The Code Flow from the Thunder perspective:

1. Lemmy instances would be able to configure OAuth Providers, Thunder would be able to tell what OAuth Providers are supported by a Lemmy instance by looking at the response from getSite.

2. Thunder would have a button to login with the supported Provider, which would redirect to the Provider's Login page. That redirect would include:

• scope: "openid email"
• response_type: "code"
• state: a random value
• redirect_uri: callback address

And would look something like this:

https://app.privacyportal.org/oauth/authorize?client_id=9d16fb35-090f-4426-a456-368d9412861f&response_type=code&scope=openid%20email&redirect_uri=http%3A%2F%2Flocalhost%3A1236%2Foauth%2Fcallback&state=9f5c5fdb-1ed0-454f-905d-7efb6ea8f15b

redirect_uri is the tricky part. For desktop this means starting an http server that would listen for a response from the Provider, kind of like this:

static Future<Uri> listenForAuth() async {
    HttpServer server = await HttpServer.bind("localhost", 80);
    final req = await server.first;
    final result = req.uri;
    req.response.statusCode = 200;
    req.response.headers.set("content-type", "text/plain");
    req.response.writeln("Authentication successful! You can close this tab.");
    await req.response.close();
    await server.close();
    return result;
  }

For mobile that will look a little different.

3. Thunder receives a "code" from the Provider on the redirect_uri callback, and then gives this code to Lemmy which Lemmy can use to get your name, and email from the Provider.

4. Lemmy checks your email address and gives Thunder a Token (jwt) to authenticate with.

[gwbischof]

I have been looking around for an oauth2 dart package to that can be used to implement the SSO. It needs to do a "Code Flow" and you should get a JWT at the end.

I have gone through a few packages and haven't found one the looks good.

https://github.com/dart-lang/tools/tree/main/pkgs/oauth2 this official one doesn't seem to be maintained, and I can't figure out how to get a JWT at the end. See: dart-lang/tools#375

This one was decent, but I couldn't get the callback working: https://pub.dev/packages/flutter_web_auth_2

I am wondering if I should write it from scratch, but there is some complexity to support the various auth providers and platforms.
Any thoughts about how I should continue?

[gwbischof]

This example code from flutter_web_auth2 looks about right, but the callback wasn't working. Maybe I need to add code to add a http server for the callback.

import 'package:flutter_web_auth_2/flutter_web_auth_2.dart';

import 'dart:convert' show jsonDecode;
import 'package:http/http.dart' as http;

// App specific variables
final googleClientId = 'XXXXXXXXXXXX-xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx.apps.googleusercontent.com';
final callbackUrlScheme = 'com.googleusercontent.apps.XXXXXXXXXXXX-xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx';

// Construct the url
final url = Uri.https('accounts.google.com', '/o/oauth2/v2/auth', {
  'response_type': 'code',
  'client_id': googleClientId,
  'redirect_uri': '$callbackUrlScheme:/',
  'scope': 'email',
});

// Present the dialog to the user
final result = await FlutterWebAuth2.authenticate(url: url.toString(), callbackUrlScheme: callbackUrlScheme);

// Extract code from resulting url
final code = Uri.parse(result).queryParameters['code'];

// Construct an Uri to Google's oauth2 endpoint
final url = Uri.https('www.googleapis.com', 'oauth2/v4/token');

// Use this code to get an access token
final response = await http.post(url, body: {
  'client_id': googleClientId,
  'redirect_uri': '$callbackUrlScheme:/',
  'grant_type': 'authorization_code',
  'code': code,
});

// Get the access token from the response
final accessToken = jsonDecode(response.body)['access_token'] as String;

[hjiangsu]

Thanks for opening the discussion here! I haven't looked too deeply into how OAuth works within the context of Lemmy, but I have an idea:

• For the redirect_uri, could we use a custom scheme here? Thunder is currently registered with the thunder:// scheme, so the redirect URI could be thunder://oauth/callback for example
• We can then add in logic to handle the thunder://oauth callback to obtain the authorization code (and store that into the local database for later use)
• Note: I'm not entirely sure if this would work on a web-based build since deep links/custom schemes may not be supported there

If you have some instructions on how I can run the current implementation, I can also test it out myself and see if I can get it to work properly!

You can also see the following code to get an understanding on how our custom scheme is parsed:

thunder/lib/thunder/pages/thunder_page.dart

Line 209 in d8bb721

Future<void> _handleDeepLinkNavigation(

[gwbischof]

I'll write up some instructions shortly.

I tried using thunder://oauth/callback as the callback url in Privacy Portal but I get this error:

@privacyguard are redirect_uri like thunder://oauth/callback possible?

[gwbischof]

See instructions below

[privacyguard]

@gwbischof we don't support custom URI schemes for security reasons (potential impersonation by other apps). The recommended approach here would be to use Universal Links instead on iOS and its equivalent on Android. We also recommend using PKCE once it gets merged into Lemmy. This means you can have an https URI on the domain owned by your application that would deeplink back into your app.

[gwbischof]

@hjiangsu @micahmo what about using this package? https://pub.dev/packages/app_links

[micahmo]

Hey just throwing in my two cents here. I'll admit I haven't read the Privacy Portal document (it's on my to-do list!), so if I'm way off base here, please feel free to disregard everything I'm saying. 😊

All this notion of a callback server embedded within Thunder makes me question the design. If Thunder were a standalone app that we wanted to let people log into via SSO, then sure we'd need to allow the third-party auth service to call back to us with the token and such. But Lemmy is already a hosted service, and it should be handling all of the redirects and callbacks back to itself. Then it should just provide a token back to us as the client, like it does now with username/password. The way I would expect an app like Thunder to implement this functionality is essentially just to use an embedded browser and show the Lemmy login page. Then all the redirects can happen relative to the Lemmy server instead of directly within the Thunder app.

From my limited experience, that's how apps would normally implement SSO to a hosted service. However, just based on what I'm reading in this thread, maybe that's not how Lemmy and/or Privacy Portal are recommending, so, again, feel free to ignore if this is way off base.

[gwbischof]

Thats a good point, this got me thinking.

Some thoughts on the topic..

I don't think default Lemmy has a login page. The Lemmy instance would also have to have lemmy-ui or a different webapp set up.

Also, after Thunder receives the callback from the Auth Provider at the redirect_uri, the same redirect_uri is sent to Lemmy, which Lemmy then includes in its requests to the Provider. The Provider uses this redirect_uri to verify that it matches the original request and sets the scope of authorization codes to be for this specific Thunder app. I don't think that would be possible if a Lemmy login page was used.

[hjiangsu]

Thanks for the input @micahmo! Initially, this is also what I thought the login flow would look like (but as I mentioned previously, I'm not too familiar with how OAuth works within the context of Lemmy).

This is what I was imagining we would have to do on our end:

• From the site response, see if there's any available options to login via SSO for the current instance.
• If so, we would provide a button that opens up a web view to the current instance's login flow for SSO.
• After the authentication flow, we would somehow retrieve back an access token that we could use to authenticate with the existing API like normal.

I was under the assumption that the Lemmy instance admins would be the ones to set up the SSO flows (to interact with the auth providers), and would have a way to provide the client (Thunder) with the tokens required for API access. I'll set up a local Lemmy instance to play around with it to see how it actually works though!

[privacyguard]

The process being described by @hjiangsu is pretty similar to what is needed with minor changes.

• From the site response, see if there's any available options to login via SSO for the current instance.
• If so, you should provide a button that opens up a web view to the current instance's login flow for SSO. This web view opens the authorization_endpoint provided in the site response for the provider in question along with its corresponding params.
  • The redirect_uri, should be an https deeplink back into your application that would provide you with the authorization response.
  • Once the response is received, you should close the web view and handle the response either by displaying an authentication error to the user or by continuing the authentication process with the Lemmy server.
• If the authorization is successful, you can redeem the authorization_code with the Lemmy backend to initiate a user session (which would return a user token as usual).

Please note that PKCE is being implemented on Lemmy Server and is recommended for this use case. It's a minor addition to this process.

[gwbischof]

Setting up a v0.20.0 Lemmy

Clone Lemmy:

Remember to run:

git submodule init
git submodule update --remote

• Update lemmy-ui version in the docker-compose file

+++ b/docker/docker-compose.yml
@@ -53,14 +53,14 @@ services:

   lemmy-ui:
     # use "image" to pull down an already compiled lemmy-ui. make sure to comment out "build".
-    image: dessalines/lemmy-ui:0.19.5
+    image: dessalines/lemmy-ui:dev

• Update the port forward in the nginx section, this is needed for an app to connect to this instance.

+++ b/docker/docker-compose.yml
@@ -12,7 +12,8 @@ services:
       # Note, change the left number if port 1236 is already in use on your system
       # You could use port 80 if you won't use a reverse proxy
       - "1236:1236"
-      - "8536:8536"
+      - "80:8536"

2. Start the containers.

cd lemmy/docker
docker compose up --build

You should be able to see lemmy-ui by connecting to http://localhost:1236

[gwbischof]

I would work off of my Thunder branch because there are a handful of updates needed to make it work with lemmy 0.20.0: https://github.com/gwbischof/thunder/tree/v0.20.0

Then to connect to you local lemmy you would enter your computers ip address like this:

There are some privacyportal instructions here: LemmyNet/lemmy#4881 (comment)

[hjiangsu]

I just tried to follow the instructions for running v0.20.0 but I'm running into some issues with docker compose. Can you provide the specific commit that you're using for Lemmy? I just pulled the latest main branch: LemmyNet/lemmy@e3fccb3

This is the error I'm facing:

4.943 error: rustc 1.80.0 is not supported by the following package:
4.943   [email protected] requires rustc 1.81
4.943 Either upgrade rustc or select compatible dependency versions with
4.943 `cargo update <name>@<current-ver> --precise <compatible-ver>`
4.943 where `<compatible-ver>` is the latest version supporting rustc 1.80.0

[gwbischof]

You can try my fork/branch, I have already updated the docker-compose: https://github.com/gwbischof/lemmy/tree/v0.20.0
You will need to have Rust/Cargo installed and updated, see instructions here: https://doc.rust-lang.org/cargo/getting-started/installation.html

[gwbischof]

Oh, you also have to have this fork checked out: https://github.com/gwbischof/lemmy_api_client/tree/v0.20.0
The Thunder pubspec.yaml points to your local clone of lemmy-api-client

[gwbischof]

@privacyguard do Lemmy and Thunder get different client_ids?

[privacyguard]

No. Client here refers to the OAuth client not the actual frontend client. When a Lemmy server instance is deployed, its admins can setup OAuth for that server. During the setup process, they would register their OAuth application (AKA the client) and they can configure a list of redirect_uris that they allow. These redirect_uris allow admins to decide which frontend applications they want to allow for SSO.

[gwbischof]

Thanks!

[gwbischof]

@privacyguard I've gotten all of the steps working except for the last step of getting the jwt from lemmy.
I am getting an oauth_authorization_invalid error.
I don't see any lemmy logs showing up.

Can you spot anything wrong with this code?
https://github.com/thunder-app/thunder/pull/1593/files#diff-6099d54b51e8b303996f5f59fcad884860f7115c1c05d7d61e31e2c54569d7faR252-R264

Thanks!

[privacyguard]

@gwbischof you can check the Lemmy codebase to see the conditions under which LemmyErrorType::OauthAuthorizationInvalid are returned. One of these conditions is !oauth_provider.enabled. Make sure the provider is actually enabled in lemmy admin configuration. Also make sure the provider ID is actually 1 not another value (use the value returned by GetSite).

The request should be a POST request:
https://github.com/LemmyNet/lemmy-js-client/blob/main/src/http.ts#L1765-L1772
https://github.com/LemmyNet/lemmy-js-client/blob/main/src/types/AuthenticateWithOauth.ts#L7-L20

Content-Type should be application/json.

[gwbischof]

From /api/v3/site:

"id":1,"display_name":"privacyportal","issuer":"https://api.privacyportal.org/","authorization_endpoint":"https://app.privacyportal.org/oauth/authorize","token_endpoint":"https://api.privacyportal.org/oauth/token","userinfo_endpoint":"https://api.privacyportal.org/oauth/userinfo","id_claim":"sub","client_id":"9d16fb35-090f-4426-a456-368d9412861f","scopes":"openid email","auto_verify_email":true,"account_linking_enabled":true,"enabled":true,"published":"2024-11-09T00:12:44.922461Z","updated":"2024-11-30T23:43:21.254926Z"}

It looks like the id is 1 and it is enabled.
I can't tell which condition is creating the error, and the error isn't showing up in my logs, maybe we can update the lemmy code so that these errors go to the logs? I'll try putting some prints in the lemmy code.
https://github.com/LemmyNet/lemmy/blob/main/crates/api_crud/src/user/create.rs#L206

[privacyguard]

@gwbischof After revisiting the Lemmy codebase, the OAuth implementation in Lemmy also requires the path of the callback_uri to be /oauth/callback. This means the iOS universal link path needs to be updated to match it.

[gwbischof]

That was it, its working now, thanks!!

[micahmo]

Nice going @gwbischof and thanks for the help @privacyguard!!

[gwbischof]

@privacyguard is there a way for a client to tell which Providers from the list of oauth_providers from the site_response will work for them?

For example, maybe a Lemmy instance has PrivacyPortal added as a Provider, but the instance hasn't registered the redirect_uri for this client. So the client wont be able to connect with this Provider even though it shows up in the oauth_providers list.

Could something be included in the oauth_providers list, like the list of redirect_uris so that a client can tell if they can use this provider?

[privacyguard]

@gwbischof hiding providers could lead to user confusion. If a server supports OAuth provider A, the administrator is expecting users to be able to sign up and sign in using said provider. They might not know that a client exists and would need to be made aware about it to support it. If a user already signed up using provider A and decides to use a separate client later, they should be able to see the provider in the list otherwise they would get confused and/or create a duplicate account. Instead they should get an error saying that the server administrator must take action to allow logins from this client.

[gwbischof]

Is there a way for the client to tell that a login failed because their redirect_uri wasn't registered?

[privacyguard]

In the redirect callback, we should be returning the following error in that case. There might be differences depending on the provider but you could parse the description to match errors with "redirect_uri".

{"error": "invalid_request", "description": "Unauthorized redirect_uri parameter."}

[privacyguard]

That said, we cannot redirect back to your application with this error but it is the error we display to the users. Decentralization is a challenge in this case because in a normal scenario you'd simply ask the server owners to add your redirect_uri once. In this case, there are many servers and admins. The solution could be adding your app's redirect_uri to the Lemmy documentation under an OAuth section and probably handling the use case within the app with a clever UI when the user closes the oauth window without successfully authenticating.

[gwbischof]

Thanks!

[gwbischof]

@privacyguard
I am a little bit confused about something.

When I was using localhost as the redirect_uri how is the Provider able to tell where to send the code? How does the code make its way back into the client app if the redirect_uri is localhost?

A similar question, If we send a redriect_uri to the oauth provider, and the redirect_uri is something like https://thunderapp.dev/oauth/callback then the oauth provider sends the auth code to that address, how does that auth code get routed back to a users thunder instance?

Thanks, and sorry for all of the questions!

[privacyguard]

@gwbischof the redirections are happening within your browser. From the provider's page running within in your browser to the localhost page. Similarly with deeplinks/universal links, the OS will override the path if the app is installed.

[gwbischof]

Thanks, that makes sense.