Understanding Solace Messaging Credentials

This topic describes the credentials of a Solace Messaging service instance.

About Credentials

Credentials are required so an app can gain access to a Solace Messaging service instance.

  • Credentials created by a binding are accessible in the VCAP_SERVICES environment variable of Pivotal Cloud Foundry (PCF) deployed app.
  • Credentials created by a service key are the responsibility of a developer to pass to an app.

For examples of different ways that developers can configure their apps to consume the credentials from VCAP_SERVICES or service keys, see the sample app GitHub repository.

Example VCAP_SERVICES Environment Variable

The VCAP_SERVICES environment variable is a JSON document, and follows the format of the example below:

{
 "VCAP_SERVICES": {
  "solace-messaging": [
   {
    "credentials": {
     "clientPassword": "6747475d-8bbf-4caf-94f5-c77abb871824",
     "clientUsername": "v001.cu000193",
     "jmsJndiTlsUris": [
      "smfs://192.168.16.99:7003",
      "smfs://192.168.16.98:7003"
     ],
     "jmsJndiUris": [
      "smf://192.168.16.99:7000",
      "smf://192.168.16.98:7000"
     ],
     "managementHostnames": [
      "medium-ha-vmr-1.sys.pie-ci-latest-01.cfplatformeng.com",
      "medium-ha-vmr-0.sys.pie-ci-latest-01.cfplatformeng.com"
     ],
     "managementPassword": "5c21f2857c504d3ca70de97d1aec47d7",
     "managementUsername": "v001-mgmt",
     "mqttTlsUris": [
      "ssl://192.168.16.99:7009",
      "ssl://192.168.16.98:7009"
     ],
     "mqttUris": [
      "tcp://192.168.16.99:7008",
      "tcp://192.168.16.98:7008"
     ],
     "mqttWsUris": [
      "ws://192.168.16.99:7010",
      "ws://192.168.16.98:7010"
     ],
     "mqttWssUris": [
      "wss://192.168.16.99:7011",
      "wss://192.168.16.98:7011"
     ],
     "msgVpnName": "v001",
     "publicJmsJndiTlsUris": [
      "smfs://tcp.pie-ci-latest-01.cfplatformeng.com:3274",
      "smfs://tcp.pie-ci-latest-01.cfplatformeng.com:11164"
     ],
     "publicJmsJndiUris": [
      "smf://tcp.pie-ci-latest-01.cfplatformeng.com:57154",
      "smf://tcp.pie-ci-latest-01.cfplatformeng.com:14242"
     ],
     "publicMqttTlsUris": [
      "ssl://tcp.pie-ci-latest-01.cfplatformeng.com:27576",
      "ssl://tcp.pie-ci-latest-01.cfplatformeng.com:5998"
     ],
     "publicMqttUris": [
      "tcp://tcp.pie-ci-latest-01.cfplatformeng.com:4050",
      "tcp://tcp.pie-ci-latest-01.cfplatformeng.com:55665"
     ],
     "publicSmfHosts": [
      "tcp://tcp.pie-ci-latest-01.cfplatformeng.com:57154",
      "tcp://tcp.pie-ci-latest-01.cfplatformeng.com:14242"
     ],
     "publicSmfTlsHosts": [
      "tcps://tcp.pie-ci-latest-01.cfplatformeng.com:3274",
      "tcps://tcp.pie-ci-latest-01.cfplatformeng.com:11164"
     ],
     "restTlsUris": [
      "https://192.168.16.99:7007",
      "https://192.168.16.98:7007"
     ],
     "restUris": [
      "http://192.168.16.99:7006",
      "http://192.168.16.98:7006"
     ],
     "smfHosts": [
      "tcp://192.168.16.99:7000",
      "tcp://192.168.16.98:7000"
     ],
     "smfTlsHosts": [
      "tcps://192.168.16.99:7003",
      "tcps://192.168.16.98:7003"
     ],
     "smfZipHosts": [
      "tcp://192.168.16.99:7001",
      "tcp://192.168.16.98:7001"
     ],
     "webMessagingTlsUris": [
      "https://192.168.16.99:7005",
      "https://192.168.16.98:7005"
     ],
     "webMessagingUris": [
      "http://192.168.16.99:7004",
      "http://192.168.16.98:7004"
     ]
    },
    "label": "solace-messaging",
    "name": "sol",
    "plan": "medium-ha",
    "provider": null,
    "syslog_drain_url": null,
    "tags": [
     "solace",
     "solace-messaging",
     "rest",
     "mqtt",
     "mq",
     "queue",
     "event-streaming",
     "amqp",
     "jms",
     "messaging",
     "publish-subscribe",
     "message-queuing",
     "request-reply"
    ],
    "volume_mounts": []
   }
  ]
 }
}

