Token Verification

Tokens issued by Endorse use the JSON Web Token (JWT) format. A typical token issued by Endorse will look something like this:

{
  "token": "eyJraWQiOiJ2MS1hYmNkZWYwMDAwMDAwMDAwMDAwMDAwMDAxMjM0NTY3OC14NTA5LnBlbSIsImFsZyI6IlJTMjU2In0.eyJpc3MiOiJodHRwczovL3NvcmFjb20uaW8iLCJhdWQiOiJzb3JhY29tLWVuZG9yc2UtYXVkaWVuY2UiLCJleHAiOjE0NTExMTYzMDEsImp0aSI6ImhrSzdxTnlYekVNVkFYZlRxMU1CdUEiLCJpYXQiOjE0NTExMTYxMjEsIm5iZiI6MTQ1MTExNjA2MSwic3ViIjoic29yYWNvbS1lbmRvcnNlIiwic29yYWNvbS1lbmRvcnNlLWNsYWltIjp7Imltc2kiOiIyOTUwMDAwMTIzNDU2NzgiLCJpbWVpIjoiODAwMDAwMDEyMzQ1Njc4In19.abcdef******************12345678"
}

Paying close attention to the token string, you will notice that the token is divided into three sections, each separated by a .. These sections make up the JWT token format: {HEADER}.{PAYLOAD}.{SIGNATURE}.

To verify the token, we need to divide the token into each of its sections.

Token Sections

Header

In our token, we can extract the first section delimited by a ., which gives us the following string:

eyJraWQiOiJ2MS1hYmNkZWYwMDAwMDAwMDAwMDAwMDAwMDAxMjM0NTY3OC14NTA5LnBlbSIsImFsZyI6IlJTMjU2In0

This is a Base64-encoded string. By decoding this string, we get the following JSON data:

{
  "kid": "v1-abcdef00000000000000000012345678-x509.pem",
  "alg": "RS256"
}

This data tells us which key Endorse used to sign the token. The public keys used for verifying signatures are stored on the Soracom Endorse Public Key repository: https://s3-ap-northeast-1.amazonaws.com/soracom-public-keys/.

For our sample key, we would download the following file:

https://s3-ap-northeast-1.amazonaws.com/soracom-public-keys/v1-abcdef00000000000000000012345678-x509.pem

Payload

The second section is also a Base64-encoded string:

eyJpc3MiOiJodHRwczovL3NvcmFjb20uaW8iLCJhdWQiOiJzb3JhY29tLWVuZG9yc2UtYXVkaWVuY2UiLCJleHAiOjE0NTExMTYzMDEsImp0aSI6ImhrSzdxTnlYekVNVkFYZlRxMU1CdUEiLCJpYXQiOjE0NTExMTYxMjEsIm5iZiI6MTQ1MTExNjA2MSwic3ViIjoic29yYWNvbS1lbmRvcnNlIiwic29yYWNvbS1lbmRvcnNlLWNsYWltIjp7Imltc2kiOiIyOTUwMDAwMTIzNDU2NzgiLCJpbWVpIjoiODAwMDAwMDEyMzQ1Njc4In19

Decoding it, we get the following JSON:

{
  "iss": "https://soracom.io",
  "aud": "soracom-endorse-audience",
  "exp": 1451116301,
  "jti": "hkK7qNyXzEMVAXfTq1MBuA",
  "iat": 1451116121,
  "nbf": 1451116061,
  "sub": "soracom-endorse",
  "soracom-endorse-claim": {
    "imsi": "295000012345678",
    "imei": "800000012345678"
  }
}

The data includes several JWT components, such as:

• iss - Issuing authority
• iat - Time token was issued
• exp - Time token expires

In this token, Endorse has attached imsi and imei claims to the payload. As these claims must be attached and signed by the Endorse service, verification of the token signature (below) ensures that the subscriber IMSI and device IMEI values have not been tampered.

Once we have verified the token signature, we can then use the IMSI and IMEI claims to authorize access to network resources, such as checking the IMSI and IMEI against a whitelist of subscribers or devices.

In addition to IMSI and IMEI claims, custom parameters can be added to the token using the Request parameters option. Refer to the Token Request documentation for more information.

Signature

The last section is the signature of the token, which is calculated by Endorse using a private key and the encryption algorithm noted in the header alg property.

By downloading the public key indicated in the header section, we can use the JWT method for verifying the signature of the token:

RSASHA256(
  "{BASE64-ENCODED-HEADER}.{BASE64-ENCODED-PAYLOAD}",
  "{CONTENTS-OF-v1-abcdef00000000000000000012345678-x509.pem-FILE}"
)

If the calculated signature matches the signature included in the token, then you can verify that the token content has not been altered.

Implementation

While the JWT format is relatively straightforward, we recommend using a verified library when implementing a verification process in your application, in order to avoid security risks with untested or unverified implementations.

Debugging

An online JWT debugger is available at jwt.io , which can be used to easily inspect and verify token issuance and verification behavior.

When debugging a token issued by Endorse:

1. Decode the token header section in order to identify which key was used to sign the token.
2. Download the corresponding public key from the Soracom Endorse Public Key repository.
3. Paste the contents of the public key into the Public Key field in order to verify the token signature.