AMS Configuration Reference


Table of Contents
AMS Configuration File Overview
AMS Configuration Properties at High Level
AMS Configuration Properties in-Depth
AMS Configuration File Example
Apple Text Editor Advisory when Editing Configuration Files

AMS Configuration File Overview

The configuration syntax for AMS is Human-Optimized Configuration Object Notation (HOCON). HOCON is a superset of JavaScript Object Notation (JSON), enhanced for readability. The specification for HOCON syntax is found here.

Two supplied configuration files are available for reference:

  • AMS.conf is the minimum starting point for customizing your AMS configuration. Substitution variables are specified for most properties in this file, allowing you to customize values without editing the file. Located in $AMS_HOME/conf.

  • AMS-defaults.conf provides application-specific configuration properties to run AMS. Located in the AMS JAR file.

Use the AMS.conf file for your customized configuration unless you are using your own configuration file. Customizations added to the AMS.conf file will override those in the AMS-defaults.conf where those specified properties overlap. Customizing the AMS-defaults.conf file is supported only through TIBCO Services.

To use your own site-specific configuration file and store in a directory of your choosing, use one of the following methods:

Method 1

Use the --conf filename command option to specify the AMS configuration file, which can be absolute or relative to the current working directory.

ams-server --conf /path/to/my/site-specific-AMS.conf
Method 2

Use the --resourcedirectory directory command option to specify a resource directory in which you stored AMS configuration files. When using this option, the file name must be AMS.conf.

Configuration Resources

The AMS installation also provides resources to expedite configuration. Find these files in the $AMS_HOME/samples directory:

resources/AMS-sample.properties

An example properties file that can be passed on the command line with the --substitutionfile option. This file contains all the substitution variables in the AMS.conf file, with each having the default value of its associated property.

resources/AMS-sample.conf

A superset of the AMS.conf file that includes commented syntax for every HOCON configuration property. Copy configuration properties from this file to your AMS.conf file to refine your configuration. Located in $AMS_HOME/samples/resources.

scripts/generate-KeyStore

This script provides guidelines to generate the KeyStore and certificate files for a Java KeyStore. The script prompts for the host and password. Using this information, the KeyStore and certificate files are generated using the Java keytool application.

AMS Configuration Properties at High Level

AMS configuration is organized into the following categories.

Decryption

This property defines a path to a master secret file, which can be absolute or relative to the current working directory, or within the resource path.

Database

The path to the database file and the user name and password to access the file.

Client API Listener

The client API listener specifies the TCP port number on which the AMS server listens and whether this port uses secure (TLS) communication.

To enable secure communications, change the ClientAPIListener.secure property from false to true and the ClientAPIListener.portNumber to the port number on which AMS should listen. Since AMS listens on a single port, it is technically possible to leave the port number unchanged. However, convention dictates that secure servers listen on different ports than non-secure servers, so it is good practice to change the port number when enabling secure communication.

The default port is 2185 (non-secure).

Communication Security

When using secure communication, a keystore file, keystore password, and key password are required. The configuration underpinnings for two-way (client) authentication are in place, though the AMS server currently supports only one-way (server) authentication.

You are expected to provide your own keystore file containing a private key and a certificate and that properly identifies the AMS host name. The CommunicationSecurity.keyStore property points to the user-supplied keystore file. The CommunicationSecurity.keyStorePassword and CommunicationSecurity.keyPassword properties provide the password of the keystore file and the password of the private key within that file, respectively.

Authentication Realms

AMS validates the identity of each user prior to allowing the user to perform actions. AMS supports the following authentication realms — essentially collections of user, password, and role information — for this purpose:

Local

When configured for local realm authentication, the user, password, and role (in other words, the principal) information are stored directly in the template HOCON configuration file, or in another AMS configuration file included by the template. The local authentication realm is used to seed users and roles in the AMS persistence realm. Once the user's information is seeded, AMS ignores the entry upon server restart; changing existing user passwords or roles must be performed using the web UI.

See AMS Configuration Properties in-Depth.

LDAP

