For Administrators

Mamori Version & License

To view the server version and manage the mamori license

Click > Help

Click > Mamori License



Raising a support issue

Raise feature request or errors on our public git project. Click here for git project.

If you are asked to email a support bundle, then you can generate one from the help section.

Click > Help

Click > Download Support Bundle



Managing Proxy Listeners

To view and manage the database and SSH proxy ports

Click Server Settings

Click Proxies

To disable a proxy set the port to 0 (zero) and click apply.
ProxyDefault Listener Port
SSH1122
Postgres5432
Oracle1521
MySQL3306
Microsoft SQL Server1433
mongoDB28017
Other JDBC1527



Datasource Drivers

To view and manage the datasource drivers

Click Server Settings

Click Drivers

Click

Set the name, type

Select the upload the driver resource file

Click Ok



Database Drivers

Common database driver links

DatabaseDownloadNotes
Amazon RedshiftDownload redshift JDBC driverCan use native postgres proxy
Aurora MySQLSee MySQL
Aurora PostgresPostgres is preinstalled with mamori server
BigSQLDownload BigSQL/DB2 drivers50000
CassandraDownload Apache Cassandra driver
DerbyDownload Derby drivers
EDB PostgresDownload EDB Postgres driverPostgres is preinstalled with mamori server
Gemfire (AKA Pivotal Gemfire)Download Pivotal Gemfire driver
Hadoop[Contact mamori for help with Enterprise Installations](mailto: support@mamori.com?subject=Hadoop%20enquiry)
HawqDownload Hawq driver
Hive ClouderaDownload Hive Driver 2.5.19 from Cloudera
Hive HortonworksDownload Hortonworks Hive driver
Greenplum ODBCDownload GreenPlum ODBCCan use the native postgres proxy
IBM DB2 LUWDownload from DB2 Drivers
Impala JDBCDownload Impala JDBC driver
InfiniDBSee MySQL
Mysql8Download MySQL driver
NetezzaNetezza Software and Client ApplicationsAKA IBM PureData. You'll need an IBM login to access their downloads page
OracleDownload Oracle JDBC driver
PostgresDownload Postgres driverPostgres preinstalled with mamori server.
RedshiftSee Amazon RedshiftCan use the native postgres proxy
SQL ServerDownload sql server JDBC driver
Download JTDS SQL Server JDBC driver
Sybase ASE / SAP ASEView SAP ASE drivers
Older Sybase ASE drivers (v 0.1 to 1.3.1)
SAP requires authorization to download drivers.
Sybase IQDownload sybase iq JDBC driver
TeradataDownload Teradata JDBC driverYou'll need to a Teradata account to download drivers.
VerticaDownload vertica JDBC driverYou'll need a vertica account to download drivers.



Please advise mamori support if you find outdated drivers in this list.



On Demand Policy Script Syntax

Mamori On Demand policy script syntax is an easy to use SQL-like syntax. Statements can have parameters and clauses that specify when the grant is valid.

A policy script can have many statements and one statement can :

  • Grant a role, privilege, or object permission
  • Grant access to an ssh login
  • Grant access to use an encryption key
  • Grant reveal masked data for specified database objects
  • Grant access to an IP resource
  • Insert, Update and delete table data
  • Run Insert as Select across databases

Parameters

The syntax uses :customvalue for statement parameters.

Validity

GRANT and GRANT REVEAL statements can include VALID date and time.

ClauseDescription
VALID BETWEEN :date1 AND :date2valid between two dates
VALID FROM :date1valid from a date
VALID UNTIL :date1valid from a date
VALID FOR :amount [seconds, minutes, or hours]valid from a specified unit of time

Enter dates in format YYYY-MM-DD

A permanent grant is one without a VALID clause.

Grant a privilege

policy script statements
GRANT REQUEST TO :applicant VALID FOR :time minutes;

Grant a Role, Policy, IP resource

policy script statements
GRANT myrole TO :applicant VALID BETWEEN :date1 AND :date2;
GRANT mypolicy TO :applicant VALID BETWEEN :date1 AND :date2;
GRANT myipresource TO :applicant VALID BETWEEN :date1 AND :date2;

Grant Encryption Key Usage

policy script statements
GRANT KEY USAGE on :encryptionkey TO :applicant VALID FROM :date1;

Grant Data Reveal

policy script statements
GRANT REVEAL * ON "datasource"."database"."schema"."table" TO :applicant valid for :time minutes;

Grant SSH Login

policy script statements
GRANT SSH mysshlogin TO :applicant VALID FOR :time hours;

Grant on DB Object

