Karakeep OIDC Integration

This document explains how to implement Monosign with Karakeep, the open-source application to save and organize bookmarks, notes and images. It covers Single Sign-On with OpenID Connect (OIDC), which is built into Karakeep. Karakeep reads the Monosign addresses from the OIDC discovery document, uses the Authorization Code flow with PKCE and takes the user from the identity provider, so the OIDC/OpenID access key of Monosign is used. Before you continue, it is better to read the Karakeep configuration documentation.

This configuration is done with Karakeep 0.34.0 running on Docker (image ghcr.io/karakeep-app/karakeep:0.34.0). If your Karakeep version or deployment type is different, please check the Karakeep documentation.

Karakeep supports OpenID Connect only. SAML is not available. There is no single sign-on screen in the Karakeep interface; the provider is configured with environment variables. OIDC is enabled only when OAUTH_WELLKNOWN_URL and OAUTH_CLIENT_ID are set (see step 4).

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

Karakeep is free and open source (AGPL-3.0). 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 Karakeep application
Configuration Single Sign-On for Karakeep
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)

Karakeep 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	`Karakeep`	Name of the application shown to users on the Monosign portal and on the Monosign sign-in page.
Type	`Web`	Karakeep is accessed through a web browser. Options: Web, Mobile, Desktop, API.
Url	Optional	Leave empty or enter the Karakeep address (for example `https://<karakeep-address>`). When Karakeep is opened from the Monosign portal, the user lands on the Karakeep sign-in page and clicks Sign in with Monosign (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). Karakeep needs the e-mail address and the name of the user.

Karakeep creates an account for every Monosign user who signs in for the first time. 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 Karakeep 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 Karakeep application are provided as follows:

Monosign value	Example	Used in Karakeep as
Client Id	`<client-id>`	`OAUTH_CLIENT_ID`
Client Secret	`<client-secret>`	`OAUTH_CLIENT_SECRET`
Configuration Url	`https://<monosign-host>/.well-known/openid-configuration`	`OAUTH_WELLKNOWN_URL`. Karakeep reads the Auth, Token, UserInfo and JWKS addresses from this document.

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 Karakeep requests and add the callback address of Karakeep to Allowed Redirect URIs, then press Update.

Property	Value	Description
Scope	`openid` `profile` `email`	The scopes that Karakeep sends in the authorization request. Add each scope separated by space.
Allowed Redirect URIs	`https://<karakeep-address>/api/auth/callback/custom`	The address where Monosign sends the user back after sign-in. The path `/api/auth/callback/custom` is fixed by Karakeep. Use the public (HTTPS) address of Karakeep; it must be the same as `NEXTAUTH_URL` of step 4.
Signing Key / Key Id / Password, Issuer, Audience, Resource	Empty	Optional custom JWT settings. They are not needed.
Token lifetimes, CORS	Empty	Default values are used.

Karakeep reads the name, the e-mail address and the picture of the user from the claims name, email and picture, which Monosign returns by default, so a claim mapping is not required.

3- Assign a User to the Karakeep Application

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

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

Search and select the users who can sign in to Karakeep, 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 Karakeep with Monosign.
Expiration Date	Default one year	The assignment expires on this date.

4- Configuration Single Sign-On for Karakeep

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

Bash

NEXTAUTH_URL=https://<karakeep-host-name>
OAUTH_WELLKNOWN_URL=https://<monosign-host>/.well-known/openid-configuration
OAUTH_CLIENT_ID=<client-id>
OAUTH_CLIENT_SECRET=<client-secret>
OAUTH_PROVIDER_NAME=Monosign
OAUTH_SCOPE=openid email profile

Variable	Value	Description
NEXTAUTH_URL	`https://<karakeep-host-name>`	Public HTTPS address of Karakeep. The redirect address that is sent to Monosign is built from it, so it must match the Allowed Redirect URI of step 2.
OAUTH_WELLKNOWN_URL	`https://<monosign-host>/.well-known/openid-configuration`	Configuration Url of the Monosign access key. Required.
OAUTH_CLIENT_ID / OAUTH_CLIENT_SECRET	Client Id / Client Secret	Copied from the Monosign OIDC/OpenID Access Key Details created in the first step. When the secret is not set, Karakeep acts as a public client and relies on PKCE only. When `OAUTH_WELLKNOWN_URL` or `OAUTH_CLIENT_ID` is missing, OIDC stays disabled and no Monosign button is shown.
OAUTH_PROVIDER_NAME	`Monosign`	Name of the provider on the sign-in page (Sign in with Monosign). Default: Custom Provider.
OAUTH_SCOPE	`openid email profile`	Scopes that Karakeep requests, separated by space. This is the default value.
OAUTH_TOKEN_ENDPOINT_AUTH_METHOD	`client_secret_basic` (default)	Optional. How Karakeep authenticates to the token endpoint: `client_secret_basic` or `client_secret_post`. Monosign accepts both.
OAUTH_ALLOW_DANGEROUS_EMAIL_ACCOUNT_LINKING	`false` (default)	Optional. When it is `false`, a Monosign sign-in is not linked to an existing local Karakeep account with the same e-mail address. Set it to `true` only if you fully trust the identity provider.
DISABLE_PASSWORD_AUTH / OAUTH_AUTO_REDIRECT	`false` (default)	Optional. Local e-mail and password sign-in stays available next to Monosign. Set `DISABLE_PASSWORD_AUTH=true` to allow the single sign-on only and add `OAUTH_AUTO_REDIRECT=true` to send the user directly to Monosign.
DISABLE_SIGNUPS	`false` (default)	Optional. When it is `true`, new users cannot be created, also not through Monosign. Only existing accounts can sign in.

