LinkAce OIDC Integration

This document explains how to implement Monosign with LinkAce, the open-source, self-hosted bookmark archive. It covers Single Sign-On with OpenID Connect (OIDC), which is built into LinkAce. LinkAce reads the Monosign addresses from the OIDC discovery document, uses the Authorization Code flow and verifies the signature of the ID token, so the OIDC/OpenID access key of Monosign is used. Before you continue, it is better to read the LinkAce documentation.

This configuration is done with LinkAce 2.6.2 running on Docker (image docker.io/linkace/linkace:v2.6.2 with the SQLite database). If your LinkAce version or deployment type is different, please check the LinkAce documentation.

LinkAce supports OpenID Connect (a generic OIDC provider) and a list of ready-made OAuth providers (for example Google, GitHub, GitLab, Microsoft Azure, Keycloak, Okta, Authentik, Auth0, Zitadel). SAML is not available. There is no single sign-on screen in the LinkAce interface; the provider is configured with environment variables in the .env file of LinkAce.

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

LinkAce is free and open source (GPL-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 LinkAce application
Configuration Single Sign-On for LinkAce
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)

LinkAce 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	`LinkAce`	Name of the application shown to users on the Monosign portal and on the Monosign sign-in page.
Type	`Web`	LinkAce is accessed through a web browser. Options: Web, Mobile, Desktop, API.
Url	Optional	Leave empty, or enter `https://<linkace-address>/auth/sso/oidc/redirect`. With this address, when LinkAce 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). LinkAce needs the e-mail address and the name of the user.

LinkAce creates an account for every Monosign user who signs in for the first time (unless SSO_REGISTRATION_ENABLED=false is set), and it links an existing account that has the same 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 LinkAce 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 LinkAce application are provided as follows:

Monosign value	Example	Used in LinkAce as
Client Id	`<client-id>`	`SSO_OIDC_CLIENT_ID`
Client Secret	`<client-secret>`	`SSO_OIDC_CLIENT_SECRET`
Configuration Url	`https://<monosign-host>/.well-known/openid-configuration`	`SSO_OIDC_BASE_URL`. LinkAce needs the address without the `/.well-known/openid-configuration` part, for example `https://<monosign-host>`. It reads the Auth, Token, UserInfo and JWKS addresses from the 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 LinkAce requests and add the callback address of LinkAce to Allowed Redirect URIs, then press Update.

OIDC/OpenID Settings (Scope and Allowed Redirect URIs)

Property	Value	Description
Scope	`openid` `profile` `email`	The scopes that LinkAce sends in the authorization request (`openid email profile` is the default of its OIDC provider). Add each scope separated by space.
Allowed Redirect URIs	`https://<linkace-address>/auth/sso/oidc/callback`	The address where Monosign sends the user back after sign-in. The path `/auth/sso/oidc/callback` is fixed by LinkAce. Use the public (HTTPS) address of LinkAce; it must be the same as `APP_URL` of step 4.
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.

LinkAce reads the e-mail address and the name of the user from the claims email, name and preferred_username, which Monosign returns by default, so a claim mapping is not required. The user name in LinkAce is taken from preferred_username when it exists, otherwise from name.

3- Assign a User to the LinkAce Application

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

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

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

4- Configuration Single Sign-On for LinkAce

As we mentioned at the start, please check out the LinkAce documentation first. LinkAce is configured with environment variables in its .env file. Add the following variables and replace the placeholder values.

Bash

APP_URL=https://<linkace-host-name>
SSO_ENABLED=true
SSO_OIDC_ENABLED=true
SSO_OIDC_BASE_URL=https://<monosign-host>
SSO_OIDC_CLIENT_ID=<client-id>
SSO_OIDC_CLIENT_SECRET=<client-secret>

Variable	Value	Description
APP_URL	`https://<linkace-host-name>`	Public HTTPS address of LinkAce. The redirect address that is sent to Monosign is built from it, so it must match the Allowed Redirect URI of step 2.
SSO_ENABLED	`true`	Turns the single sign-on on. The login page then shows the SSO buttons next to the local login.
SSO_OIDC_ENABLED	`true`	Turns the generic OIDC provider on. The button is shown as OIDC.
SSO_OIDC_BASE_URL	`https://<monosign-host>`	Address of Monosign without `/.well-known/openid-configuration`.
SSO_OIDC_CLIENT_ID / SSO_OIDC_CLIENT_SECRET	Client Id / Client Secret	Copied from the Monosign OIDC/OpenID Access Key Details created in the first step.
SSO_OIDC_SCOPES	Optional	Additional scopes, separated by space. The default scopes are `openid email profile`.
SSO_OIDC_VERIFY_JWT	`true` (default)	Verifies the signature of the ID token with the keys (JWKS) of Monosign.
SSO_REGISTRATION_ENABLED	`true` (default)	When `true`, a new account is created at the first sign-in. When `false`, only users that already exist in LinkAce can sign in with SSO.
SSO_REQUIRE_VERIFIED_EMAIL	`false` (default)	When `true`, the sign-in is refused if the identity provider does not send the claim `email_verified` as true.
REGULAR_LOGIN_DISABLED / SSO_AUTO_REDIRECT	`false` (default)	Optional. The local e-mail and password login stays available next to Monosign. Set `REGULAR_LOGIN_DISABLED=true` to allow the single sign-on only; together with `SSO_AUTO_REDIRECT=true` the login page sends the user directly to Monosign.