policy script statements
GRANT SELECT on "datasource"."database"."schema"."table" TO :applicant;
GRANT UPDATE on "datasource"."database"."schema"."table" TO :applicant;
GRANT INSERT on "datasource"."database"."schema"."table" TO :applicant;
GRANT DELETE on "datasource"."database"."schema"."table" TO :applicant;

GRANT CREATE TABLE on "datasource"."database"."schema" TO :applicant;
GRANT DROP TABLE on "datasource"."database"."schema" TO :applicant;

GRANT is overruled if there is a DENY already on the object.


SQL-Based Integration

To interact and integrate with mamori via SQL instead of API requests you need to

  • download and install the mamori ODBC (32-bit or 64-bit) or JDBC (64-bit) driver
  • connect any database tool to the mamori database



Downloading the driver

Go to the mamori server login page and do not login

Click on "download drivers"

Select your driver and download it

Unzip the media and install



Windows ODBC

Please make sure you use the matching 32-bit or 64-bit version of the ODBC Data Source Administrator

Run the driver MSI installer

Launch windows ODBC Data Source Administrator

Add a DSN

Select the Mamori Driver (Mamori 64)

Enter the following in the DSN Dialog

FieldDefault ValueDescription
Datasource NameEnter the DSN name
Server Host Name or IPEnter the IP address of the mamori server
Server Port1527
Remote SystemMamoriThe datasource to connect to
Datasource NameEnter the DSN name
CredentialsEnter a mamori login username and password

Click OK



JDBC

Open the driver manager of your SQL tool & Add a driver

  • Add the mamori jar file

  • Classpath is io.mamori.jdbc.security.Driver

  • Connection String

connection string
jdbc:mamori://YOURMAMORISERVER:1527/mamori;schemapattern=true

Manage Encryption & SSH Keys

With mamori's built-in key management service you can define or store

  • AES keys for symmetric data encryption
  • RSA key pairs for asymmetric data encryption
  • SSH private keys for SSH network tunnels and logins
You can get the public key for any private key by clicking the button in the grid.



Symmetric Encryption

To add an AES encryption key

Click Server Settings

Click Keys

Click

Set the key properties

FieldDescription
Key NameName passed into encryption function
Key TypeSelect AES
KeyEnter key content
Password (Optional)Require a password to encrypt/decrypt data

Click OK



Asymmetric Encryption

To add a part or create an RSA encryption key pair.

Click Server Settings

Click Keys

Click

Set the key properties

FieldDescription
Key NameName passed into encryption function
Key TypeSelect RSA
MethodSelect Automatic to generate a pair or Manual to paste in an existing public or private key
SizeDefaults to 1024

Click OK

User the public key to encrypt data and the private key to decrypt



SSH

To add an SSH key

Click Server Settings

Click Keys

Click

Set the key properties

FieldDescription
Key NameYour reference for the key
Key TypeSelect SSH
KeyPaste in the private key that you generated with ssh-keygen -t rsa

Do not add a keyphrase to your key

PasswordLeave Blank

Click OK


Access On-Demand Policies

To create an Access On-Demand policy follow the steps below

Prerequisites

Define Alert Channels

Ensure Request Permissions

To make requests a user must have the REQUEST privilege, either directly or via a role.

To request a particular policy a user must have the request role specified in the policy.

Click Policies

Click Access On Demand

Click Add

Next, enter the details

SectionFieldDescription
Policy Namename user will request
DescriptionDescription of grant policy will provide
Request
RoleRole required to request the policy
Alert (optional)Alert channel for new quests
Endorsement
Role(s)Roles required to endorse the policy
Level CountNumber of endorsements required per role
Default MessageDefault approval message to provider user
Approval Alert (optional)Alert channel for approved policies
Deny Alert (optional)Alert channel for a denials
Execute
Alert (optional)Alert channel for executed policies
Execute on approvaldefaults to false. When true the grant expiration starts on approval. When false it starts when the applicant executes the policy.
Script
Parameters (optional)Custom request parameters to collect from the applicant
StatementsEnter One or more Grant Statements. Script Statement Syntax

Click Create


Alert Channels

You can define an alert channel with one or more alerts. An alert can be an

  • Email
  • HTTP operation (POST, GET, PUT)
  • Mamori notification

Alert channels are used in connection policies, statement policies and access on-demand policies.

To create an alert channel

Click Server Settings

Click Alerts

Click Add

Next, enter the details

FieldDescription
Alert Namereference for alert channel
Alert Typethe type of alert
Alert detailsenter details for alert type