When configured for LDAP authentication, AMS consults an LDAP server to validate the identity of the AMS user. The AMS configuration file provides the information required by AMS to access the LDAP server, including its host name, port number, and various search paths and LDAP attributes. See AMS Configuration Properties in-Depth.

AMS Persistence

AMS maintains a database of projects, artifacts, and related metadata. AMS can be configured to use the persistence layer for user authentication and authorization as well. In which case user, role, and permission information are stored in the persistence layer.

The seeding of users and roles from the local authentication realm to the AMS persistence realm is a process that happens automatically every time the AMS server starts. No explicit action is required, aside from starting the server itself.

OpenID Connect

The OpenIDConnectAuthenticationRealm enables single sign-on through an ID provider. See Configuring Single Sign-On.

Role-to-Privilege Mappings

Once AMS identifies a user, it consults a map of role-to-privilege information to determine whether the user's requested actions are permitted. On startup, the AMS copies this map from the template configuration file to its database. Administrators can then use the web UI to add, remove, or change roles and their permissions. Roles that are deleted will be re-added on the next start-up if they remain present in the configuration file.

Source Control Management

AMS supports artifacts imported from Git or Subversion source control management (SCM) repositories. Artifacts in SCM-sourced projects are accessible through the AMS web client. Such artifacts are visible in the Workspace view and editable in the Artifact Editor.

Artifact Deployment

AMS supports artifact deployment to different machines that are discoverable through the discovery service.

If your AMS configuration is not set up for trusted hosts between StreamBase machines and AMS, you can create entries in the following AMS configuration file properties:

DeploymentServiceNames

Use this option if your StreamBase node and AMS server reside in the same subnet. Service name can be either a StreamBase Runtime cluster or node name.

DeploymentServiceAddresses

Use this option (AMS 1.5.0 and above) if your StreamBase node and AMS server do not reside in the same subnet. Service address is a combination of host name and port for the service.

[Note]Note

Trusted hosts are configured on the StreamBase side, not the AMS side. See the StreamBase Configuration Guide in the TIBCO Streaming® documentation for details.

AMS Configuration Properties in-Depth

The following section describes configuration properties, usage, and syntax examples, where applicable.

com.tibco.ep.ams.configuration

Mandatory configuration file header line, followed by an open brace "{". The file must end with the matching close brace.

com.tibco.ep.ams.configuration = {
...
...
}
Database

The access information to the AMS database.

databaseType

The type of database (default: H2_EMBEDDED). Valid values: H2_EMBEDDED, POSTGRES.

driverClass

The class name of the database driver. When providing your own JDBC Driver, the Driver class and JAR must be in the classpath and the class name must be specified here. Default values are based on the specified databaseType:

  • H2_EMBEDDED = org.h2.jdbcx.JdbcDataSource

  • POSTGRES = org.postgresql.ds.PGSimpleDataSource

driverClass = "org.h2.jdbcx.JdbcDataSource"
filePath

The file path to the database can be absolute or relative to the current working directory (default: data/ams-h2-persistence). This property is only used when the databaseType property represents a file-based database.

filePath = "data/ams-h2-persistence"
hostPort

The host-name and port-number to the database (format: host-name:port-number, default: localhost:5432). Both the host-name and port-number must be specified. Use this property only when the databaseType represents a URL-based database.

hostPort = "localhost:5432"
databaseName

The name of the database (default: tibco-ams). Use this property only when the databaseType represents a URL-based database.

databaseName = "tibco-ams"
userName

The user name to access the database (default: sa). This property is encryptable as described in Encrypting AMS Configuration Data.

userName = "sa"
password

The password of the user.This property is encryptable as described in Encrypting AMS Configuration Data.

password = ""
Decryption

The path to the master secret file can be absolute, relative to the current working directory, or within the resource path.

masterSecretFile

Specify the file containing the master secret. A master secret file is generated using two AMS commands:

  • Create the KeyStore that will contain the master secret: ams_server --secret create --keystore <keystore-file>

  • Extract the master secret from the KeyStore into a file: ams_server --secret generate --keystore <keystore-file> --mastersecretfile master-secret-file

