cesium

The cesium crate provides a simple interface for authenticating with fediverse servers using the OAuth API.

For more info, see https://docs.joinmastodon.org/spec/oauth/

lib.rs:

cesium

The cesium-oauth crate provides a simple interface for authenticating with fediverse servers using the OAuth API.

For more info, see https://docs.joinmastodon.org/spec/oauth/

In the examples below we use the https://mastodon.art instance. This is purely an example, almost any fediverse instance (mastodon, calckey, pixelfed, etc) should work.

Apps

In order to authenticate with a fediverse server, you first need to register an application. To do so, you can call [apps::register_new_app()]. However, you probably shouldn't register a new app for every authentication attempt. This crate provides a simple file-based implementation for caching your apps, see apps::FileCachedAppProvider. It will automatically register a new app if it needs one for a specific server.

Basic usage:

let app_info = AppInfo::new("Test App", "https://example.org");
let mut provider = FileCachedAppProvider::new("apps.toml", app_info)?;
let registered_app = provider.get_app_for("mastodon.art").await?;

Authentication

Once you have an app, authentication is really simple. Let your user navigate to the url https://[INSTANCE DOMAIN]/oauth/authorize?response_type=code&client_id=[CLIENT ID]&redirect_uri=[REDIRECT_URI]&scope=read:accounts Replace the placeholders with the appropriate values. The client ID can be found in apps::RegisteredApp. An example authorization URL might look like this:

https://mastodon.art/oauth/authorize?response_type=code&client_id=EMNn7o4PkKPB5aggs5aHysiY2CY24CUS3AA8sqvwy9Y&redirect_uri=https://example.org&scope=read:accounts

Once the user logs in, this will redirect them to the provided redirect_uri with a code field as a GET parameter. You will need this code for the next step:

let token = auth::get_auth_token("mastodon.art", "[CODE]", &app, &app_info).await?;
let account = auth::verify_credentials("mastodon.art", &token.access_token).await?;

If this does not result in an error, the authentication was successful. The auth::Account struct it returns contains some basic information about the user.