Understanding Solace Messaging Credentials

This topic describes the credentials that an application bound to a Solace Messaging service instance gains access to. These credentials are stored in the VCAP_SERVICES environment variable. For examples of different ways that developers can configure their applications to consume the credentials, see the sample application GitHub repository.

Example 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 application for more information about achieving this.

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 2 seperate service URIs for each of the available transports as shown in the example above. Connecting applications 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.

The availability of some of the Credentials fields will depend on the enabled or disabled features of the Solace tile at installation time.

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 application. 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 application
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 applications 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 application needs to provide the Message VPN when using the SMF, JMS, or Web Messaging protocols. As a result, the application 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 application 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 application 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 application 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 the Managing the Message VPN topic.

  • 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