Soracom Endorse

Overview

Soracom Endorse is an authentication service that uses SIM authentication to validate network connections, and in turn issues tokens which can be used as access credentials. Endorse acts as an authentication provider, using a simple mechanism for issuing tokens and verifying token signatures, similar to identity-based smartcard authentication.

Tokens issued by Endorse certify that the device holding the token is using a valid Soracom IoT SIM, and has requested and received the token from the Endorse service using a secured cellular connection. As Endorse uses asymmetric (public-key) cryptography when generating token signatures, the authenticated device can present the token to a network resource (such as your server), which can then independently verify the validity of the token prior to granting access.

Each token contains a validity (timeout) period, and can also include the IoT SIM IMSI, device IMEI, and additional parameters for further authentication. Once issued, the token can also be used to authorize network connections over other interfaces, including Wifi.

Authentication Process

Endorse Mechanism

In typical usage, Endorse operates in the following manner:

  1. An IoT SIM device connects to a cellular network and requests a token from Endorse.
  2. Endorse issues a token and sends it to the device.
  3. The device sends its token signature to an endpoint, such as your server.
  4. The endpoint inspects the token signature, and requests the public key indicated in the token that was used by Endorse to generate the token.
  5. Using the public key, the endpoint independently verifies the validity of the token signature and confirms authentication.

Importantly, the initial token request and issuance occurs through the device's cellular connection, which allows Endorse to issue authentication tokens based on device IMSI, IMEI, and other parameters.

Once the device has received the token, it can then send it to the endpoint in response to an authentication challenge through any network connection, including cellular and wifi.

Token Format

Endorse issues tokens using the JSON Web Token (JWT) format. JWT is an open, industry standard method for representing claims between two parties, such as a client device requesting access to server resources. JWT is widely used in many industries, and JWT libraries are readily available for all major programming environments.

When implementing Endorse into your application, we recommend referring to JWT documentation and additional JWT resources in order to ensure proper implementation of JWT.

Website Integration

When integrating with HTTP-based resources (such as an intranet web server), Endorse also provides an issue-token-and-redirect behavior:

  1. An IoT SIM devices connects to a cellular network and accesses an Endorse URL, which contains a redirect_url query string or request body parameter.
  2. Endorse issues a token, but instead of sending the token back to the device, redirects the device to the redirect target with the token as part of an HTTP POST request.
  3. The target webserver receives the POST data, including the token, and can verify the validity of the token signature using the same process as above before granting access to web resources.

By redirecting the client to the URL specified in the redirect_url parameter with the token issued by Endorse, the web server can validate the token in order to grant access to web resources.

Free Tier

Soracom provides a free tier for Endorse with each Soracom account. Refer to the Pricing & Fee Schedule for more information.