Akkoma OAuth2 Integration

This document explains how to implement Monosign with Akkoma, the open source federated social network server (a fork of Pleroma). It covers Single Sign-On with OAuth 2.0, which Akkoma provides as the OAuth consumer mode based on the Ueberauth library. Akkoma uses the Authorization Code flow and reads the user from the user information endpoint, so the OIDC/OpenID access key of Monosign is used. Before you continue, it is better to read the Akkoma documentation (opens in a new tab) about the OAuth consumer mode.

Instructions

This documentation contains 5 main steps for integration.

1. Creating an application on Monosign

2. Configuring the OIDC/OpenID settings on Monosign

3. Assign a user to the Akkoma application

4. Configuration Single Sign-On for Akkoma

5. Sign In Test

1- Creating an Application on Monosign

Create your application on Monosign first. Open the Applications page from the left menu and click Add New.

Akkoma is not in the application catalog, so click Create from scratch.

Fill in the application details on the Application tab and click Next.

On the Access tab define who can reach the application and click Create Application.

After the application is created, click Keys and add a new Access Key for OIDC/OpenID access.

Select OIDC/OpenID as the key type and click Create. Monosign generates the Client Id and Client Secret automatically. Akkoma consumes the key with OAuth 2.0 and does not read the discovery document, so every address is entered one by one.

Configuration details for the Akkoma application are provided as follows:

2- Configuring the OIDC/OpenID Settings on Monosign

Open the Keys tab of the application and click the Configure button of the OpenID Connect (OIDC) key to open the OIDC/OpenID settings.

Add the callback address of Akkoma to Allowed Redirect URIs, enter the scopes in the Scope field, then press Update.

3- Assign a User to the Akkoma Application

Open the application in Monosign, click the Assignments tab and click Assign a User.

Search and select the users who can sign in to Akkoma, check the Expiration Date and save. You can select more than one user. Every user needs an e-mail address, a name and a user name in Monosign.

4- Configuration Single Sign-On for Akkoma

4.1 Akkoma configuration

As we mentioned at the start, please check out the Akkoma documentation first. Akkoma uses the Ueberauth strategy Keycloak because it lets you enter every address of the provider; it works with Monosign even though Monosign is not a Keycloak server. The provider is given the name monosign so that the sign-in button and the callback address carry the name Monosign. Add the following lines to the configuration file of Akkoma, replace the placeholder values and restart Akkoma.

monosign_url = "https://<monosign-host>"

config :ueberauth, Ueberauth.Strategy.Keycloak.OAuth,
  client_id: "<client-id>",
  client_secret: "<client-secret>",
  site: monosign_url,
  authorize_url: "#{monosign_url}/openid/authorize",
  token_url: "#{monosign_url}/openid/token",
  userinfo_url: "#{monosign_url}/openid/userinfo",
  token_method: :post

config :ueberauth, Ueberauth,
  providers: [
    monosign: {Ueberauth.Strategy.Keycloak, [uid_field: :email, default_scope: "openid profile email"]}
  ]

config :pleroma, :auth, oauth_consumer_strategies: ["monosign"]

4.2 Correction of the token request

The Keycloak strategy sends the client credentials in the body of the token request and the library adds them again in an Authorization: Basic header. Monosign accepts the client credentials in only one place and answers with the error Multiple client credentials cannot be specified; Akkoma then shows Internal server error after the sign-in. Edit the function get_token in the file deps/ueberauth_keycloak_strategy/lib/ueberauth/strategy/keycloak/oauth.ex so that only the body is used:

def get_token(client, params, headers) do
  client
  |> put_param("client_id", client().client_id)
  |> put_param("client_secret", client().client_secret)
  |> put_param("grant_type", "authorization_code")
  |> put_param("redirect_uri", client().redirect_uri)
  |> put_header("Accept", "application/json")
  # replaces: |> OAuth2.Strategy.AuthCode.get_token(params, headers)
  |> merge_params(params)
  |> put_headers(headers)
end

Then compile the dependency again and restart Akkoma (mix deps.compile ueberauth_keycloak_strategy --force). Repeat this correction after every mix deps.get that downloads the dependency again.

5- Sign In Test

The login page of Akkoma shows only the user name and password form. The sign-in with Monosign is offered on the authorization page that an application opens when it asks for access to an account (for example a mobile or web client of Akkoma). To test it without a client, register a test application and open its authorization address:

curl -X POST https://<akkoma-address>/api/v1/apps \
  -d 'client_name=SSO Test' -d 'redirect_uris=urn:ietf:wg:oauth:2.0:oob' -d 'scopes=read'

https://<akkoma-address>/oauth/authorize?client_id=<client_id from the answer>&redirect_uri=urn:ietf:wg:oauth:2.0:oob&response_type=code&scope=read

Open the second address in a new browser window (or a private window). Below the user name and password form the page shows Sign in with external provider and the button Sign in with Monosign.

1. Click the Sign in with Monosign button once.

2. On the Monosign sign-in page log in passwordless with your QR code (Monofor Identity), with a Passkey or with your user name and password (Sign in with Password). If you are already signed in to Monosign, the page is skipped.

3. After the sign-in Monosign redirects the browser back to Akkoma (/oauth/monosign/callback). At the first sign-in Akkoma shows the Registration Details with the nickname and the e-mail address from Monosign. Change the nickname if it contains a dot, and click Proceed as new user. To link the Monosign user to an account that already exists in Akkoma, enter its name or e-mail address and password and click Proceed as existing user.

4. After the registration Akkoma authorizes the application and shows the token code. At the next sign-ins Akkoma recognizes the user by the e-mail address and authorizes the application without the registration form.

Troubleshooting