Device Authentication Methods

How to setup your device to authenticate with Xively securely. Authentication Method must be set per Device Template.

Important: Once the device template is created, the Device Authentication method can’t be modified.
Important: All devices in a device template must use the same Device Authentication method.

Method One: Password based Authentication

The device authenticates by sending its Device ID as the MQTT Client ID, and its Device Secret as the MQTT Password. The MQTT Username can either be empty or the Device ID.

Note: Xively uses password-based authentication by default when authenticating with devices and device templates.

Xively must have the following when authenticating:

Calling parameters

Parameter
Description and value

Broker port

Connection port for TLS communication
Must be set to 8883

Broker address / Hostname

broker.xively.com

Client ID

See below for what to use

Username

See below for what to use

Password

See below for what to use

Last Will

Clean / Unclean

Default value: Clean

Keep Alive

Default value: 60 seconds

SSL/TLS

Enabled

Protocol

TLSv1.2

Response Parameters

Parameter
Description

Connect notification

Upon successful connection, a CONNECTED message is sent.
Common issues

  • Bad username or password: Check your credentials
  • Identifier rejected: Check your client id
  • Server unavailable: Check port or Xively status page

Method Two: X.509 Certificates

When using X.509 Certificates, the device authenticates by performing TLS client authentication using its X.509 Certificate, sending its Device ID as the MQTT Client ID. It is possible to use self-signed certificates as each device certificate must be registered in Xively.

For the X.509 Certificate authentication mode, you must connect to the following:

<account name>-tlsa.broker.xively.com (or.eu)
for example; mycompany.tlsa.broker.xively.eu

Important: Clients must use TLS Server Name Indication (SNI) on devices.

Setting up the X.509 Certification process

To setup an x.509 certificate, you must use APIs.

  1. Use a POST command with /api/v1/devices/templates and in the body parameters, set the authMethod to 1
{
 	 "accountId": "<account ID>",
 	 "name": "<name of your device template>",
 	 "authMethod": 1
}
  1. Use a POST command with /api/v3/access/mqtt-credentials and in the body parameters, set the following:
{
 "accountId": <account ID>,
 "entityType": "device",
 "entityId": <device ID>,
 "certificate": <certificate PEM>
}

What's Next

Find out more information on Xively's messaging broker

Messaging Broker