Authenticating with mTLS

Device identities use mutual-TLS (mTLS) to authenticate and retrieve Identity tokens. To connect to an mTLS-protected endpoint, the client (e.g., device) must present a certificate confirming its Identity.

Trimble Cloud enables providers the capability for the users to create IoT device identities and corresponding certificates by consuming the Profiles APIs. When a device profile is created, Profiles engages with Identity to create a matching device identity. After a device identity and mutual-TLS certificate have been provisioned, that certificate and device ID can retrieve access tokens via the mutual-TLS token endpoint.

• Staging: https://mtls.stage.id.trimblecloud.com

• Production: https://mtls.id.trimble.com

How to Configure your CA

The device must present a certificate to retrieve a TID access token and make a POST request to the mutual-TLS enabled token endpoint.

Below is a Python example; the pem_path is the path to a certificate issued by a TID-recognized CA. Note that the scope must target a valid application name. For more information on configuring TID applications, see our Identity v4 documentation.

import jwt
import requests

def get_token_with_cert(device_id, pem_path, application_id=None):
   '''
   Invoke the mutual TLS endpoint and retrieve a bearer token
   '''
   mtls_token_endpoint = 'https://mtls.stage.id.trimblecloud.com/oauth/token'

   payload_params = {'grant_type': 'urn:trimble:params:oauth:x509-cert',
                     'scope': 'test-123:openid',
                     'device_id': device_id}

   if application_id:
       payload_params['application_id'] = application_id

   payload = '&'.join([f'{k}={v}' for k, v in payload_params.items()])
   res = requests.post(mtls_token_endpoint,
                       data=payload,
                       cert=pem_path)
   res.raise_for_status()
   bearer_token = res.json()
   print(jwt.decode(bearer_token['access_token'],
                    options={'verify_signature': True,
                             'verify_aud': True}))