One Time Secret OIDC Integration

This document explains how to implement Monosign with Onetime Secret, the open-source, self-hosted service to share passwords and other sensitive text with a link that can be opened only once. It covers Single Sign-On with OpenID Connect (OIDC), which is built into Onetime Secret. Onetime Secret reads the Monosign addresses from the OIDC discovery document and uses the Authorization Code flow with PKCE, so the OIDC/OpenID access key of Monosign is used. Before you continue, it is better to read the Onetime Secret documentation (opens in a new tab).

This configuration is done with Onetime Secret 0.26.19 running on Docker (image onetimesecret/onetimesecret:v0.26.19) with Valkey (Redis compatible) and the SQLite authentication database. If your version or deployment type is different, please check the Onetime Secret documentation.

Onetime Secret supports a generic OIDC provider, ready-made Microsoft Entra ID, Google, GitHub, GitLab and Apple providers, and SAML 2.0. There is no single sign-on screen in the Onetime Secret interface; the provider is configured with environment variables. Single sign-on works only in the full authentication mode (AUTHENTICATION_MODE=full) with a SQL database for the accounts.

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

Onetime Secret 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 Onetime Secret application
Configuration Single Sign-On for Onetime Secret
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.

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

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

Property	Value	Description
Name	`Onetime Secret`	Name of the application shown to users on the Monosign portal and on the Monosign sign-in page.
Type	`Web`	Onetime Secret is accessed through a web browser. Options: Web, Mobile, Desktop, API.
Url	Optional	Leave empty or enter the Onetime Secret address (for example `https://<ots-address>`). The sign-in is started from the Onetime Secret sign-in page with the Sign in with Monosign button (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.

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). Onetime Secret needs the e-mail address of the user.

Onetime Secret creates an account for every Monosign user who signs in for the first time (a nonblank e-mail address is required). 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.

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

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 Onetime Secret application are provided as follows:

Monosign value	Example	Used in Onetime Secret as
Client Id	`<client-id>`	`OIDC_CLIENT_ID`
Client Secret	`<client-secret>`	`OIDC_CLIENT_SECRET`
Configuration Url	`https://<monosign-host>/.well-known/openid-configuration`	`OIDC_ISSUER`. Onetime Secret needs the address without the `.well-known/openid-configuration` part, as the issuer, for example `https://<monosign-host>/`. Keep the slash at the end, because the issuer of Monosign has it.

2- Configuring the OIDC/OpenID Settings on Monosign

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

Add the callback address of Onetime Secret to Allowed Redirect URIs, then press Update.

Property	Value	Description
Allowed Redirect URIs	`https://<ots-address>/auth/sso/oidc/callback`	The address where Monosign sends the user back after sign-in. The path `/auth/sso/oidc/callback` is built by Onetime Secret from the provider route name `oidc` and the host of the request. Use the public (HTTPS) address of Onetime Secret.
Scope	Optional	Onetime Secret sends the scopes `openid`, `email` and `profile` in the authorization request by itself, so the field can stay empty.
Other fields	Empty / default	The other fields (Signing Key, Issuer, Audience, Resource, token lifetimes, CORS, Initiate Login Url) are not needed. Do not enter the callback address in the Resource field.

Onetime Secret needs the email claim of the user to create the account. Monosign returns the claim email by default, so a claim mapping is not required.

3- Assign a User to the Onetime Secret Application

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

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

4- Configuration Single Sign-On for Onetime Secret

As we mentioned at the start, please check out the Onetime Secret documentation first (installation, secrets and the authentication mode are described there). Single sign-on is configured with environment variables. Add the following variables to the environment of the Onetime Secret container and replace the placeholder values.

HOST=<ots-host-name>
SSL=true
AUTHENTICATION_MODE=full
AUTH_DATABASE_URL=sqlite://data/auth.db
AUTH_SSO_ENABLED=true
OIDC_ISSUER=https://<monosign-host>/
OIDC_CLIENT_ID=<client-id>
OIDC_CLIENT_SECRET=<client-secret>
OIDC_DISPLAY_NAME=Monosign

Variable	Value	Description
HOST / SSL	`<ots-host-name>` / `true`	Public host name of Onetime Secret and the HTTPS setting. The links and the redirect address are built from them.
AUTHENTICATION_MODE	`full`	Required for single sign-on. The default `simple` mode has no SSO.
AUTH_DATABASE_URL	`sqlite://data/auth.db`	SQL database of the accounts. SQLite is enough for a test; use PostgreSQL in production.
AUTH_SSO_ENABLED	`true`	Master switch of the single sign-on. It must be `true` for any provider.
OIDC_ISSUER	`https://<monosign-host>/`	Issuer of Monosign. Onetime Secret reads `.well-known/openid-configuration` below this address and validates the tokens with it, so keep the slash at the end. Required.
OIDC_CLIENT_ID / OIDC_CLIENT_SECRET	Client Id / Client Secret	Copied from the Monosign OIDC/OpenID Access Key Details created in the first step.
OIDC_DISPLAY_NAME	`Monosign`	Name on the sign-in button (Sign in with Monosign). Default: SSO.
ALLOWED_SIGNUP_DOMAIN	Optional	Comma separated e-mail domains that can sign up, for example `company.com`.
OIDC_TRUST_EMAIL_FOR_LINKING	`false` (default)	Optional. By default an existing local account with the same e-mail address is not linked automatically; the user must prove the password of the account or the mailbox.

