Flowctl OIDC Integration

This document explains how to implement Monosign with Flowctl, the open-source workflow automation platform. It covers Single Sign-On with OpenID Connect (OIDC), which is built into Flowctl. Flowctl 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 Flowctl documentation (Access Control, OIDC Authentication).

This configuration is done with the Flowctl Docker image (ghcr.io/cvhariharan/flowctl:latest, October 2026) and postgres:17 running on Docker Compose. If your Flowctl version or deployment type is different, please check the Flowctl documentation.

Flowctl supports OpenID Connect only. SAML is not available in Flowctl. There is no single sign-on screen in the Flowctl interface; the provider is defined in the config.toml file (or with environment variables).

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

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

Flowctl 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	`Flowctl`	Name of the application shown to users on the Monosign portal and on the Monosign sign-in page.
Type	`Web`	Flowctl is accessed through a web browser. Options: Web, Mobile, Desktop, API.
Url	Optional	Leave empty or enter the Flowctl address so users can open the application from their Monosign portal (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). Flowctl needs the e-mail address and the name of the user.

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

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

Monosign value	Example	Used in Flowctl as
Client Id	`<client-id>`	`client_id`
Client Secret	`<client-secret>`	`client_secret`
Issuer (Configuration Url without the `.well-known/openid-configuration` part)	`https://<monosign-host>/`	`issuer`. Flowctl adds `.well-known/openid-configuration` itself and reads the Auth, Token and JWKS addresses from it.

2- Configuring the OIDC/OpenID Settings on Monosign

Open the key with the Configure button, go to OIDC/OpenID Settings, enter the scopes that Flowctl requests and add the callback address of Flowctl to Allowed Redirect URIs.

Property	Value	Description
Scope	`openid` `profile` `email`	The scopes that Flowctl sends in the authorization request. Add each scope separated by space.
Allowed Redirect URIs	`https://<flowctl-address>/auth/callback`	The address where Monosign sends the user back after sign-in. The path `/auth/callback` is fixed by Flowctl. Use the public (HTTPS) address of Flowctl; the host name must be the same as the one users type in the browser and the same as `root_url` of Flowctl.
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.

Flowctl identifies the user with the email claim of the ID token and uses the name claim as the display name. Monosign returns both claims by default, so a claim mapping is not required. The e-mail address of the Monosign user must be the same as the user name of the user in Flowctl.

3- Assign a User to the Flowctl Application

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

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

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

Assign a User dialog (1: select the users, set the Expiration Date)

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

4- Configuration Single Sign-On for Flowctl

As we mentioned at the start, please check out the Flowctl documentation first. Flowctl reads the single sign-on provider from the [[oidc]] section of its config.toml file (the same keys can be given with environment variables that start with FLOWCTL_OIDC__). In the Docker Compose deployment create the file next to the compose file, mount it to /app/config.toml and replace the placeholder values.

[[oidc]]
name = "monosign"
label = "Monosign"
client_id = "<client-id>"
client_secret = "<client-secret>"
issuer = "https://<monosign-host>/"
auto_create_users.enabled = true
auto_create_users.namespace = "default"
auto_create_users.role = "user"
auto_create_users.allowed_domains = ["<your-e-mail-domain>"]

Option	Value	Description
name	`monosign`	Name of the provider. It may contain only letters. It is part of the sign-in address (`/login/oidc/monosign`).
label	`Monosign`	Text of the button on the sign-in page.
client_id / client_secret	Client Id / Client Secret	Copied from the Monosign OIDC/OpenID Access Key Details created in the first step.
issuer	`https://<monosign-host>/`	Issuer address of Monosign. Flowctl compares it with the issuer of the discovery document, so it must be exactly the same, including the trailing slash.
auto_create_users.enabled	`true`	Creates the user in Flowctl at the first sign-in. When it is `false` (default), the user must already exist in Flowctl with the e-mail address as the user name.
auto_create_users.namespace / role / groups	`default` / `user`	Namespace and role of the new user (`user`, `operator`, `reviewer`, `admin`), and optionally the groups to add the user to.
auto_create_users.allowed_domains	Your e-mail domain	Only e-mail addresses of these domains can create an account. If it is empty, every user who can sign in at Monosign gets an account.
redirect_url	Not set	Optional. By default it is `root_url` + `/auth/callback`, so `root_url` must be the public HTTPS address of Flowctl.