If the environment variable VCAP_SERVICES contains more than one service binding, you must search for the Solace Messaging service instance. You can search for the service instance statically by looking up a pre-defined name attribute or dynamically through the tags or label properties. See the Solace sample app for more information about achieving this.

Example Service Key Credentials

The credentials of a service key are a JSON document and are the same format as the “credentials” portion seen in the VCAP_SERVICES.

The following credentials are those of a service key created for the same service instance as the one used for the VCAP_SERVICES example.

{    
     "clientPassword": "89876776-124h-2caf-24x4-ef86g4577584",
     "clientUsername": "v001.cu000188",
     "jmsJndiTlsUris": [
      "smfs://192.168.16.99:7003",
      "smfs://192.168.16.98:7003"
     ],
     "jmsJndiUris": [
      "smf://192.168.16.99:7000",
      "smf://192.168.16.98:7000"
     ],
     "managementHostnames": [
      "medium-ha-vmr-1.sys.pie-ci-latest-01.cfplatformeng.com",
      "medium-ha-vmr-0.sys.pie-ci-latest-01.cfplatformeng.com"
     ],
     "managementPassword": "5c21f2857c504d3ca70de97d1aec47d7",
     "managementUsername": "v001-mgmt",
     "mqttTlsUris": [
      "ssl://192.168.16.99:7009",
      "ssl://192.168.16.98:7009"
     ],
     "mqttUris": [
      "tcp://192.168.16.99:7008",
      "tcp://192.168.16.98:7008"
     ],
     "mqttWsUris": [
      "ws://192.168.16.99:7010",
      "ws://192.168.16.98:7010"
     ],
     "mqttWssUris": [
      "wss://192.168.16.99:7011",
      "wss://192.168.16.98:7011"
     ],
     "msgVpnName": "v001",
     "publicJmsJndiTlsUris": [
      "smfs://tcp.pie-ci-latest-01.cfplatformeng.com:3274",
      "smfs://tcp.pie-ci-latest-01.cfplatformeng.com:11164"
     ],
     "publicJmsJndiUris": [
      "smf://tcp.pie-ci-latest-01.cfplatformeng.com:57154",
      "smf://tcp.pie-ci-latest-01.cfplatformeng.com:14242"
     ],
     "publicMqttTlsUris": [
      "ssl://tcp.pie-ci-latest-01.cfplatformeng.com:27576",
      "ssl://tcp.pie-ci-latest-01.cfplatformeng.com:5998"
     ],
     "publicMqttUris": [
      "tcp://tcp.pie-ci-latest-01.cfplatformeng.com:4050",
      "tcp://tcp.pie-ci-latest-01.cfplatformeng.com:55665"
     ],
     "publicSmfHosts": [
      "tcp://tcp.pie-ci-latest-01.cfplatformeng.com:57154",
      "tcp://tcp.pie-ci-latest-01.cfplatformeng.com:14242"
     ],
     "publicSmfTlsHosts": [
      "tcps://tcp.pie-ci-latest-01.cfplatformeng.com:3274",
      "tcps://tcp.pie-ci-latest-01.cfplatformeng.com:11164"
     ],
     "restTlsUris": [
      "https://192.168.16.99:7007",
      "https://192.168.16.98:7007"
     ],
     "restUris": [
      "http://192.168.16.99:7006",
      "http://192.168.16.98:7006"
     ],
     "smfHosts": [
      "tcp://192.168.16.99:7000",
      "tcp://192.168.16.98:7000"
     ],
     "smfTlsHosts": [
      "tcps://192.168.16.99:7003",
      "tcps://192.168.16.98:7003"
     ],
     "smfZipHosts": [
      "tcp://192.168.16.99:7001",
      "tcp://192.168.16.98:7001"
     ],
     "webMessagingTlsUris": [
      "https://192.168.16.99:7005",
      "https://192.168.16.98:7005"
     ],
     "webMessagingUris": [
      "http://192.168.16.99:7004",
      "http://192.168.16.98:7004"
     ]
}

