Ech0 OIDC Integration | Monofor Help

This document explains how to implement Monosign with Ech0, the open-source, self-hosted micro-blogging and note platform. It covers Single Sign-On with OpenID Connect (OIDC), which is built into Ech0 as the Custom OAuth2 provider with the Enable OIDC option. Ech0 validates the ID token of Monosign (signature, issuer, audience and nonce), so the OIDC/OpenID access key of Monosign is used. Before you continue, it is better to read the Ech0 documentation.

This configuration is done with Ech0 5.8.0 running on Docker (image sn0wl1n/ech0). If your Ech0 version or deployment type is different, please check the Ech0 documentation.

Ech0 supports OAuth 2.0 and OpenID Connect; SAML is not available. The provider is configured on the SSO page of the Ech0 panel and only one provider can be active at the same time.

Monofor has no responsibility to do Ech0 configurations. If you need support please contact the Ech0 community or your Ech0 support provider.

Important: Ech0 does not create a user automatically at the first single sign-on. A Monosign identity can sign in only after it has been bound to an existing Ech0 account (step 4). The first account that is registered in Ech0 becomes the Owner.

📑 Instructions

This documentation contains 5 main steps for integration.

Creating an application on Monosign
Configuring the OIDC/OpenID settings on Monosign
Assign a user to the Ech0 application
Configuration Single Sign-On for Ech0
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.

Applications page in Monosign (1: Applications menu, 2: Add New)

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

Creating a new application from scratch (1: Create from scratch)

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

New Application - Application tab (1: Name, 2: Logo (optional), 3: Next)

Property	Value	Description
Name	`Echo`	Name of the application shown to users on the Monosign portal and on the Monosign sign-in page.
Type	`Web`	Ech0 is accessed through a web browser. Options: Web, Mobile, Desktop, API.
Url	Optional	Leave empty or enter the Ech0 address so users can open the application from their Monosign portal.
Logo	Optional	Browse and upload a logo; it is also shown on the Monosign sign-in page.
Users can see this application on their list	`Enabled`	Displays the application on the user portal.

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

New Application - Access tab (1: Profile Access Type, 2: Create Application)

Property	Value	Description
User Access Type	`System Default`	Defines which users can access this application. Options: Only Assigned Users, All Users, System Default.
User Group Access Type	`System Default`	Defines the application’s user group access.
Source Using Type	`System Default`	Defines which user sources the application can use.
Profile Access Type	`All`	Defines which user profile attributes are available to the application (Options: Restricted, All).

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

Keys tab of the Echo application (1: Keys, 2: Add New Access Key)

Select OIDC/OpenID as the key type and click Create. Monosign generates the Client Id and Client Secret automatically.

Creating the OIDC/OpenID Access Key (1: Type OIDC/OpenID, 2: Create)

Property	Value	Options
Type	`OIDC/OpenID`	Rest API, OAuth 2.0, JWT, OIDC/OpenID, SAML, RADIUS, Access Gateway, LDAP, AuthN/Z Server
Client Id / Client Secret	Generated automatically	Use the eye icon next to the secret to reveal it. Both values are required in step 4.
Session	`System Default`	System Default, On-demand, Permanent
State	`Enabled`	Enabled, Disabled
Never Expires	`Yes`	Turn off to define a specific expiration date for the key.

Configuration details for the Echo application are provided as follows:

Monosign value	Example	Used in Ech0 as
Client Id	`<client-id>`	Client ID
Client Secret	`<client-secret>`	Client Secret
Auth Url	`https://<monosign-host>/openid/authorize`	Auth URL
Access Token Url	`https://<monosign-host>/openid/token`	Token URL
User Info Url	`https://<monosign-host>/openid/userinfo`	UserInfo URL
Issuer (Configuration Url without the `.well-known/openid-configuration` part)	`https://<monosign-host>/`	Issuer
JSON Web Key Set	`https://<monosign-host>/.well-known/jwks`	JWKS URL

2- Configuring the OIDC/OpenID Settings on Monosign