The role of the new user is set by auto_create_users.role; Flowctl does not read a role or group claim from Monosign. Only the built-in admin user can sign in with a user name and password (the other users must use single sign-on). Change the role of a user on the Members page of Flowctl with the administrator account.

Flowctl reads the other required settings (database, root_url, scheduler, logger) from the environment of the official compose file. When Flowctl has neither a configuration file nor these environment variables, it stops at the start with a validation error. Set FLOWCTL_APP__ROOT_URL to the public address, for example https://<flowctl-address>.

The official Flowctl compose file also mounts the Docker socket (/var/run/docker.sock) so that flows can run in Docker containers. The single sign-on does not need it. Anyone who can run a flow with the Docker executor can control the Docker host, so do not mount the socket unless you need the Docker executor and restrict who can run flows.

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

The Flowctl image is based on Debian and does not contain the trusted CA certificate bundle. Flowctl cannot verify the certificate of Monosign without it and skips the provider (see the Troubleshooting table). Mount the CA bundle of the host to the container (read-only), then recreate the container:

YAML

  flowctl:
    image: ghcr.io/cvhariharan/flowctl:latest
    volumes:
      - ./config.toml:/app/config.toml:ro
      - /etc/ssl/certs/ca-certificates.crt:/etc/ssl/certs/ca-certificates.crt:ro

Bash

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

The sign-in page must now show the user name and password form and the Monosign button.

Now try to log in to Flowctl using Monosign SSO.

Open a new browser window (or a private window) and type the Flowctl address. The sign-in page shows the user name and password form and the Monosign button.

Flowctl sign-in page with the Monosign button

Click Monosign. Flowctl redirects the browser to the Monosign sign-in page of the Flowctl 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 Flowctl (/auth/callback). Flowctl creates the user on the first sign-in with the role User and opens the Flows page. The signed-in user is shown at the bottom left.

User logged in to Flowctl through Monosign SSO (Flows page and the user menu)

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

Troubleshooting

Symptom	Cause	Solution
The Monosign button is not shown, and the log contains `skipping oidc provider initialization` with `x509: certificate signed by unknown authority`	The Flowctl container has no trusted CA certificates and cannot verify the certificate of Monosign.	Mount `/etc/ssl/certs/ca-certificates.crt` of the host to the container (step 4) and recreate it. Do not disable the certificate verification.
The button is not shown, and the log contains `skipping oidc provider initialization` with another error	The `issuer` is not exactly the issuer of the discovery document, or Monosign cannot be reached from the container.	Use the `issuer` value of `https://<monosign-host>/.well-known/openid-configuration` exactly as it is (with the trailing slash) and check the DNS and firewall rules of the Flowctl host.
Flowctl stops at the start with `config validation failed`	Required settings are missing, or the `[[oidc]]` section has an empty `client_id`, `client_secret` or `issuer`.	Set the scheduler, logger and database variables of the official compose file and fill in all required `[[oidc]]` values.
Monosign shows a redirect URI error	The redirect URI that Flowctl sends does not exactly match the Allowed Redirect URIs.	Add `https://<flowctl-address>/auth/callback` in Monosign (step 2). The host name must be the same as `root_url`.
The sign-in at Monosign succeeded, but Flowctl does not let the user in	The user does not exist in Flowctl and `auto_create_users` is not enabled, or the e-mail domain is not in `allowed_domains`.	Enable `auto_create_users`, add the domain to `allowed_domains`, or create the user in Flowctl first with the e-mail address as the user name.
A user gets an account without the permissions that are needed	New users get the role set in `auto_create_users.role`.	Change the role on the Members page with the administrator account or set another role in the configuration.
A user cannot sign in	The user is not assigned to the application.	Assign the user in step 3.
The user name and password of a normal user are refused	Only the built-in administrator can use the password; all other users must use single sign-on.	Use the Monosign button.
SAML sign-in is required	Flowctl supports OpenID Connect only.	Use the OIDC integration in this document.

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