Click to add another alert in the channel

Click Create to save the channel

Parameters

To use parameters place the parameter inside brackets {{parameter}}.

Parameters for connection and session events

  • username
  • source (client IP address)
  • target (target datasource)
  • context (client information)

parameters for on-demand events

  • applicant
  • applicant_message
  • agent
  • agent_message
  • procedure (the policy name)
  • request_key
  • status

Email Alert

Next, enter the details

FieldDescription
Email Addressescomma separated list of emails
Subjectemail subject
Bodyemail content



Example Email Body

email body
DB access alert 
username: {{username}} 
accessing datasource {{target}}
client ip: {{source}}
context: {{context}}
contextjson: {{contextjson}}

Mamori Notification Alert

Sends a notification to the mamori mobile application.

Next, enter the details

FieldDescription
Recipient Namemamori user name or parameter

for example, {{applicant}}

Notification TypeMessage (Message Web Authenticator)

PushMessage (Message Mamori Mobile App)

Bodycontent



Messages content is a JSON object

title

message (HTML string content with parameters)

navigate-status (optional navigation)

 "endorsed"
 "declined"

navigate-to (optional navigation)

 "0" Policies page
 "1" Requests page
 "2' Request history page
 "3" Pending Approvals
 "4" Approval History
 "5" Active Permissions
 "6" Active Session
 "7" Approved Requests



Example Endorsement Alert

alert content
{
  "title":"Endorsed Notification",
  "navigate-status":"endorsed",
  "message":"<p style='text-align:left'>
<br>
<strong>policy: {{procedure}}</strong><br>
applicant: {{applicant}}<br>
message: {{applicant_message}}<br>
agent: {{agent}}<br>
reason: {{agent_message}}<br>
</p>"
}

HTTP Alert - Slack

Sends a notification to slack

Select HTTP as the alert type and enter the details

FieldDescription
HTTP OperationPOST
Header
Urlyour slack message hook

https://hooks.slack.com/services/YOURAPPID/YOURKEY

Bodycontent



Messages content is a JSON object

attachments

Example Endorsement Alert

alert content
{
 "attachments": [
       {   "color": "#2eb886",
           "pretext": "A policy has been endorsed",
           "author_name": "Mamori",
           "title": "Policy Request for {{applicant}} endorsed by {{agent}}",
           "text": "A policy request with the following parameters has been issued.",
           "fallback": "Request Details",
           "fields": {{contextjson}},
           "footer": "This is a Mamori Policy Notification",
       }
   ]
}

HTTP Alert - Line

Sends a notification to Line

Select HTTP as the alert type and enter the details

FieldDescription
HTTP OperationPOST
HeaderAuthorization: Bearer YOURLINEGROUPKEY
Urlhttps://notify-api.line.me/api/notify
Content Typeapplication/x-www-form-urlencoded
Bodycontent



Message content is a URL-encoded string

Example Endorsement Alert

alert content
message=A%20policy%20has%20been%20endorsed.%0D%0APolicy%20Request%20for%20{{applicant}}%20endorsed%20by%20{{agent}}%0D%0ARequest%20key:%20{{request_key}}%0APolicy%20name:%20{{procedure}}%0AApplicant%20message:%20{{applicant_message}}%0AReason:%20{{agent_message}}%0AStatus:%20{{status}}&notificationDisabled=false


Application Proxies

Configuration file JSON format

JSON files can be used to configure an application proxy.

To use a JSON configuration file when running a proxy in standalone mode pass in the -json=<jsonfile> parameter to the http_proxy_standalone.sh script. For example:

... -json="myfilters.json"

The config file can be uploaded to the mamori server to manage the configuration in the server.

The JSON file configuration format is an array of API filters which define the rules for intercepting incoming HTTP/S client requests. Each filter specifies the interception criteria and and one or more MASK transformations to apply to the API response data.

  • each filter defines a series of matching conditions to be able to identify which client HTTP request to intercept
  • each transformation specifies the response attributes to mask elementSpec and the MASK function to apply function

For example:

[
  {
    "name": "REST API",
    "system": "testsystem",
    "path": "/my-rest-api", <-- API endpoint to target
    "method": null,   
    "queryParameters": null,
    "headers": null,
    "body": null,
    "owner": "test",
    "active": 1,
    "transformations": [
      {
        "name": "default",          <-- user/role to apply to
        "priority": 1,
        "elementSpec": "$..price",  <-- JSON PATH for all price fields
        "function": "MASK FULL",    <-- Masking function to apply
      }
    ]
  },
  {
    "name": "XML API",
    "system": "testsystem",
    "path": "/my-xml-api", <-- API endpoint to target
    "method": null,
    "queryParameters": null,
    "headers": null,
    "body": null,
    "owner": "test",
    "active": 1,
    "transformations": [
      {
        "name": "default",         <-- user/role to apply to
        "priority": 1,
        "elementSpec": "//salary", <-- XML PATH for all salary fields
        "function": "MASK FULL",   <-- Masking function to apply
      }
    ]
  }
]
  • name - the filter/rule name
  • system - the system to apply the rule to
  • path - the HTTP request URL path to match on (regexp e.g .* is supported) e.g /info
  • method - the HTTP request method to match on e.g GET, POST, PUT
  • queryParameters - the HTTP request query parameters e.g op=getUserData
  • headers - the HTTP request headers to match on e.g X-OP=getUserData
  • body - the HTTP request body to match on e.g (regexp e.g .* is supported) e.g .*SOMEKEY

*Transformations - specify fields to mask **

To specify which response fields/attributes to mask set the filter attribute elementSpec.

The proxy supports 2 elementSpec types:

For example:

To target all title fields in a JSON response use the JSON path: $..title

To target all title fields in an XML response us the XML path: //title

Note, if the XML payload uses namespaces (as is common in SOAP responses) you must specify the namespace in your xpath e.g //ns:title or use local-name() if you don't know the specific namespace e.g //*\[local-name()='title'\].

Transformations - applying masking functions

Each transformation specifies the set of XML/JSON fields to target (elementSpec), the role/user that the transform applies too (name),and the mask/hash function to apply (function).

Masking function reference

FunctionDescription
MASK ALLMasks all characters with X or supplied mask character
MASK FIRSTMasks first N characters with X or supplied mask character
MASK LASTMasks last N characters with X or supplied mask character
MASK SUBSTRINGMasks a substring (start,end) characters with X or supplied mask character
MASK CCMasks the digits in a CC number
MASK SSNMasks all digits in a SSN
MASK PHONEMasks the last 4 digits of a phone number
MASK DATETIMEGenerates a random datetime or adds a days. If the input is String the datetime format must be supplied as a function arg
MASK DATEGenerates a random date or adds a days. If the input is a String, the date format must be supplied as a function arg
MASK DECIMALGenerates a random double to the specified number of digits and precision (decimals)
MASK INTGenerates a random long of the same length as the input
MASK EMAILMasks all characters with * or supplied mask character
MASK EMAIL KEEP SUFFIXMasks domain characters with * or supplied mask character
MASK EMAIL KEEP DOMAINMasks suffix characters with * or supplied mask character
MASK OUTMasks the first % with X or supplied mask character. Percentage defaults to 0.6 if not specified
MASK RANDOMMasks letters and digits with randomly generated letters and digits
MASK HASHMasks letters and digits with supplied hashing function e.g "MD5"
MASK HASH NUMERICMasks letters and digits with supplied hashing function e.g "SHA-1" to supplied length
MASK ROWQLIK only. Masks all rows where the column value matches the supplied regexp in the function args.
REVEALReveal a masked attribute

Dealing with SSL

Overview

By default the application/API proxies use a self signed certificate. Some browsers such as Chrome (and also curl) will raise an SSL error if you attempt to use HTTPS to access your API via the proxy.

Bypass the certificate check

If using CURL you can bypass the certificate check by using the curl flag --insecure.

For some browsers, it is possible to configure the browser to ignore the cert check.

Otherwise, you can either configure the proxy to use a valid certificate and private key for the domain you are proxying or deploy the proxy behind HAPROXY or NGINX or APACHE which handles the SSL terminator - this is the recommended option.

To use a certificate and key with a proxy

To add a cert/key, configure the location of the certificate and key files in config/proxy-<system>.properties:

mockserver.dynamicallyCreateCertificateAuthorityCertificate=false
mockserver.privateKeyPath=...     <-- your private key file
mockserver.x509CertificatePath=...<-- your certificate file

To generate a certificate for your domain you can use sites such as letsencrypt.org.

Example SSL/proxy forward NGINX config

An example NGINX for handling SSL and forwarding to a Qlik proxy running on a local port.

upstream qlik {
    server 127.0.0.1:8080; <-- Qlik proxy
}

server {
       server_name qlik.foo.com;

       listen 80;
       listen [::]:80;

       root /var/www/html;

       index some-file-that-does-not-exist;
       error_page 403 @gotohttps;
       error_page 404 @gotohttps;

       location / {
                try_files $uri $uri/ =404;
       }

       location @gotohttps {
                rewrite ^ https://$host$request_uri permanent;
       }
}