masterSecretFile = 
Linux absolute example: "/app-data/ams/keystores/MasterSecret.data"
Linux relative example: "../ams/keystores/MasterSecret.data"
Windows absolute example: "C:\\app-data\\ams\\keystores\\MasterSecret.data"
Windows relative example: "..\\ams\\keystores\\MasterSecret.data"
[Note]Note

Since Windows uses the backslash \ character, HOCON formatting requires two \\ for Windows paths (backslash is the escape character). For any OS, use double quotes around the path value.

ClientAPIListener

The port the AMS server listens on and whether that port is configured for secure (TLS) communication.

portNumber

TCP port for the client API to listen on. This property is optional. The default value is 2185 (non-secure) and the range is 1024 to 65535. AMS recommends using port 2443 when secure communication is required (which therefore requires setting the secure property, below, to true).

portNumber = 2185
secure

A secure-transport indicator. When true, use TLS to secure communication to the client; when false do not. Enabling secure communication requires that the engine have a secure communication configuration, or this indicator value is ignored. This property is optional and its default value is false.

secure = false
CommunicationSecurity

The KeyStore file, KeyStore password, and key password to use when using secure (TLS) communication.

keyStore

The KeyStore file. The file must be in the resource path. TIBCO recommends placing the file in: $AMS_HOME/conf. You can generate the KeyStore using the Java keytool.

keyStore = "localhost.jks"
keyStorePassword

KeyStore password, used to access the KeyStore contents. This property is encryptable as described in Encrypting AMS Configuration Data.

keyStorePassword = ""
keyPassword

The password of the alias-key. This property is encryptable as described in Encrypting AMS Configuration Data.

keyPassword = ""
clientAuthentication

Client authentication KeyStore file, KeyStore password, and cipher types.

trustStore

The trust-store KeyStore file. The file must be in the resource path. TIBCO recommends placing the file in: $AMS_HOME/conf. The KeyStore and algorithm are either the Java defaults (JKS and RSA, respectively) or in the Security properties file. You can generate the KeyStore using the Java keytool.

trustStore = "localhost.jks"
trustStorePassword

The password of the trustStore's KeyStore.

trustStorePassword = ""
cipherSuites

An array of cipher suites that can be used for TLS encryption.

cipherSuites = [
 "SSL_RSA_WITH_RC4_128_MD5"
 "SSL_RSA_WITH_RC4_128_SHA"
]
LocalAuthenticationRealm

The array of principals. On AMS server start-up, the principals are added as users with the specified roles when the username does not already exist. When the username already exists, the element in the array is ignored (cannot be used to change user passwords or roles). Administration of existing users, passwords, and roles are managed through the AMS UI or API.

principals

An array of zero or more user names, passwords, and their roles. This property is optional and has no default value.

userName

AMS user name. This property is required and cannot be an empty string. This property is encryptable as described in Encrypting AMS Configuration Data.

password

AMS user password. This property is encryptable as described in Encrypting AMS Configuration Data.

roles

An array of zero or more role names of which the user is a member. For more information about roles, see User Roles.

principals = [
  {
     userName = "admin"
     password = "admin"
     roles = ["AMSAdmin"]
  }
  {
     userName = "deploy"
     password = "deploy"
     roles = ["AMSDeploy"]
  }
  {
     userName = "nopriv"
     password = "nopriv"
     roles = []
  }
]
LDAPAuthenticationRealm

The authentication system uses this property to log into the LDAP server to enumerate user roles and to authenticate users.

serverConnectAlgorithm

When multiple LDAP servers are specified in this realm, this property defines the order in which the servers are connected for authentication. To authenticate in a round robin (the default) fashion specify round-robin. To authenticate against LDAP servers until the first successfully authentication request specify first-hit.

serverConnectAlgorithm = "round-robin"
servers

AMS currently supports at most one LDAP server. See the following descriptions of the Binding Components.

authenticationCredentials

The user used by the authentication system to log into the LDAP server and query for principal or role information.

