KSM-199 ServiceNow plugin version 0.0.1

integration/mid-keeper-external-credential-resolver/.gitattributes

@@ -0,0 +1,9 @@
+#
+# https://help.github.com/articles/dealing-with-line-endings/
+#
+# Linux start script should use lf
+/gradlew        text eol=lf
+
+# These are Windows script files and should use crlf
+*.bat           text eol=crlf
+

integration/mid-keeper-external-credential-resolver/.gitignore

@@ -0,0 +1,29 @@
+# Compiled class file
+*.class
+
+# Log file
+*.log
+
+# BlueJ files
+*.ctxt
+
+# Mobile Tools for Java (J2ME)
+.mtj.tmp/
+
+# Package Files #
+*.jar
+*.war
+*.nar
+*.ear
+*.zip
+*.tar.gz
+*.rar
+
+# virtual machine crash logs, see http://www.java.com/en/download/help/error_hotspot.xml
+hs_err_pid*
+
+build/
+.gradle/
+.idea/
+.DS_Store
+!gradle/wrapper/gradle-wrapper.jar

integration/mid-keeper-external-credential-resolver/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2023 Keeper Security
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

integration/mid-keeper-external-credential-resolver/README.md

@@ -0,0 +1,68 @@
+# MID Server External Credential Resolver for Keeper Secrets Manager
+This is the ServiceNow MID Server custom external credential resolver for the Keeper vault credential storage.
+
+# Pre-requisites:
+Keeper External Credential Resolver requires JDK 1.8 or newer  
+IntelliJ IDEA or any equivalent IDE
+
+> ⚠️ JRE 8 versions prior to u161 require strong cryptography (JCE) to be enabled.
+Latest versions of JRE have strong cryptography enabled [by default](https://bugs.openjdk.java.net/browse/JDK-8170157).
+
+# Steps to build
+* Clone this repository.
+* Import the project in IntelliJ IDEA or any IDE.
+* Update MID Server agent path in build.gradle to point to valid MID Server location.
+* Update the code in CredentialResolver.java to customize anything.
+* Use the following gradle command or IDE (IntelliJ or Eclipse) gradle build option to build the jar:
+  > gradle jar  
+* keeper-external-credentials-0.0.1-SNAPSHOT.jar will be generated under target folder.
+
+# Steps to install and use Keeper Secrets Manager as external credential resolver
+
+* Make sure that "External Credential Storage" plugin (com.snc.discovery.external_credentials) is installed in your ServiceNow instance.
+* Import the keeper-external-credentials-0.0.1-SNAPSHOT.jar file from target folder in ServiceNow instance.
+    - Navigate to MID Server – JAR Files
+    - Create a New Record by clicking New
+    - Name it "KeeperCredentialResolver", version 0.0.1 and attach keeper-external-credentials-0.0.1-SNAPSHOT.jar from target folder.
+    - Click Submit
+* Update the _config.xml_ in MID Server with below parameters and restart the MID Server.
+  `<parameter name="ext.cred.keeper.ksm_config" secure="true" value="<ksm-config-base64-string>"/>`
+* Create Credential in the instance with "External credential store" flag activated.
+* Ensure that the "Credential ID" matches a record UID in your Keeper vault.
+* Ensure that the record in the vault contains fields matching the ServiceNow credential record fields - ex. record _type=login_ or any record type with custom fields of _type=hidden_ or _type=text_ with labels matching with the column names in discovery_credential table, where each label is prefixed with  "mid_" (ex. GCP Credential requires a record with two custom fields labelled: mid_email and mid_secret_key)
+
+# Finding records
+Credential ID (credId parameter) passed from MID Server to Credential Resolver must be either a valid record UID (22 alphanumeric characters incl. "-" and "_") or in the following format type:title. The second format allows searches by type only or by title only (or both, but single ":" is invalid combination)
+> ⚠️ When using `type:title` format for the credential make sure there's only one matching record, since multiple matches result in error.
+
+> ⚠️ We recommend using record UID - first to guarantee uniqueness, second to avoid downloading all records with every single request to do a local search by type/title (due to zero knowledge nature of the keeper vault).
+
+#### Examples:
+_(zero or two or more matches result in an error)_  
+Find by Record UID - `ABCDABCDABCDABCDABCDAB`  
+Find by type and title - `login:MyLogin`  
+Find by title - `:MyLogin`  
+Find by type - `login:`
+
+# Mapping fields
+Keeper record types are dynamic and easy to customize, but there are no specific record types matching corresponding credential types in ServiceNow. Keeper External Credential Resolver uses custom field labels to match record data with MID Server's table columns (`discovery_credential` _table_) just label all required custom fields to match the table columns for a given credential type and prefix that label with "mid_" _(see below how to configure custom prefix)_  
+Credential types that require username/password should use Login records, and add any custom fields required by the credential type - ex. type=hidden label="mid_pkey"  
+Any other types that may not have username/password it is best to use File/Photo records which don't have any standard fields that makes it easier to navigate the custom fields.  
+
+To change the custom field labels prefix update the _config.xml_ in MID Server with the parameters below and restart the MID Server.
+  `<parameter name="ext.cred.keeper.ksm_label_prefix" value="mid_"/>`
+
+> ️ⓘ Use custom fields with type `text`, `multiline` or `hidden` depending on the visibility you want in your Keeper Vault.
+
+> ⚠️ When Login record type is used any custom fields for username/password are ignored _(even if properly labeled mid_user, mid_pswd)_ as these values always come from the Login record type standard fields - Login/Password.
+
+#### Examples:  
+ + Credential type `jdbc` map to Keeper record type `Login` (using standard Login/Password field)
+ + Credential type `api_key` map to Keeper record type `Login` and manually add custom fields with of type `hidden` with labels `mid_ssh_private_key`, and `mid_ssh_passphrase` (_optional_)
+ + Credential type `gcp` map to Keeper record type `File Attachment/Photo` and manually add the required custom fields `mid_email` - _text_, `mid_secret_key` - _hidden_.   
+
+When used with **"External credential store"** option output values must conform to IExternalCredential interface from `snc-automation-api.jar` (values start with VAL_ prefix).
+Currently supported values - should be prefixed with `mid_` in Keeper records to be extracted (Utah: _user, pswd, passphrase, pkey, authprotocol, authkey, privprotocol, privkey, secret_key, client_id, tenant_id, email_)
+
+When used as Custom External Credential Resolver any field could be mapped **if properly prefixed** in Keeper vault and present in corresponding credential type. 
+The credential map returned from the resolve method is expected to have keys matching with the column names in discovery_credential table _ex. sn_cfg_ansible, sn_disco_certmgmt_certificate_ca, cfg_chef_credentials, etc._

integration/mid-keeper-external-credential-resolver/build.gradle

@@ -0,0 +1,49 @@
+plugins {
+    id 'java'
+}
+
+archivesBaseName = 'keeper-external-credentials'
+group 'com.keepersecurity'
+version '0.0.1-SNAPSHOT'
+
+sourceCompatibility = 1.8
+
+// TODO: replace with mid server path
+// This must point to the MID Server installation location (agent directory path).
+def midserver_agent_dir = '/opt/servicenow/mid/agent/lib'
+
+repositories {
+    mavenCentral()
+    flatDir {
+        dirs("$midserver_agent_dir")
+    }
+}
+
+dependencies {
+    implementation 'com.keepersecurity.secrets-manager:core:16.5.4+'
+
+    // MID server dependencies, not required to be uploaded
+    // MID jar dependency for config APIs
+    compileOnly 'com.snc:mid:19.0.0.0-SNAPSHOT'
+    compileOnly 'com.snc:commons-glide:19.0.0.0-SNAPSHOT'
+    compileOnly 'com.snc:commons-core-automation:19.0.0.0-SNAPSHOT'
+    compileOnly 'com.snc:snc-automation-api:19.0.0.0-SNAPSHOT'
+    compileOnly 'com.google.guava:guava:2.8.2'
+    compileOnly 'log4j:log4j-api:1.2.17'
+    compileOnly 'commons-logging:commons-logging'
+    compileOnly 'org.jetbrains.kotlin:kotlin-jdk-annotations:1.0.0'
+}
+
+jar {
+    duplicatesStrategy = DuplicatesStrategy.EXCLUDE
+    manifest {
+        attributes('Main-Class': 'com.snc.discovery.CredentialResolver')
+    }
+    from {
+        configurations.runtimeClasspath.collect { it.isDirectory() ? it : zipTree(it) }
+    } {
+        exclude "META-INF/*.SF"
+        exclude "META-INF/*.DSA"
+        exclude "META-INF/*.RSA"
+    }
+}

integration/mid-keeper-external-credential-resolver/gradle/wrapper/gradle-wrapper.properties

@@ -0,0 +1,6 @@
+distributionBase=GRADLE_USER_HOME
+distributionPath=wrapper/dists
+distributionUrl=https\://services.gradle.org/distributions/gradle-8.1.1-bin.zip
+networkTimeout=10000
+zipStoreBase=GRADLE_USER_HOME
+zipStorePath=wrapper/dists

integration/mid-keeper-external-credential-resolver/gradlew

@@ -0,0 +1,190 @@
+#!/usr/bin/env sh
+
+
+##############################################################################
+#
+#   Gradle start up script for POSIX
+#
+##############################################################################
+
+# Attempt to set APP_HOME
+
+# Resolve links: $0 may be a link
+app_path=$0
+
+# Need this for daisy-chained symlinks.
+while
+    APP_HOME=${app_path%"${app_path##*/}"}  # leaves a trailing /; empty if no leading path
+    [ -h "$app_path" ]
+do
+    ls=$( ls -ld "$app_path" )
+    link=${ls#*' -> '}
+    case $link in             #(
+      /*)   app_path=$link ;; #(
+      *)    app_path=$APP_HOME$link ;;
+    esac
+done
+
+# This is normally unused
+# shellcheck disable=SC2034
+APP_BASE_NAME=${0##*/}
+APP_HOME=$( cd "${APP_HOME:-./}" && pwd -P ) || exit
+
+# Use the maximum available, or set MAX_FD != -1 to use that value.
+MAX_FD=maximum
+
+warn () {
+    echo "$*"
+} >&2
+
+die () {
+    echo
+    echo "$*"
+    echo
+    exit 1
+} >&2
+
+# OS specific support (must be 'true' or 'false').
+cygwin=false
+msys=false
+darwin=false
+nonstop=false
+case "$( uname )" in                #(
+  CYGWIN* )         cygwin=true  ;; #(
+  Darwin* )         darwin=true  ;; #(
+  MSYS* | MINGW* )  msys=true    ;; #(
+  NONSTOP* )        nonstop=true ;;
+esac
+
+CLASSPATH=$APP_HOME/gradle/wrapper/gradle-wrapper.jar
+
+
+# Determine the Java command to use to start the JVM.
+if [ -n "$JAVA_HOME" ] ; then
+    if [ -x "$JAVA_HOME/jre/sh/java" ] ; then
+        # IBM's JDK on AIX uses strange locations for the executables
+        JAVACMD=$JAVA_HOME/jre/sh/java
+    else
+        JAVACMD=$JAVA_HOME/bin/java
+    fi
+    if [ ! -x "$JAVACMD" ] ; then
+        die "ERROR: JAVA_HOME is set to an invalid directory: $JAVA_HOME
+
+Please set the JAVA_HOME variable in your environment to match the
+location of your Java installation."
+    fi
+else
+    JAVACMD=java
+    which java >/dev/null 2>&1 || die "ERROR: JAVA_HOME is not set and no 'java' command could be found in your PATH.
+
+Please set the JAVA_HOME variable in your environment to match the
+location of your Java installation."
+fi
+
+# Increase the maximum file descriptors if we can.
+if ! "$cygwin" && ! "$darwin" && ! "$nonstop" ; then
+    case $MAX_FD in #(
+      max*)
+        # In POSIX sh, ulimit -H is undefined. That's why the result is checked to see if it worked.
+        # shellcheck disable=SC3045
+        MAX_FD=$( ulimit -H -n ) ||
+            warn "Could not query maximum file descriptor limit"
+    esac
+    case $MAX_FD in  #(
+      '' | soft) :;; #(
+      *)
+        # In POSIX sh, ulimit -n is undefined. That's why the result is checked to see if it worked.
+        # shellcheck disable=SC3045
+        ulimit -n "$MAX_FD" ||
+            warn "Could not set maximum file descriptor limit to $MAX_FD"
+    esac
+fi
+
+# Collect all arguments for the java command, stacking in reverse order:
+#   * args from the command line
+#   * the main class name
+#   * -classpath
+#   * -D...appname settings
+#   * --module-path (only if needed)
+#   * DEFAULT_JVM_OPTS, JAVA_OPTS, and GRADLE_OPTS environment variables.
+
+# For Cygwin or MSYS, switch paths to Windows format before running java
+if "$cygwin" || "$msys" ; then
+    APP_HOME=$( cygpath --path --mixed "$APP_HOME" )
+    CLASSPATH=$( cygpath --path --mixed "$CLASSPATH" )
+
+    JAVACMD=$( cygpath --unix "$JAVACMD" )
+
+    # Now convert the arguments - kludge to limit ourselves to /bin/sh
+    for arg do
+        if
+            case $arg in                                #(
+              -*)   false ;;                            # don't mess with options #(
+              /?*)  t=${arg#/} t=/${t%%/*}              # looks like a POSIX filepath
+                    [ -e "$t" ] ;;                      #(
+              *)    false ;;
+            esac
+        then
+            arg=$( cygpath --path --ignore --mixed "$arg" )
+        fi
+        # Roll the args list around exactly as many times as the number of
+        # args, so each arg winds up back in the position where it started, but
+        # possibly modified.
+        #
+        # NB: a `for` loop captures its iteration list before it begins, so
+        # changing the positional parameters here affects neither the number of
+        # iterations, nor the values presented in `arg`.
+        shift                   # remove old arg
+        set -- "$@" "$arg"      # push replacement arg
+    done
+fi
+
+
+# Add default JVM options here. You can also use JAVA_OPTS and GRADLE_OPTS to pass JVM options to this script.
+DEFAULT_JVM_OPTS='"-Xmx64m" "-Xms64m"'
+
+# Collect all arguments for the java command;
+#   * $DEFAULT_JVM_OPTS, $JAVA_OPTS, and $GRADLE_OPTS can contain fragments of
+#     shell script including quotes and variable substitutions, so put them in
+#     double quotes to make sure that they get re-expanded; and
+#   * put everything else in single quotes, so that it's not re-expanded.
+
+set -- \
+        "-Dorg.gradle.appname=$APP_BASE_NAME" \
+        -classpath "$CLASSPATH" \
+        org.gradle.wrapper.GradleWrapperMain \
+        "$@"
+
+# Stop when "xargs" is not available.
+if ! command -v xargs >/dev/null 2>&1
+then
+    die "xargs is not available"
+fi
+
+# Use "xargs" to parse quoted args.
+#
+# With -n1 it outputs one arg per line, with the quotes and backslashes removed.
+#
+# In Bash we could simply go:
+#
+#   readarray ARGS < <( xargs -n1 <<<"$var" ) &&
+#   set -- "${ARGS[@]}" "$@"
+#
+# but POSIX shell has neither arrays nor command substitution, so instead we
+# post-process each arg (as a line of input to sed) to backslash-escape any
+# character that might be a shell metacharacter, then use eval to reverse
+# that process (while maintaining the separation between arguments), and wrap
+# the whole thing up as a single "set" statement.
+#
+# This will of course break if any of these variables contains a newline or
+# an unmatched quote.
+#
+
+eval "set -- $(
+        printf '%s\n' "$DEFAULT_JVM_OPTS $JAVA_OPTS $GRADLE_OPTS" |
+        xargs -n1 |
+        sed ' s~[^-[:alnum:]+,./:=@_]~\\&~g; ' |
+        tr '\n' ' '
+    )" '"$@"'
+
+exec "$JAVACMD" "$@"