Karakeep also needs the basic variables of every installation. In the Docker deployment that was used for this document they are:

Bash

NEXTAUTH_SECRET=<random-string>
DISABLE_NEW_RELEASE_CHECK=true

Generate the secret with openssl rand -base64 36. DISABLE_NEW_RELEASE_CHECK is optional.

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

For reference, the Docker Compose file that was used for this document is below. It is the lightest installation with one container: the optional headless Chrome and Meilisearch services of the official Compose file are not used, so pages are fetched without a browser and the search is disabled. To use them, start from the official Karakeep Docker Compose file and add the same variables. The image uses an init system that needs a few capabilities, so only these are added back after dropping all.

YAML

services:
  web:
    image: ghcr.io/karakeep-app/karakeep:0.34.0
    restart: unless-stopped
    volumes:
      - data:/data
    ports:
      - "6277:3000"
    env_file:
      - .env
    environment:
      DATA_DIR: /data
    cap_drop:
      - ALL
    cap_add:
      - CHOWN
      - DAC_OVERRIDE
      - FOWNER
      - SETUID
      - SETGID
    security_opt:
      - no-new-privileges:true

volumes:
  data:

When Karakeep is behind a reverse proxy, the proxy must send the header X-Forwarded-Proto: https and forward the real host name. Recreate the Karakeep container so that the new variables are loaded:

Bash

cd <karakeep-compose-directory>
docker compose up -d --force-recreate web

The first account that registers in Karakeep becomes the administrator. Create the local administrator account (Sign up) before turning on the single sign-on, so that the first Monosign user does not become the administrator by accident.

Now try to log in to Karakeep using Monosign SSO.

Open a new browser window (or a private window) and type the Karakeep address. The sign-in page of Karakeep shows the e-mail and password form and, below it, the Sign in with Monosign button. When the password sign-in is disabled together with OAUTH_AUTO_REDIRECT=true, Karakeep redirects the browser directly to Monosign.

Karakeep sign-in page with the Sign in with Monosign button

Click Sign in with Monosign. 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 Karakeep (/api/auth/callback/custom). At the first sign-in Karakeep creates the account with the name and the e-mail address from Monosign and opens the home page. The user menu in the upper right corner shows them.

Troubleshooting

Symptom	Cause	Solution
The Sign in with Monosign button is not shown	`OAUTH_WELLKNOWN_URL` or `OAUTH_CLIENT_ID` is missing, so OIDC is disabled, or the container was not recreated after the change.	Set both variables (step 4) and run `docker compose up -d --force-recreate web`.
Monosign shows a redirect URI error	The redirect address that Karakeep sends does not exactly match the Allowed Redirect URIs, for example because `NEXTAUTH_URL` is wrong.	Add `https://<karakeep-address>/api/auth/callback/custom` in Monosign (step 2) and set `NEXTAUTH_URL` to the same public HTTPS address.
Karakeep cannot reach Monosign (error in the log about the discovery document, certificate or network)	The container cannot resolve or trust the address of Monosign.	Check `OAUTH_WELLKNOWN_URL`, the DNS and firewall rules of the Karakeep host and that the certificate of Monosign is issued by a trusted CA.
An error is shown after returning from Monosign	The Client Id or Client Secret is wrong, or the token endpoint authentication method is not accepted.	Copy the values again from the Monosign access key and read the Karakeep container log. Try `OAUTH_TOKEN_ENDPOINT_AUTH_METHOD=client_secret_post`.
The name of the user is empty or wrong	The `name` claim is missing.	Set `Profile Access Type` to All (step 1).
A user cannot sign in	The user is not assigned to the application.	Assign the user in step 3.
A new user cannot sign in with Monosign	`DISABLE_SIGNUPS=true` is set, so no new account can be created.	Remove the variable or create the account in Karakeep first.
Sign in with Monosign fails for an e-mail address that already has a local account	Account linking is off by default.	Sign in with the local account, or set `OAUTH_ALLOW_DANGEROUS_EMAIL_ACCOUNT_LINKING=true` if the identity provider is trusted.
The container restarts continuously with an error about changing the owner of a directory	All capabilities were dropped, but the init system of the image needs a few of them.	Add back the capabilities `CHOWN`, `DAC_OVERRIDE`, `FOWNER`, `SETUID` and `SETGID` as in the Compose file above.
SAML sign-in is required	Karakeep supports OpenID Connect only, not SAML.	Use the OIDC integration in this document.

After completing the configuration on Karakeep 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 Karakeep 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 Karakeep Application

4- Configuration Single Sign-On for Karakeep

5- Sign In Test

Troubleshooting