userName

The user name used by the authentication system to log in to the LDAP server. This property is required.

userName = "CN=Administrator,CN=Users,DC=mycompany,DC=com"
password

The password used by the authentication system to log in to the LDAP server. This property is required. This property is encryptable as described in Encrypting AMS Configuration Data.

password = ""
host

The LDAP server's host name. This property is optional and its default value is localhost.

host = "ldap.example.com"
portNumber

The LDAP server's port to connect to AMS. This property is optional and its default value is 389.

portNumber = 389
secure

When set to true, the LDAPS protocol is used. Otherwise, the LDAP protocol is used.

secure= true
principalRoot

A list of Distinguished Names under which principals are searched for during search-based authentication or user ID-to-DN conversion. This property is required.

principalRoot = "CN=Users,DC=mycompany,DC=com"
principalSearch

The key name and index within the LDAP to use when looking up principals. This property is required.

principalSearch = "cn={0}"
roleRoot

A list of Distinguished Names under which roles are searched for. This property is required.

roleRoot = "CN=Groups,DC=example,DC=com"
roleSearch

The LDAP filter expression used when searching for roles of which a principal is a member. The filter permits Java pattern substitution expressions:

  • {0} is bound to the input principal

  • {1} is bound to its corresponding DN

roleSearch = "distinguishedName={0}"
roleAttribute

Attribute of a role entry that is used to map to privileges. This property is required.

roleAttribute = "memberOf"
OpenIDConnectAuthenticationRealm

Configuration for the OpenID Connect Authentication Realm.

IdentityToAMSProfileBinding

Properties that control how identities are bound to AMS profiles after authenticating with an identity provider if no matching AMS profile is found.

bindAction

Configure the actions to take when no binding exists between an identity and an AMS profile. Valid values are:

FAIL

Fails the login request.

AUTO_CREATE

Default. Creates a new AMS profile using the configured OpenID Connect claim as the username.

SIGN_IN

Presents a login form to the user, who enters the credentials of an existing AMS profile, creating the binding between the identity and profile.

SIGN_IN_OR_SIGN_UP

Presents a login form in the web client to the user, who enters the credentials of an existing AMS profile or requests the creation of a new profile.

autoCreateUsernameClaim

The OpenID Connect claim used for the username of auto-created AMS profiles. Valid values include: email, name (username), and family_name (surname).

autoCreateUsernameClaim = "email"
autoCreateUserEnabled

Determines whether auto-created users, or users created through the sign-up form, are initially enabled. One of {true | false}. Default is false.

autoCreateUserEnabled = "false"
autoCreateDefaultRoles

A comma-delimited list of role(s) to assign to auto-created users. If empty, auto-created users are assigned no roles. An administrator would then have to assign one or more roles to the user through the web client.

autoCreateDefaultRoles = ""
autoCreateFilters

Zero or more filters to apply to auto-create AMS profile requests. A filter contains the name of a fully qualified Java path that conforms to the com.tibcp.ep.ams.auth.AMSAutoCreateFilter interface along with zero or more parameters associated with each filter.

In the array below, a filter is used to restrict the creation of AMS profiles to users within a specific email domain.