Note about the examples: Notice how all service scoped fields are the same and that only the app scoped fields are changed. The clientUsername and clientPassword changed. For this example, two collaborating apps are accessing the same service instance, one app is in PCF using `VCAP_SERVICES` and the other is outside cloud foundry using a service key.

Credentials Contents

The availability of some of the Credentials fields and their contents will depend on the enabled or disabled features of the Solace tile at installation time as well as the plan type of the service instance.

If a VMR service instance was created using the medium-ha or large-ha service plan then it will be highly available. In these cases there will be two seperate service URIs for each of the available transports as shown in the example above. Connecting apps use both of these URIs by reconnecting to the other if one of them becomes unavailable. This is known as the host list HA failover mechanism and more information can be found in Solace documentation.

If a VMR service instance was created using the shared, large, or community service plan then it will not be highly available. In these cases, there will only be one URI for each of the supported transports.

When LDAP is enabled, and Management Access is set to LDAP Server, the managementUsername and managementPassword will not be available.

When LDAP is enabled, and Application Access is set to LDAP Server, the clientUsername and clientPassword will not be available. The tile installation has taken care of creating an LDAP profile, and setting it as the auth-type for each Message VPN. However an administrator with Management Access needs to create the necessary LDAP Groups on the VMR for each Message VPN using SEMP or SolAdmin in order to grant the necessary access to the app. For more documentation please see Configuring Client LDAP Authorization

When TCP Routes are enabled additional public fields will provide the connectivity details for that messaging protocol so it may be used from an external network source, such as the internet.

Credentials Fields

