Cronmaster OIDC Integration

This document explains how to implement Monosign with Cronmaster (Cr*nMaster), the open-source web interface to manage and schedule cron jobs. It covers Single Sign-On with OpenID Connect (OIDC), which is built into Cronmaster. Cronmaster discovers the Monosign addresses from the OIDC discovery document, so the OIDC/OpenID access key of Monosign is used. Before you continue, it is better to start with the Cronmaster SSO guide.

This configuration is done with Cronmaster 2.4.0 running on Docker Compose (image ghcr.io/fccview/cronmaster:latest). If your Cronmaster version or deployment type is different, please check the Cronmaster documentation.

Cronmaster supports OpenID Connect only. SAML is not available in Cronmaster. There is no single sign-on screen in the Cronmaster interface; it is configured with environment variables.

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

The official Cronmaster compose file starts the container with privileged: true, pid: host, user: root and the Docker socket, because the Run now button enters the host as root and edits the host crontab. Anyone who signs in to Cronmaster in this mode can run commands as root on the host. Allow only a few trusted administrators in Monosign (Only Assigned Users). For a test, or if you need only the sign-in, start the container without these privileges (see step 4); the single sign-on works the same, but the host cron jobs cannot be managed.

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

Cronmaster 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	`Cronmaster`	Name of the application shown to users on the Monosign portal and on the Monosign sign-in page.
Type	`Web`	Cronmaster is accessed through a web browser. Options: Web, Mobile, Desktop, API.
Url	Optional	Leave empty or enter `https://<cronmaster-address>/api/oidc/login` so users can open Cronmaster directly from their Monosign portal and are signed in without clicking the SSO button (see the note in 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).

Cronmaster lets every user who can sign in at the identity provider use the application, and it has no roles. 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 Cronmaster 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 Cronmaster application are provided as follows:

Monosign value	Example	Used in Cronmaster as
Client Id	`<client-id>`	`OIDC_CLIENT_ID`
Client Secret	`<client-secret>`	`OIDC_CLIENT_SECRET` (optional, switches Cronmaster to the confidential client mode)
Issuer (Configuration Url without the `.well-known/openid-configuration` part)	`https://<monosign-host>/`	`OIDC_ISSUER`. Cronmaster adds `.well-known/openid-configuration` itself and reads the Auth, Token, UserInfo and JWKS addresses from it.

2- Configuring the OIDC/OpenID Settings on Monosign

Click the Configure button of the OpenID Connect (OIDC) key to open the OIDC/OpenID settings.

Opening the OIDC/OpenID key configuration (1: Configure)

In OIDC/OpenID Settings add the callback address of Cronmaster to Allowed Redirect URIs.

OIDC/OpenID Settings (1: Allowed Redirect URIs)

Property	Value	Description
Allowed Redirect URIs	`https://<cronmaster-address>/api/oidc/callback`	The address where Monosign sends the user back after sign-in. The path `/api/oidc/callback` is fixed by Cronmaster. It must start with `https://` and match the `APP_URL` of step 4 exactly; 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. Cronmaster sends the scope itself (`openid profile email`).
Token lifetimes, CORS	Empty	Default values are used.

Cronmaster validates the ID token (signature, issuer, audience, nonce) and reads the user information from the standard claims, which Monosign returns by default. A claim mapping is not required.

To let the user return to the Cronmaster sign-in page after signing out, add the address of the page to the Allowed Redirect Urls for Logout. Open the application with Edit.

On the Login tab enter the address and click Save.

Login tab of the application (1: Login tab, 2: Allowed Redirect Urls for Logout)

Property	Value	Description
Allowed Redirect Urls for Logout	`https://<cronmaster-address>/login`	When the user signs out, Cronmaster asks Monosign to end the session and to send the browser back to its sign-in page. Monosign accepts only the addresses that are listed here.
Login Url, Login Callback Url	Empty	Not used. The sign-in is started by Cronmaster.

3- Assign a User to the Cronmaster Application

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

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

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

4- Configuration Single Sign-On for Cronmaster

As we mentioned at the start, please check out the Cronmaster documentation first. Cronmaster is configured with environment variables. In the Docker Compose deployment add the following variables to the environment of the cronmaster service (directly or with an env_file) and replace the placeholder values.

Bash

APP_URL=https://<cronmaster-host-name>
HTTPS=true
INTERNAL_API_URL=http://localhost:3000
SSO_MODE=oidc
OIDC_ISSUER=https://<monosign-host>/
OIDC_CLIENT_ID=<client-id>
OIDC_CLIENT_SECRET=<client-secret>
OIDC_GROUPS_SCOPE=no
AUTH_PASSWORD=<local-password>