Click the Configure button of the OpenID Connect (OIDC) key to open the OIDC/OpenID settings and add the callback address of Ech0 to Allowed Redirect URIs.

OIDC/OpenID Settings (1: Allowed Redirect URIs)

Property	Value	Description
Allowed Redirect URIs	`https://<ech0-address>/oauth/custom/callback`	The address where Monosign sends the user back after sign-in. The path is `/oauth/<provider>/callback`; for the Custom provider it is `/oauth/custom/callback` (there is no `/api` prefix). Use the public (HTTPS) address of Ech0; the host name must be the same as the one users type in the browser.
Signing Key / Key Id / Password, Issuer, Audience, Scope, Resource	Empty	Optional custom JWT settings. They are not needed.
Token lifetimes, CORS	Empty	Default values are used.

Ech0 identifies the user with the sub claim of the ID token (together with the issuer). Monosign returns it by default, so a claim mapping is not required.

3- Assign a User to the Ech0 Application

Please follow the below instructions on how to assign a user to the Ech0 application. Open the application, click the Assignments tab and click Assign a User.

Assignments tab of the Echo application (1: Assignments, 2: Assign a User)

Search and select the users who can sign in to Ech0, check the Expiration Date and save. You can select more than one user.

Assign a User dialog (select the users, set the Expiration Date)

Property	Value	Description
User(s)	Selected users	Users who can sign in to Ech0 with Monosign.
Expiration Date	Default one year	The assignment expires on this date.

4- Configuration Single Sign-On for Ech0

As we mentioned at the start, please check out the Ech0 documentation first. Ech0 is configured in its panel; there is no configuration file for the provider. Sign in to Ech0 with the Owner account (the first account that was registered), open the SSO page of the panel and the OAuth2 tab. By default the page shows the GitHub template and the OAuth2 login is disabled.

Click the edit icon, enable OAuth2, select the Custom template and fill in the Monosign values.

OAuth2 settings with the Monosign values (Custom template, OIDC enabled)

Setting	Value	Description
Enable OAuth2	On	Turns the single sign-on on.
OAuth2 template	`Custom`	Provider for any OAuth2 / OIDC server. The provider name `custom` is part of the callback address.
Client ID / Client Secret	Client Id / Client Secret	Copied from the Monosign OIDC/OpenID Access Key Details created in the first step.
Callback URL	`https://<ech0-address>/oauth/custom/callback`	Must be the same as the Allowed Redirect URI in Monosign.
Auth URL	`https://<monosign-host>/openid/authorize`	Authorization endpoint of Monosign.
Token URL	`https://<monosign-host>/openid/token`	Token endpoint of Monosign.
UserInfo URL	`https://<monosign-host>/openid/userinfo`	UserInfo endpoint of Monosign. Ech0 requires the Auth URL, Token URL and UserInfo URL to be filled in even when OIDC is enabled; otherwise it answers that OAuth2 is not configured.
Scopes	`openid`	Requested scopes, separated by space. With OIDC enabled Ech0 adds `openid` by itself.
Enable OIDC	On	Ech0 validates the ID token instead of reading the user from the UserInfo endpoint.
Issuer	`https://<monosign-host>/`	Issuer of Monosign. It must be exactly the `issuer` of the discovery document, including the trailing slash.
JWKS URL	`https://<monosign-host>/.well-known/jwks`	Public keys that are used to verify the signature of the ID token.
Redirect Allowlist / CORS Origins	`https://<ech0-address>/auth` / `https://<ech0-address>`	The “Authentication security boundary”. The configuration health check shows “OAuth ready: Not ready” until both are set. Click Auto-fill recommended settings to fill them.

The client secret and the JWT_SECRET of Ech0 are stored on the server. Restrict the permissions of the environment file (for example chmod 600) and the data folder, and do not store them in a shared repository.

Save the settings. Then bind the Monosign identity to your Ech0 account: at the bottom of the SSO page, in the Account binding card, click the bind button. Ech0 redirects the browser to Monosign, you sign in, and Ech0 stores the identity (the sub claim and the issuer) for the signed-in Ech0 account.