map $http_upgrade $connection_upgrade {
    default upgrade;
    ''      close;
}


server {
       server_name qlik.foo.com;

        # SSL configuration
        #
        listen 443 ssl http2;
        listen [::]:443 ssl http2;

        index index.html;
        root /var/www/html;

        ssl_certificate /etc/nginx/ssl/nginx.crt;
        ssl_certificate_key /etc/nginx/ssl/nginx.key;

        location / {
             proxy_pass http://qlik/;
             proxy_redirect off;
             proxy_http_version 1.1;
             proxy_set_header X-Forwarded-For $remote_addr;
             proxy_set_header Connection $connection_upgrade;
             proxy_set_header Upgrade $http_upgrade;
             proxy_read_timeout 7d;
             proxy_send_timeout 7d;
        }
}

Extracting the user from an HTTP/S request

Out of the box the application/API proxies provide two mechanisms to identify the requesting user:

  • Simple - extracts user details from a request header, query parameter or form field using a simple regular-expression based mechanism. This mechanism works with schemes such as Basic Authorisation.

  • Token - Maps a token to a user. This assumes signin occurs via the proxy and can only be used in a non clustered environment.

Method one: Simple

  • Open the config/proxy-<system>.properties configuration file in a terminal window.

  • Set the user extraction mechanism to simpleauth. Add the following configuration to extract the user from a request Authorization HTTP header:

authentication=simpleauth
simpleauth.header=Authorization        <-- or simpleauth.formfield=user or simpleauth.queryparam=user or simpleauth.body.regexp=.. or simpleauth.body=xpath or json path
simpleauth.header.regexp=.*

Will handle basic Authorization:

Authorization: Basic QWxhZGRpbjpPcGVuU2VzYW1l <-- user is extracted as Aladdin

Alternatively, if using a different header, specify that and use a Regular Expression to extract the username from the header value:

simpleauth.header=MySpecialAuthHeader       <-- name of the header to use
simpleauth.header.regexp=.*                 <-- Optional Regular expression to extract the username from the header contents (can be null)

Method two: Token

This mechanism extracts the user name from a signin/login and tracks the token to allow the user to be identified on subsequent requests.

This mechanism only works if the proxy is the only way to access the API and is able to intercept the signin.
  • Open the config/proxy-<system>.properties configuration file in a terminal window.

  • Set the extraction mechanism to tokenauth. Add the following configuration to extract the login token and user from an auth server

authentication=tokenauth

# Authorisation server
auth.remotehost=....
auth.remoteport=443

# On a user sign in
tokenauth.signin.path=(/users/sign_in|/users/session_data)
tokenauth.signin.method=

# User name and token extraction. Specify how to extract the user and token on sign in
tokenauth.user.body=$..email        <-- can also be in a header, query parameter or form field or body
tokenauth.token.body=$..token       <-- can also be in a header, query parameter or form field or body

# On a user signout
# Stops token from being tracked
tokenauth.signout.path=/users/sign_outec
tokenauth.signout.method=DELETE

# On all other requests extract token from token header
simpleauth.header=token

Once the user has been extracted, the proxy can determine the user's roles and determine which masking rules to apply.

If the user cannot be determined from the request the proxy will fallback to the default rules

Monitoring and Logging

By default the proxies publish various metrics about the JVM and endpoints to the proxy log and the mamori server monitoring sub-system.

The metrics can be viewed inside the the mamori server Influx/Grafana dashboards.

By default two monitoring channels are enabled:

  • InfluxDb
  • Proxy Log

More information on Influx configuration properties can be found at influx configuration

To Activate

  • Open the monitoring properties configuration file at /opt/mamori/server/http-proxy-<version>/config/monitoring.properties.
  • Set the following properties:
influx.enabled=true
logging.enabled=true

To Deactivate

  • Open the monitoring properties file at /opt/mamori/server/http-proxy-<version>/http-proxy-<version>/config/monitoring.properties.

  • Set the following properties:

influx.enabled=false
logging.enabled=false
If influx is not in use set `influx.enabled=false`

Proxy log files

  • Application Proxy log -- /opt/mamori/server/http-proxy-<version>/log/proxy-<system>-<instance>.log
  • Service issues log -- /var/log/syslog

Proxy healthcheck endpoint

The proxy heartbeat/healthcheck is on http/s:<proxy host>:<port>/healthcheck. If the proxy is up, it will return a status 200.

=======


Edit this page on GitHub Updated at Sun, Oct 17, 2021