Variable	Value	Description
SSO_MODE	`oidc`	Enables the OpenID Connect login.
OIDC_ISSUER	`https://<monosign-host>/`	Issuer address of Monosign. Cronmaster compares the issuer of the ID token with this value, so it must be exactly the `issuer` of the discovery document, including the trailing slash.
OIDC_CLIENT_ID / OIDC_CLIENT_SECRET	Client Id / Client Secret	Copied from the Monosign OIDC/OpenID Access Key Details created in the first step. When the secret is set, Cronmaster uses it instead of PKCE (confidential client). If you leave it out, Cronmaster works as a public client with PKCE.
APP_URL	`https://<cronmaster-host-name>`	Public address of Cronmaster. It is used to build the redirect address (`APP_URL/api/oidc/callback`), so it must match the Allowed Redirect URI in Monosign.
HTTPS	`true`	Marks the session cookie as secure (`__Host-` prefix). Set it when users reach Cronmaster over HTTPS, for example behind a reverse proxy.
INTERNAL_API_URL	`http://localhost:3000`	Cronmaster validates the session with an internal request. Behind a reverse proxy this request can be blocked with `403`, so it is sent to the container itself.
OIDC_GROUPS_SCOPE	`no`	Cronmaster requests a `groups` scope by default. Monosign does not provide it, so it is turned off to avoid an invalid scope error.
AUTH_PASSWORD	Local password	Optional. Keeps the local password login next to the “Sign in with SSO” button. Remove the variable to allow only the single sign-on.
OIDC_USER_GROUPS / OIDC_USER_ROLES	Not set	Optional. Allow only users with these groups or roles in the token. They are not used here, because the access is limited with Only Assigned Users in Monosign.

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

If you only need the sign-in and not the management of the host cron jobs, remove privileged, pid: host, user: root and the Docker socket from the compose file and harden the container:

YAML

services:
  cronmaster:
    image: ghcr.io/fccview/cronmaster:latest
    ports:
      - "40123:3000"
    env_file:
      - .env
    volumes:
      - ./scripts:/app/scripts
      - ./data:/app/data
      - ./snippets:/app/snippets
    cap_drop:
      - ALL
    security_opt:
      - no-new-privileges:true
    restart: always

The container runs as the non-root user of the image (UID 1001), so the scripts, data and snippets folders must be writable by this user (for example chown -R 1001:1001 scripts data snippets). Recreate the container so that the new variables are loaded:

Bash

cd <cronmaster-compose-directory>
docker compose up -d --force-recreate

The sign-in page must now show the password field and the “Sign in with SSO” button.

Now try to log in to Cronmaster using Monosign SSO.

Open a new browser window (or a private window) and type the Cronmaster address. The sign-in page shows the password field and the Sign in with SSO button.

Cronmaster sign-in page with the “Sign in with SSO” button

Click Sign in with SSO. Cronmaster redirects the browser to the Monosign sign-in page of the Cronmaster 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 Cronmaster (/api/oidc/callback) and Cronmaster opens the dashboard.

User logged in to Cronmaster through Monosign SSO (Cronmaster dashboard)

The sign-in of Cronmaster is started with a simple address (/api/oidc/login), so Monosign can start it directly. If you enter https://<cronmaster-address>/api/oidc/login as the Url of the application (step 1), the user who opens Cronmaster from the Monosign portal is redirected to the Monosign sign-in without clicking the SSO button (IdP-initiated sign-in).

Troubleshooting

Symptom	Cause	Solution
The “Sign in with SSO” button is not shown	`SSO_MODE=oidc` is not set, or the container was not recreated.	Set the variables and run `docker compose up -d --force-recreate`.
Monosign shows a redirect URI error	The redirect URI that Cronmaster sends does not exactly match the Allowed Redirect URIs.	Add `https://<cronmaster-address>/api/oidc/callback` in Monosign (step 2). It must include `https://` and the same host name as `APP_URL`.
The sign-in at Monosign succeeded, but Cronmaster returns to the sign-in page (redirect loop, logs show `403`)	The session check goes through the reverse proxy and is blocked, or `APP_URL` does not match the public address.	Set `INTERNAL_API_URL=http://localhost:3000` and check that `APP_URL` is exactly the public address. Set `DEBUGGER=true` to see the OIDC flow in the logs.
Cronmaster reports an authentication or issuer error after returning from Monosign	`OIDC_ISSUER` is not exactly the issuer of the discovery document (for example the trailing slash is missing).	Use the `issuer` value of `https://<monosign-host>/.well-known/openid-configuration` exactly as it is.
“Invalid scope” error	Cronmaster requests the `groups` scope, which Monosign does not provide.	Set `OIDC_GROUPS_SCOPE=no`.
“Nonce mismatch” or the login starts again	The browser blocks or clears the cookies of Cronmaster.	Test in a new private window and allow cookies. With `HTTPS=true` the address must be opened with `https://`.
“JWKS fetch failed” in the logs	The container cannot reach the Monosign address.	Check DNS and firewall rules of the Cronmaster host and open `https://<monosign-host>/.well-known/jwks` from the container.
A user cannot sign in	The user is not assigned to the application.	Assign the user in step 3.
After Sign Out the browser does not return to the Cronmaster sign-in page	The sign-in page address is not listed in Allowed Redirect Urls for Logout.	Add `https://<cronmaster-address>/login` on the Login tab of the application (step 2).
Cronmaster cannot write its data (errors about `data` or `sessions.json`)	The container runs as UID 1001 and the mounted folders belong to another user.	Run `chown -R 1001:1001 scripts data snippets` and recreate the container.
SAML sign-in is required	Cronmaster supports OpenID Connect only.	Use the OIDC integration in this document.

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