Olivetin OAuth2 Integration

This document explains how to implement Monosign with OliveTin, the open-source web interface that runs predefined shell commands as buttons. It covers Single Sign-On with OAuth 2.0, which is built into OliveTin. OliveTin uses the Authorization Code flow and reads the user name from the user information endpoint, so the OIDC/OpenID access key of Monosign is used as an OAuth 2.0 provider. Before you continue, it is better to start with the OliveTin OAuth2 documentation.

This configuration is done with OliveTin 3000.20.0 running on Docker Compose (image jamesread/olivetin). If your OliveTin version or deployment type is different, please check the OliveTin documentation.

OliveTin supports OAuth 2.0 only. It does not validate an ID token (no issuer or nonce check) and SAML is not available. There is no single sign-on screen in the OliveTin interface; the provider is defined in the config.yaml file.

Monofor has no responsibility to do OliveTin configurations. If you need support please contact the OliveTin community or your OliveTin 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 OliveTin application
Configuration Single Sign-On for OliveTin
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)

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

Every user who can sign in to OliveTin through Monosign can run the buttons that are allowed to the group in step 4. 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 Olivetin 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 Olivetin application are provided as follows:

Monosign value	Example	Used in OliveTin as
Client Id	`<client-id>`	`clientId`
Client Secret	`<client-secret>`	`clientSecret`
Auth Url	`https://<monosign-host>/openid/authorize`	`authUrl`
Access Token Url	`https://<monosign-host>/openid/token`	`tokenUrl`
User Info Url	`https://<monosign-host>/openid/userinfo`	`whoamiUrl`. OliveTin reads the user name from this address with the access token.

2- Configuring the OIDC/OpenID Settings on Monosign

Click the Configure button of the OpenID Connect (OIDC) key to open the OIDC/OpenID settings and add the callback address of OliveTin to Allowed Redirect URIs.

OIDC/OpenID Settings (1: Allowed Redirect URIs)

Property	Value	Description
Allowed Redirect URIs	`https://<olivetin-address>/oauth/callback`	The address where Monosign sends the user back after sign-in. The path `/oauth/callback` is fixed by OliveTin (it says `oauth`, not `oauth2`). Use the public (HTTPS) address of OliveTin; the host name must be the same as the one users type in the browser and the same as `authOAuth2RedirectUrl` of step 4.
Scope, Signing Key / Key Id / Password, Issuer, Audience, Resource	Empty	Optional custom JWT settings. They are not needed. OliveTin sends the scopes itself (`openid profile email`).
Token lifetimes, CORS	Empty	Default values are used.

OliveTin takes the user name from the email field of the UserInfo response. Monosign returns it by default, so a claim mapping is not required. If you want another field as the user name, add it on the Claim Mapping tab, click Update and set usernameField in OliveTin.

3- Assign a User to the OliveTin Application

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

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

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

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

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

4- Configuration Single Sign-On for OliveTin

As we mentioned at the start, please check out the OliveTin documentation first. OliveTin is configured with the config.yaml file (in the Docker image it is in the /config folder). Add the following lines to the file and replace the placeholder values.

YAML

authRequireGuestsToLogin: true
authOAuth2RedirectUrl: https://<olivetin-address>/oauth/callback
authOAuth2Providers:
  monosign:
    title: Monosign
    clientId: <client-id>
    clientSecret: <client-secret>
    authUrl: https://<monosign-host>/openid/authorize
    tokenUrl: https://<monosign-host>/openid/token
    whoamiUrl: https://<monosign-host>/openid/userinfo
    usernameField: email
    scopes:
      - openid
      - profile
      - email
    addToUsergroup: monosign
    certBundlePath: /certs/ca-certificates.crt

defaultPermissions:
  view: false
  exec: false
  logs: false
  kill: false

accessControlLists:
  - name: monosign-users
    matchUsergroups:
      - monosign
    addToEveryAction: true
    permissions:
      view: true
      exec: true
      logs: true