autoCreateFilters = [
  {
     javaClass = "com.tibco.ep.ams.auth.AMSAutoCreateEmailFilter"
     params = [
       {
         name = "domains"
         value = "example.com"
       }
     ]
IdentityProviders

Use this property to configure authentication against one or more OpenID Connect identity providers.

providers

Contains an array of one or more OpenID Connect identity providers.

Many organizations have one or more providers, including their own. For single sign-on to AMS to succeed, AMS also requires the identity provider configuration to be set up between your organization and your providers.

providers = [
  {
     name = "Google"
     issuer = "https://accounts.google.com"
     clientId = "place your Google client ID here"
     clientSecret = "place your Google client secret here"
  }
  {
     name = "Auth0"
     issuer = "https://example.auth0.com"
     clientId = "place your Auth0 client ID here"
     clientSecret = "place your Auth0 client secret here"
     subjectProviderMappings = [
       {
          subjectPrefix = "google-oauth2"
          provider = "Google"
       }
     ]
AMSRealmList

A comma-separated and/or line-separated list of Authentication Realms. When the realm name appears in the list, the realm is enabled using the configurations defined for the realm with this configuration. Valid values are:

LocalAuthenticationRealm
LDAPAuthenticationRealm
AMSPersistenceRealm
OpenIDConnectAuthenticationRealm
AMSRealmList = [
  LocalAuthenticationRealm, 
  LDAPAuthenticationRealm, AMSPersistenceRealm, 
  OpenIDConnectAuthenticationRealm]            
RoleToPrivilegeMappings

The array of role-permission mappings. On AMS server start-up, the privileges are added as roles with the specified permissions when the role-name does not already exist. When the role-name already exists, the element in the array is ignored (cannot be used to change role permissions). Administration of existing roles and permissions are managed through the AMS web client or API. See User Access Control.

TIBCO recommends all privileges referenced in the LocalAuthenticationRealm configuration have its associated privileges defined here.

privileges

An associative array of AMS privileges keyed by role. The default below defines the AMSAdmin role with all privileges included as well as the AMSDeploy role:

privileges = {
  AMSAdmin = [
    {
       privilege = "*"
    }
  ]
  AMSDeploy = [
    {
       privilege = "artifact:deploy"
       resource = "MyProject/MyArtifact"
    }
  ]
}
DeploymentServiceNames

Enables deployment of artifacts to StreamBase nodes that are within the same subnet as AMS. The array of filters containing StreamBase service names from which to accept deployment requests. When empty, the AMS responds to all services.

filter

The service names used for filter matching. These service names can contain Java-compatible wildcards. For example:

filter = [my-company-service, my-company-*]
services

The array of StreamBase service credentials. These credentials are used when deploying artifacts using a Target Type of StreamBase Service Name. For example:

services = [
  {
     serviceName = "example"             // The StreamBase service name 
     userName = "guest"                  // The username used to access the service
     password = ""                       // The password used to access the service 
                                         //  (see: This property is encryptable as described 
                                         //   in Encrypting AMS Configuration Data.)
  }
]
DeploymentServiceAddresses

An array of service addresses. Use this object to enable deployment of artifacts to StreamBase nodes that are outside the AMS subnet. On AMS server start-up, a service address is added to the deployment service addresses when the address name does not already exist. When the address name already exists, the "duplicated" entry is ignored (meaning, it cannot be used to change service address details).

Service Addresses configured in the AMS.conf file are available for use when you define an artifact deployment descriptor in the web client.

serviceAddress

The service address configuration.

addressName

For example:

addressName = "example"
hostName

The host name of the service. This can be a simple host name, a fully qualified DNS name, or an IPv4 or IPv6 address. AMS does not validate the format. For example:

hostName = "example.com"
adminPort

The administration port of the service. This value must be an integer in the range: 1024 to 65535. For example:

adminPort = 56789
userName

The user's name for authentication (non-trusted host). When provided, the password property must also have a value. For example:

userName = "node-user"
userPassword

The user's password (see this page regarding encrypting sensitive data). When provided, the userName property must also have a value (non-trusted host). For example:

userPassword = "node-password"
description

The service address description.

SourceControlManagement

An array defining one or more source control management repositories, such as Git and Subversion.

name

A unique name for this repository instance.

enabled

Set to true to enable this repository and false otherwise. Default is false.

type

Valid values are GIT, SUBVERSION, or CUSTOM.

javaClass

Required only when type == CUSTOM.

url

Repository URL.

branch

Repository branch name (defaults to master).

username

Repository username. This property is encryptable as described in Encrypting AMS Configuration Data.

password

Repository password. This property is encryptable as described in Encrypting AMS Configuration Data.

executable

Path to Subversion, Git, or custom executable.

pullIntervalSeconds

Interval in seconds between attempts to pull repository updates into AMS, or 0 to disable periodic pulling.

SourceControlManagement {
  repositories = [
    {  
       name = "REPO1"                                         
       enabled = true                                          
       type = "GIT"                                            
       javaClass = ""                                          
       url = "https://svn.example.com/path/to/repository"    
       branch = "master"                                       
       username = "myusername"                                 
       password = ""                                           
       executable = "/usr/bin/git"                             
       pullIntervalSeconds = 0                                 
     }
  ]
}

AMS Configuration File Example

The following is the supplied AMS.conf file, which provides the minimum required information to configure AMS.

// Site-specific modifications to the AMS server configuration.
// NOTE - Sensitive Data:
//   Sensitive data (e.g. passwords) can be encrypted, enciphered, or in clear-text.
//     Encrypted:  As of AMS 1.4.0, encrypted values are supported within the AMS
//                 configuration and created using the following command:
//                   ams-server --secret encrypt <options>
//                 Data encrypted in this way will all start with "#!!".
//                 See the "ams-server" help for details.
//
//     Enciphered: As of AMS 1.4.0, "ams-server --cipher" has been deprecated.
//                 Enciphered values were created using the following command:
//                   ams-server --cipher <data>
//                 The user can optionally add the prefix "#!" to the beginning
//                 of the enciphered value (acts as a hint to the decipher process).
//                 Enciphered values continue to be supported within the AMS
//                 configuration, but these values should be regenerated using
//                 the "ams-server --secret encrypt" command.
//
//     Clear-Text: Clear-text values continue to be supported within the AMS
//                 configuration.

// When the client does not override the AMS server configuration,
// basic users with their permissions are created.
com.tibco.ep.ams.configuration {

    // Users with their passwords and roles.
    LocalAuthenticationRealm = {
        // The array of principals.  On AMS server start-up, the principals are added as users with the
        // specified roles when the user-name does not already exist.  When the user-name already exists,
        // the element in the array is ignored (can not be used to change user passwords or roles).
        principals = [
            {
                userName = "admin"          // The user's name
                password = "admin"          // The user's password (see: NOTE - Sensitive Data)
                roles = ["AMSAdmin"]        // Array of roles (see: RoleToPrivilegeMappings) 
            }
            {
                userName = "deploy"         // The user's name
                password = "deploy"         // The user's password (see: NOTE - Sensitive Data)
                roles = ["AMSDeploy"]       // Array of roles (see: RoleToPrivilegeMappings)
            }
            {
                userName = "nopriv"         // The user's name
                password = "nopriv"         // The user's password (see: NOTE - Sensitive Data)
                roles = []                  // Array of roles (no roles need be specified)
            }
        ]
    }

    // The map of roles to permissions.
    // The privilege value contains a combination of the permission types and actions:
    //   manage_server (no action required)
    //   manage_permissions (no action required)
    //   artifact : delete | deploy | read | write | * [: <artifact-name>]
    //   group : delete | read | write | * [: <group-name>]
    //   project : approve | delete | import | read | write | * [: <project-name>]
    //   * (all permissions)
    RoleToPrivilegeMappings = {
        // The array of role/permission mappings.  On AMS server start-up, the privileges are added as roles
        // with the specified permissions when the role-name does not already exist.  When the role-name
        // already exists, the element in the array is ignored (can not be used to change role permissions).
        privileges = {
            // The name of the role.
            AMSAdmin = [
                // The array of permissions associated with the role.
                {
                    privilege = "*"
                }
            ]

            // The name of the role.
            AMSDeploy = [
                // The array of permissions associated with the role.
                {
                    privilege = "artifact:deploy"
                }
            ]
        }
    }
}

Apple Text Editor Advisory when Editing Configuration Files

When using Apple TextEdit, ensure that all configuration file values requiring quotes use straight quotes ("...") and not smart quotes (“...”). Smart quotes are treated as data and not as delimiters for HOCON values.

AMS configuration files use straight quotes to encapsulate values. Apple's TextEdit application is a rich text editor that uses smart quotes by default. If using TextEdit or any rich text editor, ensure the editor is set to use straight quotes.