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:
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
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
.
The AMS installation also provides resources to expedite configuration. Find these files in the $AMS_HOME/samples
directory:
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.
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
.
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 is organized into the following categories.
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.
The path to the database file and the user name and password to access the file.
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).
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.
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:
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.
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 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.
The OpenIDConnectAuthenticationRealm enables single sign-on through an ID provider. See Configuring Single Sign-On.
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.
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.
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:
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.
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 | |
---|---|
Trusted hosts are configured on the StreamBase side, not the AMS side. See the |
The following section describes configuration properties, usage, and syntax examples, where applicable.
Mandatory configuration file header line, followed by an open brace "{
". The file must end with the matching close brace.
com.tibco.ep.ams.configuration = { ... ... }
The access information to the AMS database.
The type of database (default: H2_EMBEDDED). Valid values: H2_EMBEDDED, POSTGRES.
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"
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"
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"
The name of the database (default: tibco-ams). Use this property only when the databaseType
represents a URL-based database.
databaseName = "tibco-ams"
The user name to access the database (default: sa). This property is encryptable as described in Encrypting AMS Configuration Data.
userName = "sa"
The password of the user.This property is encryptable as described in Encrypting AMS Configuration Data.
password = ""
The path to the master secret file can be absolute, relative to the current working directory, or within the resource path.
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 | |
---|---|
Since Windows uses the backslash |
The port the AMS server listens on and whether that port is configured for secure (TLS) communication.
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
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
The KeyStore file, KeyStore password, and key password to use when using secure (TLS) communication.
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"
KeyStore password, used to access the KeyStore contents. This property is encryptable as described in Encrypting AMS Configuration Data.
keyStorePassword = ""
The password of the alias-key. This property is encryptable as described in Encrypting AMS Configuration Data.
keyPassword = ""
Client authentication KeyStore file, KeyStore password, and cipher types.
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"
The password of the trustStore's KeyStore.
trustStorePassword = ""
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" ]
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.
An array of zero or more user names, passwords, and their roles. This property is optional and has no default value.
AMS user name. This property is required and cannot be an empty string. This property is encryptable as described in Encrypting AMS Configuration Data.
AMS user password. This property is encryptable as described in Encrypting AMS Configuration Data.
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 = [] } ]
The authentication system uses this property to log into the LDAP server to enumerate user roles and to authenticate users.
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"
AMS currently supports at most one LDAP server. See the following descriptions of the Binding Components.
The user used by the authentication system to log into the LDAP server and query for principal or role information.
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"
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 = ""
The LDAP server's host name. This property is optional and its default value is localhost
.
host = "ldap.example.com"
The LDAP server's port to connect to AMS. This property is optional and its default value is 389.
portNumber = 389
When set to true, the LDAPS protocol is used. Otherwise, the LDAP protocol is used.
secure= true
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"
The key name and index within the LDAP to use when looking up principals. This property is required.
principalSearch = "cn={0}"
A list of Distinguished Names under which roles are searched for. This property is required.
roleRoot = "CN=Groups,DC=example,DC=com"
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}"
Attribute of a role entry that is used to map to privileges. This property is required.
roleAttribute = "memberOf"
Configuration for the OpenID Connect Authentication Realm.
Properties that control how identities are bound to AMS profiles after authenticating with an identity provider if no matching AMS profile is found.
Configure the actions to take when no binding exists between an identity and an AMS profile. Valid values are:
Fails the login request.
Default. Creates a new AMS profile using the configured OpenID Connect claim as the username.
Presents a login form to the user, who enters the credentials of an existing AMS profile, creating the binding between the identity and profile.
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.
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"
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"
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 = ""
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" } ]
Use this property to configure authentication against one or more OpenID Connect identity 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" } ]
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]
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.
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" } ] }
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.
The service names used for filter matching. These service names can contain Java-compatible wildcards. For example:
filter = [my-company-service, my-company-*]
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.) } ]
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.
The service address configuration.
For example:
addressName = "example"
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"
The administration port of the service. This value must be an integer in the range: 1024 to 65535. For example:
adminPort = 56789
The user's name for authentication (non-trusted host). When provided, the password
property must also have a value. For example:
userName = "node-user"
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"
The service address description.
An array defining one or more source control management repositories, such as Git and Subversion.
A unique name for this repository instance.
Set to true to enable this repository and false otherwise. Default is false.
Valid values are GIT, SUBVERSION, or CUSTOM.
Required only when type == CUSTOM.
Repository URL.
Repository branch name (defaults to master).
Repository username. This property is encryptable as described in Encrypting AMS Configuration Data.
Repository password. This property is encryptable as described in Encrypting AMS Configuration Data.
Path to Subversion, Git, or custom executable.
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 } ] }
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" } ] } } }
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.