Option	Value	Description
authOAuth2RedirectUrl	`https://<olivetin-address>/oauth/callback`	Public callback address of OliveTin. It must match the Allowed Redirect URI in Monosign exactly.
authOAuth2Providers.monosign	Provider definition	The key (`monosign`) is the name of the provider and it is used in the sign-in address (`/oauth/login?provider=monosign`). `title` is the text of the button.
clientId / clientSecret	Client Id / Client Secret	Copied from the Monosign OIDC/OpenID Access Key Details created in the first step.
authUrl / tokenUrl / whoamiUrl	Monosign addresses	Auth Url, Access Token Url and User Info Url of the Monosign access key. OliveTin does not use the discovery document, so the three addresses must be written.
usernameField	`email`	The field of the UserInfo response that is used as the user name.
scopes	`openid`, `profile`, `email`	Scopes that OliveTin requests.
addToUsergroup	`monosign`	Adds this user group to every user who signs in with this provider. Monosign does not send a group claim here, so the fixed group is used in the access control list below. To read a group from the token use `userGroupField`.
certBundlePath	`/certs/ca-certificates.crt`	Trusted CA certificates that are used to verify the certificate of Monosign (see below).
authRequireGuestsToLogin	`true`	Shows the sign-in page first. Without it, guests can see and run the buttons that are allowed by `defaultPermissions`.
defaultPermissions	All `false`	A user without a matching access control list cannot see or run anything.
accessControlLists	`monosign-users`	Gives the group `monosign` the permissions to view, run and read the logs of every button (`addToEveryAction`).

OliveTin runs commands on the machine where it works. Only the users of the access control list can run the buttons, so keep the group and the buttons as small as possible. Do not mount the Docker socket into the container unless it is really needed, because every user who can run a button could then control the Docker host.

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

Without an access control list the user signs in, but sees no button. The sign-in itself is checked by Monosign (assignment), the permissions inside OliveTin are decided by the access control list.

To verify the certificate of Monosign, OliveTin needs the trusted CA certificates. Mount the CA bundle of the host to the container (read-only) and point certBundlePath to it. Do not use insecureSkipVerify. Then recreate the container:

YAML

services:
  olivetin:
    image: jamesread/olivetin
    ports:
      - "1337:1337"
    volumes:
      - ./config:/config
      - /etc/ssl/certs/ca-certificates.crt:/certs/ca-certificates.crt:ro
    restart: unless-stopped

Bash

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

The sign-in page must now show the Login with Monosign button.

Now try to log in to OliveTin using Monosign SSO.

Open a new browser window (or a private window) and type the OliveTin address. The sign-in page shows the Login with Monosign button.

OliveTin sign-in page with the “Login with Monosign” button

Click Login with Monosign. OliveTin redirects the browser to the Monosign sign-in page of the Olivetin 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 OliveTin (/oauth/callback). The signed-in user is shown at the top right. The User Information page shows the user name (the e-mail address), the provider oauth2, the group monosign and the matched access control list monosign-users.

User logged in to OliveTin through Monosign SSO (User Information page)

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

Troubleshooting

Symptom	Cause	Solution
The “Login with Monosign” button is not shown	`authOAuth2Providers` is missing or wrong, or the container was not recreated.	Check the `config.yaml` (step 4) and run `docker compose up -d --force-recreate`.
Monosign shows a redirect URI error	The redirect URI that OliveTin sends does not exactly match the Allowed Redirect URIs.	Add `https://<olivetin-address>/oauth/callback` in Monosign (step 2). Check `oauth` (not `oauth2`) and the same host name as `authOAuth2RedirectUrl`.
The user signs in but sees no button	No access control list matches the user, and `defaultPermissions` are `false`.	Set `addToUsergroup` (or `userGroupField`) and add an access control list with `matchUsergroups` for that group (step 4). Check the Matched ACLs on the User Information page.
The sign-in fails or the user name is empty	The field in `usernameField` is not in the UserInfo response.	Use `email`, or add the claim on the Claim Mapping tab in Monosign, click Update and use its name.
The log contains `x509: certificate signed by unknown authority`	The container does not trust the certificate of Monosign.	Mount the CA bundle of the host and set `certBundlePath` (step 4). Do not disable the certificate verification.
The log contains `State mismatch` or `Failed to get state cookie`	The browser blocks the cookie, or the sign-in was started on another address than `authOAuth2RedirectUrl` (for example `http` instead of `https`).	Use the same public HTTPS address everywhere and test in a new private window.
A user cannot sign in	The user is not assigned to the application.	Assign the user in step 3.
ID token validation, SAML or OIDC discovery is required	OliveTin supports OAuth 2.0 only.	Use the OAuth 2.0 integration in this document.

After completing the configuration on OliveTin and Monosign, it is better to test in a new private browser window if the SSO doesn’t work, because old session cookies of the OliveTin address may cause errors.