The binding is made once for every user. Another user who should use Monosign must first have an Ech0 account (created by the Owner or by registration) and bind the Monosign identity in the same way.

For reference, the Docker deployment that was used for this document is below. The container runs as a non-root user and the data folder must be writable by this user.

YAML

services:
  ech0:
    image: sn0wl1n/ech0:latest
    container_name: ech0
    user: "10001:10001"
    ports:
      - "6277:6277"
    environment:
      - JWT_SECRET=<long-random-secret>
    volumes:
      - ./data:/app/data
    cap_drop:
      - ALL
    security_opt:
      - no-new-privileges:true
    restart: unless-stopped

When Ech0 is behind a reverse proxy, the proxy must send the header X-Forwarded-Proto: https, and the address that users type in the browser must be the same as the Callback URL.

Now try to log in to Ech0 using Monosign SSO.

Open a new browser window (or a private window) and type the Ech0 address. On the sign-in page click the Sign in with OAuth2 icon next to the Login button.

Ech0 sign-in page (1: Sign in with OAuth2)

Ech0 redirects the browser to the Monosign sign-in page of the Echo application. You can 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.
After the sign-in Monosign redirects the browser back to Ech0 (/oauth/custom/callback). Ech0 finds the bound account and opens the Ech0 home page (Feed).

User logged in to Ech0 through Monosign SSO (Ech0 home page)

The sign-in of Ech0 starts when the user clicks the OAuth2 icon on the Ech0 sign-in page. Open Ech0 from the Monosign portal by entering the Ech0 address as the Url of the application (step 1); the user then clicks the OAuth2 icon once.

Troubleshooting

Symptom	Cause	Solution
The sign-in address shows a JSON message “OAuth2 未配置” (OAuth2 is not configured)	The Auth URL, Token URL, UserInfo URL, Client ID, Client Secret or Callback URL is empty, or the provider is not `custom`. All of them are required, also when OIDC is enabled.	Fill in all fields on the SSO page (step 4) and save.
After the sign-in at Monosign Ech0 shows a JSON message “错误的参数” (wrong parameter), and the Ech0 log contains `identity_not_bound_or_lookup_failed` and `record not found`	The Monosign identity is not bound to an Ech0 account. Ech0 does not create users by itself.	Sign in to Ech0 with the local account first, open the SSO page and use the Account binding card (step 4). Then try the OAuth2 sign-in again.
The health check shows “OAuth ready: Not ready” and the missing items “Redirect Allowlist, CORS Origins”	The authentication security boundary is empty.	Click Auto-fill recommended settings or enter `https://<ech0-address>/auth` and `https://<ech0-address>`.
Monosign shows a redirect URI error	The redirect URI that Ech0 sends does not exactly match the Allowed Redirect URIs.	Add `https://<ech0-address>/oauth/custom/callback` in Monosign (step 2) and use the same address as the Callback URL of Ech0.
Ech0 rejects the sign-in after returning from Monosign and the log mentions the ID token	The Issuer or the JWKS URL is wrong (for example the trailing slash of the issuer is missing), or the Client ID is different.	Use the `issuer` value of `https://<monosign-host>/.well-known/openid-configuration` exactly as it is and the JWKS URL `https://<monosign-host>/.well-known/jwks`.
A new Monosign user cannot sign in	The user has no Ech0 account or the identity is not bound.	Create the Ech0 account, sign in with it and bind the Monosign identity. Also assign the user in Monosign (step 3).
Ech0 cannot reach Monosign (certificate or network error in the log)	The container cannot resolve or trust the address of Monosign.	Check DNS and firewall rules of the Ech0 host and that the certificate of Monosign is issued by a trusted CA.
SAML sign-in or more than one provider is required	Ech0 supports OAuth 2.0 / OIDC only and one provider at a time.	Use the OIDC integration in this document.

After completing the configuration on Ech0 and Monosign, it is better to test in a new private browser window if the OIDC SSO doesn’t work, because old session cookies of the Ech0 address may cause errors.