An account is matched with the identity of the provider. If a local account with the same e-mail address exists and is not linked to an SSO provider yet, it is linked at the first SSO sign-in. An account that is already linked to another SSO provider cannot sign in with OIDC.

LinkAce also needs the basic variables of every installation. In the Docker deployment that was used for this document, the .env file contains them:

Bash

APP_KEY=base64:<random-32-byte-key>
TRUSTED_PROXIES=*
DB_CONNECTION=sqlite
DB_DATABASE=/app/database/database.sqlite

Generate the key for example with openssl rand -base64 32 and write it after base64:. Set TRUSTED_PROXIES to the address of your reverse proxy if you want to restrict it.

The .env file contains the client secret and the key 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 and an SQLite database. The optional MariaDB, Redis and Meilisearch services of the official production Compose file are not used. The container runs as a non-root user, so the web server listens on port 8080 and only the capability to bind a port is added back after dropping all capabilities.

YAML

services:
  app:
    image: docker.io/linkace/linkace:v2.6.2
    restart: unless-stopped
    ports:
      - "6277:8080"
    environment:
      PORT: "8080"
    volumes:
      - ./.env:/app/.env
      - ./database.sqlite:/app/database/database.sqlite
    cap_drop:
      - ALL
    cap_add:
      - NET_BIND_SERVICE
    security_opt:
      - no-new-privileges:true

Create the empty database file and give the container user (UID 82) the ownership of the two mounted files before the first start:

Bash

touch database.sqlite
chown 82:82 .env database.sqlite
chmod 600 .env
docker compose up -d

Then prepare the database and create the first administrator with the command line (instead of the web installer):

Bash

docker compose exec app php artisan migrate --force
docker compose exec app php artisan setup:complete
docker compose exec app php artisan registeruser <user-name> <e-mail-address> <password> --admin

When LinkAce is behind a reverse proxy, the proxy must send the header X-Forwarded-Proto: https and forward the host name of APP_URL. After changing the .env file, recreate the container so that the new variables are loaded:

Bash

docker compose up -d --force-recreate app

Create the local administrator account before turning on the single sign-on. Accounts that are created through Monosign are normal users, not administrators.

Now try to log in to LinkAce using Monosign SSO.

Open a new browser window (or a private window) and type the LinkAce address. The login page of LinkAce shows the e-mail and password form and, below it, the OIDC button. When the regular login is disabled together with SSO_AUTO_REDIRECT=true, LinkAce redirects the browser directly to Monosign. If the Url of the Monosign application is set as described in step 1, opening LinkAce from the Monosign portal also starts the sign-in directly.

Click 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.

Monosign sign-in page of the LinkAce application

After the sign-in Monosign redirects the browser back to LinkAce (/auth/sso/oidc/callback). At the first sign-in LinkAce creates the account with the name and the e-mail address from Monosign and signs the user in. The account settings of LinkAce show the e-mail address that comes from Monosign.

Troubleshooting

Symptom	Cause	Solution
The OIDC button is not shown	`SSO_ENABLED` or `SSO_OIDC_ENABLED` is not `true`, or the container was not recreated after the change.	Set both variables (step 4) and run `docker compose up -d --force-recreate app`.
Monosign shows a redirect URI error	The redirect address that LinkAce sends does not exactly match the Allowed Redirect URIs, for example because `APP_URL` is wrong, or the address was entered in another field such as Resource.	Add `https://<linkace-address>/auth/sso/oidc/callback` to Allowed Redirect URIs in Monosign (step 2) and set `APP_URL` to the same public HTTPS address.
Error 403: the selected SSO provider is not available	The provider is not enabled in the environment.	Set `SSO_ENABLED=true` and `SSO_OIDC_ENABLED=true`.
Error 403: no existing user found for this provider	`SSO_REGISTRATION_ENABLED=false` is set and the user does not exist in LinkAce.	Create the user in LinkAce first, or remove the variable.
Error 403: the provider did not confirm the e-mail address	`SSO_REQUIRE_VERIFIED_EMAIL=true` is set, but the identity provider did not send `email_verified` as true.	Remove the variable or make the identity provider return the verified e-mail claim.
Error 403: unable to login with OIDC, please use another provider	The account is already linked to another SSO provider.	Sign in with the provider that is shown in the message, or ask an administrator to fix the account.
LinkAce cannot reach Monosign, or the ID token cannot be verified	The container cannot resolve or trust the address of Monosign, or `SSO_OIDC_BASE_URL` contains the `/.well-known` part.	Check `SSO_OIDC_BASE_URL`, the DNS and firewall rules of the LinkAce host and that the certificate of Monosign is issued by a trusted CA. Read the LinkAce container log.
HTTP error 400 when LinkAce is opened by an IP address	The request was sent with a host name that is not the one in `APP_URL`.	Open LinkAce with the host name that is set in `APP_URL`, and let the reverse proxy forward it.
The web server does not start (log message about not being able to execute `caddy`)	All capabilities were dropped, but the web server binary needs the capability to bind a port.	Add back `NET_BIND_SERVICE` as in the Compose file above.
SAML sign-in is required	LinkAce supports OpenID Connect and OAuth providers, not SAML.	Use the OIDC integration in this document.

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

4- Configuration Single Sign-On for LinkAce

5- Sign In Test

Troubleshooting