Gestalt Security

Gestalt Security provides security services to the other services. It currently supports OAuth2 authentication via API key/secret pairs and JSON Web tokens.

Gestalt Security also manages users and groups using directories. This allows Gestalt to access and authenticate against a federation of directories each with their own sets of users and groups. There are 2 types of directories currently. The first is an internal directory managed by Gestalt Security. The second is through Active Directory / LDAP directories which integrate into existing externally managed services for users to authenticate against.


The primary job of Gestalt Security is to authenticate users on incoming requests to Gestalt. The primary authentication mechanism is Oauth2, via Basic key/secret pairs, and via temporary Bearer tokens. Gestalt Security also supports Active Directory and LDAP authentication.

Gestalt Security also provides access to User and Group identity. Currently 2 types of directories are supported. Default directories store and find users and groups in a postgresql database. Also available as a licensed feature are LDAP directories, which find users on configured Active Directory and LDAP servers.

Gestalt Security Overview


Gestalt Security currently supports 2 types of authentication. The first is API key/secret pairs. These are generated credentials for use in API calls. They never expire and should be protected as they will allow authentication given a key/secret match. An API key/secret pair is generated upon initialization of the Gestalt Security service.

Another type of authentication supported are Bearer tokens. These can handily be used by an application, such as the Gestalt UI web app, and present a lower risk than API key/secret pairs, since they are only valid for a limited window of time.

Note: We are using httpie instead of curl, examples use localhost

http -f localhost:9455/root/oauth/issue grant_type=password username=myuser password=letmein

HTTP/1.1 200 OK
Content-Length: 127
Content-Type: application/json
Date: Mon, 06 Feb 2017 16:46:20 GMT

    "access_token": "5d34eb86-1b2d-4c74-a4bf-9b792dfbbdxx",
    "expires_in": 28800,
    "gestalt_access_token_href": "",
    "token_type": "bearer"

Failure example:

http -f /root/oauth/issue grant_type=password username=myuser password=dontletmein

failure result:
HTTP/1.1 400 Bad Request
Content-Length: 154
Content-Type: application/json
Date: Mon, 06 Feb 2017 16:47:32 GMT

    "code": 400,
    "error": "invalid_grant",
    "error_description": "The provided authorization grant is invalid, expired or revoked.",
    "resource": "/root/oauth/issue"

To use the token:

http localhost:9455/root Authorization:"Bearer 5d34eb86-1b2d-4c74-a4bf-9b792dfbbdxx"
HTTP/1.1 200 OK
Content-Length: 199
Content-Type: application/json
Date: Mon, 06 Feb 2017 17:13:20 GMT

    "children": [
            "href": "/orgs/3dfc64df-49f0-4b94-a74e-b51b4246ad11",
            "id": "3dfc64df-49f0-4b94-a74e-b51b4246ad11",
            "name": "myorg"
    "fqon": "root",
    "id": "7c487351-8649-4c67-844e-e6702e52834b",
    "name": "root"

Initialization & Recovery

If you are installing via the Gestalt Launcher, initialization of Gestalt Security is handled for you. However, if you are installing the Gestalt Security service manually, it needs to be initialized. This is done through an API endpoint /init. This endpoint returns a JSON object which contains the API key/secret pair for the root user.

http POST localhost:9455/init @init.json
HTTP/1.1 200 OK
Content-Length: 174
Content-Type: application/json
Date: Mon, 06 Feb 2017 17:24:17 GMT

        "accountId": "546007ec-7a3b-4146-987f-a50947b2612e",
        "apiKey": "82d2ef66-f356-4f84-bf96-da18507ad5xx",
        "apiSecret": "1Z/EtJqBpfZOjnotI/0FmasA74KJ4ekyGG0mcwxx",
        "disabled": false

Recovery of Admin Credentials

If you lose your apiKey/apiSecret, and your root password and need to recover, there is a way. Gestalt Security keeps a flag in the database called inititalization_settings. Clearing this flag and running /init will return the apiKey/apiSecret, from which you can reset your root password. This is all handled in the launcher. Rerun the launcher to reset the flag to enable returning the startup information.

Active Directory / LDAP Plugin

Gestalt includes a security plugin to integrate with Active Directory and LDAP servers. This integration currently supports user authentication with AD / LDAP directories. Integration to an AD / LDAP directory is relative to an Organization resource in Gestalt. This does allow integration to multiple AD / LDAP directories on a 1 per organization level, by adding multiple organizations.

The authentication process first looks for the user in Gestalt and if found, will authenticate the user against the external AD / LDAP service. If the user is not found in Gestalt, each directory is tried until the list is exhausted or the user is found in a directory and authentication succeeds. If successful, the user is shadowed in Gestalt as an AD / LDAP user. This allows for entitlements and authorization to proceed similar to normal Gestalt user.

In the future additional integration with AD / LDAP properties, groups, roles, and/or authorization may be provided.

How to integrate with Active Directory and/or LDAP

  1. Add an organization to the root organization.

  2. Add a directory to the new organization.

    • Currently this can be done via a REST call similar to the following:
POST - https:<gestalt-security-host>/<fqon>/directories
        "name" : "<directory name>",
        "directoryType": "LDAP",
        "description": "<description>",
        "config": {
            “activeDirectory” : <true/false>,
            “url” : "<ldap-url>”,
            “searchBase” : "dc=example,dc=com”,
            “systemUsername” : “<ldap-user>”,
            “systemPassword” : “<ldap-password>”,
            “primaryField” : “uid”,
            “globalSessionTimeout” : 5000
Configuration options:
Option Description
activeDirectory true = use field defaults for ActiveDirectory
false = use field defaults for LDAP
url Url to LDAP service
searchBase Searchbase for Active Directory / LDAP searches
Tip: Include CN=Users for Active Directory if needed
systemUsername Username for connection context to Active Directory / LDAP service
systemPassword Password for connection context to Active Direcotry / LDAP service
connectionTimeout Timeout for individual search or authentication
globalSessionTimeout Total time allowed for session
credentialsMatcher Supports available Apache Shiro credential matchers
authenticationMechanism Supports available Apache Shiro authentication mechanisms
primaryField Field name used for user primary authentication (CN, uid)
descriptionField Field used for user description (description)
firstName Field to be used to shadow first name (firstName)
lastNameField Field to be used to shadow last name (lastName)
emailField Field to be used for email (mail)
phoneNumberField Field to be used for phone number (phoneNumber)
groupField Field to be used for groups (group, groupOfUniqueNames)
userObjectClass Field to be used for users (user, person)
memberField Field to be used for group members (member, uniqueMember)

Account Lookup

When an account search is done on an organization, this search is propagated to all the directories in that organization, some of which may be LDAP directories. In LDAP directories the search is sent to the Active Directory / LDAP service to look for possible accounts which are not currently shadowed in Gestalt. Both the shadowed accounts and any matching LDAP / Active Directory users are returned.

Account Authentication

Accounts (users) in LDAP directories authenticate accounts by calling the Active Directory / LDAP service to perform the authentication. Once authenticated by the external service, an authenticated account is returned through API or to the user interface for use.

The authentication process in LDAP directory also adds any groups found that the user is a member of and shadows those groups as well as establishing the user membership in shadowed groups.

The net result is that through LDAP directory integration you can have access to users and groups that currently exist in Active Directory and LDAP services, while letting those services authenticate users.

Group Lookup

When groups are searched with an LDAP directory defined, the search is extended into the configured Active Directory / LDAP services. Found groups are shadowed in Gestalt.

Note: In the future this will be configurable via the Gestalt user interface as a provider in the Organization.