Linkding OIDC Integration

This document explains how to implement Monosign with linkding, the open-source, self-hosted bookmark manager. It covers Single Sign-On with OpenID Connect (OIDC), which is built into linkding. linkding uses the Authorization Code flow with PKCE, verifies the signature of the ID token with the keys of Monosign and reads the e-mail address and the name of the user from the Monosign user information endpoint, so the OIDC/OpenID access key of Monosign is used. Before you continue, it is better to read the linkding options documentation.

This configuration is done with linkding 1.47.0 running on Docker (image sissbruecker/linkding:1.47.0-alpine with the SQLite database). If your linkding version or deployment type is different, please check the linkding documentation.

linkding supports OpenID Connect only. SAML is not available. There is no single sign-on screen in the linkding interface; the provider is configured with environment variables. Unlike many applications, linkding does not read the OIDC discovery document: the authorization, token, user information and JWKS addresses of Monosign are entered one by one (see step 4).

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

linkding is free and open source (MIT). Single sign-on is not limited by a license, so it works in the self-hosted version without a key.

📑 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 linkding application
Configuration Single Sign-On for linkding
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)

linkding 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	`linkding`	Name of the application shown to users on the Monosign portal and on the Monosign sign-in page.
Type	`Web`	linkding is accessed through a web browser. Options: Web, Mobile, Desktop, API.
Url	Optional	Leave empty, or enter `https://<linkding-address>/oidc/authenticate/`. With this address, when linkding is opened from the Monosign portal, the user is sent directly to the Monosign sign-in (see step 5).
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). linkding needs the e-mail address of the user.

linkding creates an account for every Monosign user who signs in for the first time, and it matches an existing account by the e-mail address. Make sure the effective User Access Type is Only Assigned Users and give access only to the users you assign in step 3.

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

Keys tab of the linkding 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 linkding application are provided as follows:

Monosign value	Example	Used in linkding as
Client Id	`<client-id>`	`OIDC_RP_CLIENT_ID`
Client Secret	`<client-secret>`	`OIDC_RP_CLIENT_SECRET`
Auth Url	`https://<monosign-host>/openid/authorize`	`OIDC_OP_AUTHORIZATION_ENDPOINT`
Access Token Url	`https://<monosign-host>/openid/token`	`OIDC_OP_TOKEN_ENDPOINT`
User Info Url	`https://<monosign-host>/openid/userinfo`	`OIDC_OP_USER_ENDPOINT`
JSON Web Key Set	`https://<monosign-host>/.well-known/jwks`	`OIDC_OP_JWKS_ENDPOINT`

2- Configuring the OIDC/OpenID Settings on Monosign

Click the Configure button of the OpenID Connect (OIDC) key to open the OIDC/OpenID settings. Enter the scopes that linkding requests and add the callback address of linkding to Allowed Redirect URIs, then press Update.

OIDC/OpenID Settings (1: Scope, 2: Allowed Redirect URIs)

Property	Value	Description
Scope	`openid` `profile` `email`	The scopes that linkding sends in the authorization request (`openid email profile` is its default). Add each scope separated by space.
Allowed Redirect URIs	`https://<linkding-address>/oidc/callback/`	The address where Monosign sends the user back after sign-in. The path `/oidc/callback/` (with the slash at the end) is fixed by linkding. Use the public (HTTPS) address of linkding.
Signing Key / Key Id / Password, Issuer, Audience, Resource	Empty	Optional custom JWT settings. They are not needed. Do not enter the callback address in the Resource field.
Token lifetimes, CORS	Empty	Default values are used.

linkding matches the user by the claim email of Monosign, which is returned by default, so a claim mapping is not required. The new account gets the e-mail address as its user name. To use another claim, for example preferred_username, set OIDC_USERNAME_CLAIM in step 4. The ID token of Monosign is signed with RS256, which is the default algorithm of linkding.

3- Assign a User to the linkding Application

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

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

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

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

4- Configuration Single Sign-On for linkding

As we mentioned at the start, please check out the linkding documentation first. linkding is configured with environment variables. In the Docker Compose deployment add the following variables to the environment file of the linkding container (for example the .env file that is used with env_file) and replace the placeholder values.

Bash

LD_ENABLE_OIDC=True
OIDC_OP_AUTHORIZATION_ENDPOINT=https://<monosign-host>/openid/authorize
OIDC_OP_TOKEN_ENDPOINT=https://<monosign-host>/openid/token
OIDC_OP_USER_ENDPOINT=https://<monosign-host>/openid/userinfo
OIDC_OP_JWKS_ENDPOINT=https://<monosign-host>/.well-known/jwks
OIDC_RP_CLIENT_ID=<client-id>
OIDC_RP_CLIENT_SECRET=<client-secret>
LD_CSRF_TRUSTED_ORIGINS=https://<linkding-host-name>

