OMPASS 2FA Authentication

A Jenkins plugin that adds OMPASS-based two-factor authentication (2FA) to your Jenkins instance. After users log in with their primary credentials, they are required to complete a second authentication step through the OMPASS platform before accessing Jenkins resources.

Before using this plugin, you need an OMPASS account with a configured application (Client ID and Secret Key).

1. Sign up at https://ompasscloud.com/en/.
2. Create an application in the OMPASS portal to obtain your Client ID and Secret Key.
3. Install and configure this plugin with those credentials (see Configuration).

• Global 2FA enforcement: Enable or disable OMPASS 2FA for all users from a single configuration page.
• Transparent filter-based interception: A servlet filter intercepts all requests and redirects unauthenticated-2FA users to the OMPASS authentication flow. No changes to the Jenkins security realm are required.
• Popup-based authentication: The OMPASS authentication UI opens in a popup window. Once the user completes 2FA, the popup closes automatically and the parent page redirects to the original destination.
• Token verification: Authentication tokens are verified server-side against the OMPASS API to prevent tampering.
• Session persistence: Once a user completes 2FA, their session is marked as verified for the remainder of the session.
• Relay state preservation: The original URL the user was trying to access is preserved and restored after successful 2FA.
• Connection testing: Administrators can test the connection to the OMPASS server from the configuration page before enabling 2FA.
• Multi-language support: The OMPASS authentication prompt can be displayed in English or Korean.
• Secret key encryption: The OMPASS secret key is stored using Jenkins' built-in Secret encryption, not as plain text.
• Fail-open strategy: If the 2FA filter encounters an unexpected error, the request is allowed through to avoid locking users out.
• Emergency bypass: A system property (ompass.2fa.bypass=true) allows administrators to disable 2FA without accessing the Jenkins UI.

1. Build the plugin (see Build Instructions) or obtain the .hpi file.
2. In Jenkins, navigate to Manage Jenkins > Plugins > Advanced settings.
3. Under Deploy Plugin, click Choose File and select the .hpi file.
4. Click Deploy and restart Jenkins when prompted.

1. Copy the .hpi file to the $JENKINS_HOME/plugins/ directory.
2. Restart Jenkins.

After installing the plugin, configure it from the Jenkins management page:

1. Navigate to Manage Jenkins > OMPASS 2FA Configuration (under the Security section).
2. Fill in the following fields:

3. Click Test Connection to verify that Jenkins can communicate with the OMPASS server.
4. Click Save to apply the configuration.

The plugin operates through the following flow:

1. User logs in to Jenkins with their primary credentials (username/password, LDAP, SSO, etc.).
2. Filter intercepts the request. The OmpassFilter checks whether the user has completed 2FA for this session.
3. Redirect to auth page. If 2FA is not yet verified, the user is redirected to /ompassAuth/, and their original URL is saved as the relay state.
4. OMPASS auth starts. The OmpassAuthAction calls the OMPASS server's startAuth API and receives an OMPASS authentication URL.
5. Popup opens. The OMPASS authentication URL opens in a popup window where the user completes 2FA (e.g., mobile push notification, biometric verification).
6. Callback received. After successful authentication, the OMPASS server redirects the popup to /ompassCallback/ with a verification token.
7. Token verified. The OmpassCallbackAction verifies the token against the OMPASS server's verifyToken API.
8. Session marked. On successful verification, the user's session is marked with a {userId}_OMPASS_2FA_VERIFIED attribute.
9. Popup notifies parent. The popup window sends a postMessage to the parent window indicating success.
10. Redirect to destination. The parent page redirects the user to their original URL (relay state).

The following URL patterns are excluded from 2FA enforcement to avoid breaking Jenkins functionality:

• Jenkins system URLs: /logout, /login, /adjuncts, /static, /crumbIssuer, /theme
• Plugin URLs: /ompassAuth, /ompassCallback, /ompass2fa-config
• API/CLI endpoints: /api/, /cli
• Static resources: .css, .js, .png, .ico, .gif, .jpg, .jpeg, .svg, .woff, .woff2, .ttf, .eot

If you are locked out of Jenkins due to a 2FA misconfiguration, you can bypass 2FA by setting a JVM system property:

# Add to Jenkins startup arguments
-Dompass.2fa.bypass=true

Or set it in the JAVA_OPTS or JENKINS_JAVA_OPTIONS environment variable before starting Jenkins:

export JAVA_OPTS="-Dompass.2fa.bypass=true"

Once you regain access, disable 2FA from the configuration page and remove the system property.

To enable detailed logging for the OMPASS 2FA plugin:

1. Navigate to Manage Jenkins > System Log.
2. Click Add new log recorder and name it OMPASS 2FA.
3. Add the logger io.jenkins.plugins.ompass with log level FINE.
4. Save and reproduce the issue, then review the log entries.

• JDK 17 or later
• Apache Maven 3.x

# macOS (specify JDK 11)
JAVA_HOME=$(/usr/libexec/java_home -v 17) mvn clean package

# Linux (if JDK 11 is the default)
mvn clean package

# Skip tests
JAVA_HOME=$(/usr/libexec/java_home -v 17) mvn clean package -DskipTests

# Release build (remove SNAPSHOT)
JAVA_HOME=$(/usr/libexec/java_home -v 17) mvn clean package -Dchangelist=

Build output: target/ompass-2fa.hpi

JAVA_HOME=$(/usr/libexec/java_home -v 17) mvn test

# Accessible from localhost only
JAVA_HOME=$(/usr/libexec/java_home -v 17) mvn hpi:run

# Accessible from external IPs as well (e.g., 192.168.x.x)
JAVA_HOME=$(/usr/libexec/java_home -v 17) mvn hpi:run -Dhost=0.0.0.0

# Run without the /jenkins context path (root context)
JAVA_HOME=$(/usr/libexec/java_home -v 17) mvn hpi:run -Dprefix=/

By default, Jenkins will be available at http://localhost:8080/jenkins/. With -Dprefix=/, it will be available at http://localhost:8080/.

src/main/java/io/jenkins/plugins/ompass/
  OmpassGlobalConfig.java       - Global configuration (server URL, credentials, toggle)
  OmpassGlobalConfigView.java   - Management link and configuration UI controller
  OmpassFilter.java             - Servlet filter enforcing 2FA on all requests
  OmpassAuthAction.java         - Initiates the OMPASS authentication flow
  OmpassCallbackAction.java     - Handles the OMPASS authentication callback
  OmpassClientFactory.java      - Thread-safe factory for the OMPASS SDK client
  OmpassUserProperty.java       - Per-user property tracking OMPASS registration status

src/main/resources/io/jenkins/plugins/ompass/
  OmpassAuthAction/index.jelly         - Authentication page with popup logic
  OmpassCallbackAction/index.jelly     - Callback result page (closes popup)
  OmpassGlobalConfigView/index.jelly   - Admin configuration form
  OmpassUserProperty/config.jelly      - User property display in profile

This project is licensed under the MIT License. See LICENSE.md for details.

Copyright (c) 2024 OneMoreSecurity Co., Ltd.