The environment file contains the client secret and the secrets of the application. Restrict its permissions (for example chmod 600) and do not store it in a shared repository. After changing the environment, recreate the container so that the new variables are loaded: docker compose up -d --force-recreate app. Behind a reverse proxy that terminates TLS also set SESSION_COOKIE_SECURE=true; the proxy must send the header X-Forwarded-Proto: https and forward the host name of HOST.

Installation (for reference only). The installation of Onetime Secret itself is described in its documentation. For this document it was installed with Docker Compose (Onetime Secret and Valkey) as below. In the full mode the application also needs the random secrets SECRET, SESSION_SECRET, AUTH_SECRET, ACCOUNT_ID_SECRET, ARGON2_SECRET, FEDERATION_SECRET, IDENTIFIER_SECRET and VALKEY_PASSWORD (for example from openssl rand -hex 32), and the folder of the SQLite database must belong to the container user (chown -R 1001:1001 data).

services:
  app:
    image: onetimesecret/onetimesecret:v0.26.19
    restart: unless-stopped
    depends_on:
      valkey:
        condition: service_healthy
    env_file: .env
    environment:
      - RACK_ENV=production
      - VALKEY_URL=redis://:${VALKEY_PASSWORD}@valkey:6379/0
    entrypoint: ['./bin/entrypoint.sh']
    ports:
      - "6278:3000"
    volumes:
      - ./data:/app/data
    cap_drop:
      - ALL
    security_opt:
      - no-new-privileges:true
  valkey:
    image: valkey/valkey:8.1-bookworm
    restart: unless-stopped
    environment:
      - REDISCLI_AUTH=${VALKEY_PASSWORD}
    command: >
      valkey-server --appendonly yes --appendfilename onetime.aof
      --appendfsync everysec --dbfilename onetime.rdb --save 157680000 1
      --bind 0.0.0.0 --port 6379 --requirepass ${VALKEY_PASSWORD}
      --databases 1 --timeout 30 --loglevel notice
    expose:
      - "6379"
    volumes:
      - ./valkey:/data
    healthcheck:
      test: ['CMD', 'valkey-cli', 'ping']
      interval: 10s
      timeout: 3s
      retries: 3
    cap_drop:
      - ALL
    cap_add:
      - CHOWN
      - SETUID
      - SETGID
    security_opt:
      - no-new-privileges:true

5- Sign In Test

Now try to log in to Onetime Secret using Monosign SSO.

Open a new browser window (or a private window) and type the Onetime Secret address and open the sign-in page. The page shows the e-mail and password form and, below it, the Sign in with Monosign button.

Click the button. 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 Onetime Secret (/auth/sso/oidc/callback). At the first sign-in Onetime Secret creates the account with the e-mail address from Monosign and opens the page to create a secret link. The account menu in the upper right corner shows the e-mail address from Monosign.

Troubleshooting

Symptom	Cause	Solution
The Sign in with Monosign button is not shown	`AUTHENTICATION_MODE` is not `full`, `AUTH_SSO_ENABLED` is not `true`, `OIDC_ISSUER` or `OIDC_CLIENT_ID` is not set, or the container was not recreated after the change.	Set the variables (step 4) and recreate the container.
Monosign shows a redirect URI error	The redirect address that Onetime Secret sends does not exactly match the Allowed Redirect URIs, for example because `HOST` or `SSL` is wrong, the proxy does not send `X-Forwarded-Proto: https` so the address starts with `http://`, or the address was entered in another field such as Resource.	Add `https://<ots-address>/auth/sso/oidc/callback` to Allowed Redirect URIs in Monosign (step 2) and set `HOST`, `SSL` and the proxy headers as in step 4.
An error page appears after returning from Monosign	The Client Id or Client Secret is wrong, the issuer does not match (the slash at the end is missing), or the container cannot reach Monosign.	Copy the values again from the Monosign access key (step 1), use the issuer with the slash at the end and read the container log. Check the DNS and firewall rules of the Onetime Secret host.
The sign-in is redirected to `/signin?auth_error=account_exists_link_required`	A local account with the same e-mail address exists and is not linked to Monosign yet.	Sign in with the existing method and link Monosign in Security settings → Connected identities, or follow the password or mailbox proof that Onetime Secret offers.
A user cannot sign in	The user is not assigned to the application.	Assign the user in step 3.
SAML sign-in is required	This document covers OpenID Connect. Onetime Secret also supports SAML 2.0 when `SAML_ENABLED=true` is set.	Use the OIDC integration in this document, or the SAML 2.0 documentation.

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