Variable	Value	Description
LD_ENABLE_OIDC	`True`	Turns the single sign-on on. The login page then shows a Login with OIDC button.
OIDC_OP_AUTHORIZATION_ENDPOINT	`https://<monosign-host>/openid/authorize`	Auth Url of the Monosign access key. Required.
OIDC_OP_TOKEN_ENDPOINT	`https://<monosign-host>/openid/token`	Access Token Url of the Monosign access key. Required.
OIDC_OP_USER_ENDPOINT	`https://<monosign-host>/openid/userinfo`	User Info Url of the Monosign access key. Required.
OIDC_OP_JWKS_ENDPOINT	`https://<monosign-host>/.well-known/jwks`	JSON Web Key Set of the Monosign access key. It is used to verify the signature of the ID token.
OIDC_RP_CLIENT_ID / OIDC_RP_CLIENT_SECRET	Client Id / Client Secret	Copied from the Monosign OIDC/OpenID Access Key Details created in the first step.
LD_CSRF_TRUSTED_ORIGINS	`https://<linkding-host-name>`	Needed when linkding is behind a reverse proxy that rewrites the host name. Otherwise a `POST` request (for example saving a bookmark) can fail with CSRF verification failed.
OIDC_RP_SCOPES	`openid email profile` (default)	Optional. Scopes that linkding requests, separated by space.
OIDC_RP_SIGN_ALGO	`RS256` (default)	Optional. Algorithm that signs the ID token. Monosign uses RS256.
OIDC_USE_PKCE	`True` (default)	Optional. PKCE is supported by Monosign and stays on.
OIDC_VERIFY_SSL	`True` (default)	Optional. Keep it `True`. Set it to `False` only for a test with a self-signed certificate.
OIDC_USERNAME_CLAIM	`email` (default)	Optional. Claim that is used as the user name of a new account, for example `preferred_username`. If the claim is empty, the e-mail address is used.
LD_DISABLE_LOGIN_FORM	`False` (default)	Optional. The local user name and password login stays available next to Monosign. Set it to `True` to allow the single sign-on only.

The environment file contains the client secret. Restrict its permissions (for example chmod 600) and do not store it in a shared repository.

linkding matches users by e-mail address. Create the first administrator before the first sign-in with Monosign and give the account the same e-mail address that the user has in Monosign. Then the administrator is found when the user signs in with OIDC:

Bash

docker compose exec linkding python manage.py createsuperuser --username=<user-name> --email=<e-mail-address>

For reference, this is the Docker Compose file that was used for this document. The alpine image is the smaller variant without the browser that is needed only to save HTML snapshots of bookmarks. The container starts as root, sets the owner of the data directory and then runs the application as a non-root user (www-data), so after dropping all capabilities only the ones that are needed for this are added back.

YAML

services:
  linkding:
    image: sissbruecker/linkding:1.47.0-alpine
    restart: unless-stopped
    ports:
      - "6277:9090"
    volumes:
      - ./data:/etc/linkding/data
    env_file:
      - .env
    cap_drop:
      - ALL
    cap_add:
      - CHOWN
      - DAC_OVERRIDE
      - FOWNER
      - SETUID
      - SETGID
    security_opt:
      - no-new-privileges:true

When linkding is behind a reverse proxy, the proxy must send the header X-Forwarded-Proto: https, because linkding builds the redirect address that is sent to Monosign from the request. After changing the environment file, recreate the container so that the new variables are loaded:

Bash

docker compose up -d --force-recreate linkding

Now try to log in to linkding using Monosign SSO.

Open a new browser window (or a private window) and type the linkding address. The login page of linkding shows the user name and password form and, below it, the Login with OIDC button. When the login form is disabled with LD_DISABLE_LOGIN_FORM=True, only the button is shown. If the Url of the Monosign application is set as described in step 1, opening linkding from the Monosign portal also starts the sign-in directly.

linkding login page with the Login with OIDC button

Click Login with OIDC. 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.
After the sign-in Monosign redirects the browser back to linkding (/oidc/callback/). At the first sign-in linkding creates the account with the e-mail address from Monosign and opens the bookmarks page.

Signed in to linkding with Monosign (bookmarks page of the new account)

Troubleshooting

Symptom	Cause	Solution
The Login with OIDC button is not shown	`LD_ENABLE_OIDC` is not `True`, or the container was not recreated after the change.	Set the variable (step 4) and run `docker compose up -d --force-recreate linkding`.
Monosign shows a redirect URI error	The redirect address that linkding sends does not exactly match the Allowed Redirect URIs, for example because the slash at the end is missing, the address was entered in another field such as Resource, or the proxy does not send `X-Forwarded-Proto: https` so the address starts with `http://`.	Add `https://<linkding-address>/oidc/callback/` to Allowed Redirect URIs in Monosign (step 2) and make the proxy send the header `X-Forwarded-Proto: https`.
An error page appears after returning from Monosign	The Client Id, the Client Secret or one of the four addresses is wrong, or the container cannot reach Monosign.	Copy the values again from the Monosign access key (step 1) and read the linkding container log. Check the DNS and firewall rules of the linkding host.
The ID token cannot be verified	`OIDC_OP_JWKS_ENDPOINT` is wrong, or the signature algorithm does not match.	Use the JSON Web Key Set address of the access key and keep `OIDC_RP_SIGN_ALGO=RS256`.
Certificate error while linkding contacts Monosign	The certificate of Monosign is not issued by a CA that the container trusts.	Use a certificate from a trusted CA. Use `OIDC_VERIFY_SSL=False` only for a test.
Error 403 CSRF verification failed	The proxy rewrites the host name and it is not a trusted origin.	Set `LD_CSRF_TRUSTED_ORIGINS=https://<linkding-host-name>`.
The administrator signs in with Monosign but gets a new account	The e-mail address of the administrator account in linkding is different from the e-mail address in Monosign.	Set the e-mail address of the account to the Monosign one, or create the administrator with `createsuperuser --email` before the first sign-in.
A user cannot sign in	The user is not assigned to the application.	Assign the user in step 3.
SAML sign-in is required	linkding supports OpenID Connect only, not SAML.	Use the OIDC integration in this document.

After completing the configuration on linkding 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 linkding address may cause errors.

📑 Instructions

1- Creating an Application on Monosign

2- Configuring the OIDC/OpenID Settings on Monosign

3- Assign a User to the linkding Application

4- Configuration Single Sign-On for linkding

5- Sign In Test

Troubleshooting