Field Applies to messaging protocol Description
clientUsername All except management (SEMP) The client username used to access the messaging services. Not available if Application Access is set to LDAP Server
clientPassword All except management (SEMP) The client password used to access the messaging services. Not available if Application Access is set to LDAP Server
msgVpnName JMS, SMF, and webMessaging The name of the VPN allocated to the app
jmsJndiUris JMS The JNDI provider URLs: InitialContext.PROVIDER_URL
jmsJndiTlsUris JMS The JNDI provider URLs: InitialContext.PROVIDER_URL
mqttUris MQTT The MQTT service URIs
mqttTlsUris MQTT The MQTT service TLS URIs
mqttWsUris MQTT The MQTT WebSocket URIs
mqttWssUris MQTT The MQTT WebSocket TLS URIs
restUris REST The REST endpoints base URIs
restTlsUris REST The REST TLS endpoints base URIs
smfHosts SMF The SMF HOST Session Property
smfTlsHosts SMF The SMF TLS HOST Session Property
smfZipHosts SMF The compressed SMF HOST Session Property
webMessagingUris Web Messaging The URLs used to connect the session (solclientjs), or the HOST Session Property (CCSMP, .NET API, and JAVA RTO)
webMessagingTlsUris Web Messaging The HTTPS URLs used to connect the session (solclientjs), or the HOST Session Property (CCSMP, .NET API, and JAVA RTO)
publicJmsJndiUris JMS The JNDI provider URLs: InitialContext.PROVIDER_URL. Available when TCP Routes is enabled
publicJmsJndiTlsUris JMS The JNDI provider URLs: InitialContext.PROVIDER_URL. Available when TCP Routes is enabled
publicMqttUris MQTT The MQTT service URIs. Available when TCP Routes is enabled
publicMqttTlsUris MQTT The MQTT service TLS URIs. Available when TCP Routes is enabled
publicMqttWsUris MQTT The MQTT WebSocket URIs. Available when TCP Routes is enabled
publicMqttWssUris MQTT The MQTT WebSocket TLS URIs. Available when TCP Routes is enabled
publicRestUris REST The REST endpoints base URIs. Available when TCP Routes is enabled
publicRestTlsUris REST The REST TLS endpoints base URIs. Available when TCP Routes is enabled
pulicSmfHosts SMF The SMF HOST Session Property. Available when TCP Routes is enabled
publicSmfTlsHosts SMF The SMF TLS HOST Session Property. Available when TCP Routes is enabled
pulibcSmfZipHosts SMF The compressed SMF HOST Session Property. Available when TCP Routes is enabled
pulicWebMessagingUris Web Messaging The URLs used to connect the session (solclientjs), or the HOST Session Property (CCSMP, .NET API, and JAVA RTO). Available when TCP Routes is enabled
publicWebMessagingTlsUris Web Messaging The HTTPS URLs used to connect the session (solclientjs), or the HOST Session Property (CCSMP, .NET API, and JAVA RTO). Available when TCP Routes is enabled
managementHostnames Management (SEMP) The DNS hostnames associated with the service instance’s management service. These hostnames can be used by management apps external to PCF, for example SolAdmin, to connect to the VNR associated with the service instance
managementPassword Management (SEMP) The VPN’s administrative username. Not available if Management Access is set to LDAP Server
managementUsername Management (SEMP) The VPN’s administrative password. Not available if Management Access is set to LDAP Server

Messaging Protocols

The table above matches each field to the messaging protocol it uses. The Solace Messaging service supports the following messaging protocols:

Note: The app needs to provide the Message VPN when using the SMF, JMS, or Web Messaging protocols. As a result, the app needs to read the msgVpnName fields when using those protocols.

Each protocol can have multiple possible underlying transports. The field’s prefix specifies the protocol, while the infix specifies the transport underlying the protocol. For example, "mqttUris": ["tcp://192.168.132.14:7026"] specifies the MQTT protocol over TCP.

The app only needs one Host or Uris field to connect to the Message VPN, but which one it needs depends on the required protocol and transport combination.

The following list provides the available infixes:

  • Tls: TLS-encrypted
  • Ws: WebSocket
  • Wss: TLS-encrypted WebSocket
  • Zip: Compressed SMF (SMF with compression enabled)

For example, an app uses JMS plain text must read the following fields:

  • clientUsername
  • clientPassword
  • msgVpnName
  • jmsJndiUri

Management Protocol

The Solace Messaging service supports the Solace Element Management Protocol (SEMP) as its management protocol. To use SEMP or an management app such as SolAdmin that supports SEMP, the following fields are required:

  • managementUsername
  • managementPassword
  • managementHostnames

Usernames and Passwords

  • When Application Access is VMR Internal, the credentials required by the various messaging protocols are provided by clientUsername and clientPassword.
  • When Application Access is LDAP Server, the credentials required by the various messaging protocols is to be provided by the LDAP Administrator.

  • When Management Access is VMR Internal, the credentials required to manage the Message VPN are provided by managementUsername and managementPassword. For more information, see Managing the Message VPN.

  • When Management Access is LDAP Server, the credentials required to manage the Message VPN are to be provided by the LDAP Administrator.

Create a pull request or raise an issue on the source for this page in GitHub