SORACOM Developers

Getting Started

Verifying a Token Issued by SORACOM Endorse

This guide uses Endorse to issue a token. You will very the validity of this token and signature.


Before Starting

SORACOM Endorse (hereinafter, Endorse) provides a device authentication service for devices using Air SIM, with SORACOM as the authentication provider. The authentication used by SIM can also be used for communications other than SIM such as Wi-Fi.

Endorse issues a token that certifies that the device is using Air SIM and can connect to a network via SORACOM Air. This token has a set effective period and can include IMSI (International Mobile Subscriber Identity) and communication module IMEI (International Mobile Equipment Identity).

Also, for Endorse servers that use an asymmetric key for signatures, the client device can show this token for verification of its IMSI or IMEI information to another service.

Endorse

Note that Endorse can be set with the Console and API.

Setting Endorse(using Console)

Set Endorse for the group affiliated with the Air SIM to be used. You can select a parameter that should include a token.

For details on how to set up groups please see here.

In the user console, to enable the Endose from the group setting screen.

Endorse setup

Check on the parameters to include in the token. “Origin to allow”, “redirect URL that has been approved,” describe as necessary.

Set as described above of the screen.

Setting Endorse(using SDK)

This section uses SDK to set Endorse.

First check if the SDK is the latest version. Use Terminal, etc., to execute the following command:

$ gem soracom version

For installation and setting instructions, see SORACOM cli.

Setting Endorse

Set Endorse for the group affiliated with the Air SIM to be used. You can select a parameter that should include a token.

For details on how to set up groups please see here.

A setting example and description of the keys are as follows.

Setting Example

{
  "SoracomEndorse": {
    "enabled": true,
    "parametersToEndorse": {
      "imsi": true,
      "imei": true,
      "msisdn": false,
      "requestParameters": true
    },
    "tokenTimeoutSeconds": 600,
    "allowOrigin": "https://soracom.io",
    "authorizedRedirectUrls": ["https://soracom.io", "http://localhost:3000"]
  }
}

Description Of Keys

Now let’s use CLI to apply the Endorse settings.

Setup using CLI

Create a file according to the format below. (Here, save it as a file named endorse.json.)

{
  "parametersToEndorse":{
    "imsi": true,
    "imei": true,
    "msisdn": false,
    "requestParameters": true
  },
  "enabled" : true,
  "tokenTimeoutSeconds" : 600
}

First create a group that is to be set. Specify the group ID to be set, execute the command below, and apply the setting.

$ soracom group update-configuration --group-id XXXXXXXXXXXXXXXXXXXXXXXXXXX --namespace SoracomEndorse --params file:///Users/xxxxx/endorse/endorse.json | jq .configuration.SoracomEndorse
{
  "parametersToEndorse": {
    "imsi": true,
    "imei": true,
    "msisdn": false,
    "requestParameters": true
  },
  "enabled": true,
  "tokenTimeoutSeconds": 600
}

The file below specified in the command above is the file that includes the Endorse setting created previously above.

Instead of using the file, it is also possible to state JSON directly as a “–param” value. Here, the file is where JSON is stated is specified.

This completes the Endorse setting.


Obtaining the Endorse’s Token

With the device connected via Air SIM belonging to the group that was set previously, the token can be obtained by accessing the following end point.

The HTTP methods supported are GET and POST.

Next, execute the command below and obtain a token.

$ curl https://endorse.soracom.io
{"token":"eyJraWQiOiJ2MS1mMmZlYTA2MGI5M2Y1MTBiZmI3MjJmMmNkNGIzNzc0ZS14NTA5LnBlbSIsImFsZyI6IlJTMjU2In0.eyJpc3MiOiJodHRwczovL3NvcmFjb20uaW8iLCJhdWQiOiJzb3JhY29tLWVuZG9yc2UtYXVkaWVuY2UiLCJleHAiOjE0NTMyODgwMzYsImp0aSI6InY4UE5nQlBaVUZ6Vk5YWngzeXZ3cGciLCJpYXQiOjE0NTMyODc4NTYsIm5iZiI6MTQ1MzI4Nzc5Niwic3ViIjoic29yYWNvbS1lbmRvcnNlIiwic29yYWNvbS1lbmRvcnNlLWNsYWltIjp7Imltc2kiOiI0NDAxMDMxMzQwNzQ0NDkifX0.eF38eRyVXLB0KNP2mouBBhD5He2gp0eeadOksz9BXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX"}

A token has been obtained as shown above.


Verifying the Token’s Validity

The token is in the Json Web Token (JWT) format. Since the JWT library geared for many programming languages is used, it is easy to obtain the included information and check whether it has been modified or not.

When the above token is decoded according to the JWT specification, the information similar to the below will be included in the payload.

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

For an easy way to check the content or the validity, use the Debugger at the http://jwt.io. Shown below is the above token that was decoded by this site’s Debugger.

Endorse

By pasting the issued token in the Encoded pane on the left, you can see the decoded token.

Also, the token issued by Endorse has content signed with a secret key possessed by SORACOM. By downloading the compatible public key, you can verify whether there have been any falsifications.

The public key’s file name is included in the attribute named “kid” in the token’s header.

Endorse

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

In the example above, the public key’s file name will be v1-f2fea060b93f510bfb722f2cd4b3774e-x509.pem.

The public key used for the signature verification of Endorse is saved and distributed by https://s3-ap-northeast-1.amazonaws.com/soracom-public-keys/. By linking the public key’s file name in the header to this URL, it will become the public key’s URL that can be used to verify the token.

In other words, in the example above, the public key required for signature verification can be downloaded at https://s3-ap-northeast-1.amazonaws.com/soracom-public-keys/v1-f2fea060b93f510bfb722f2cd4b3774e-x509.pem.

Signature verification can also be tried with the Debugger at http://jwt.io. When the public key downloaded from the above URL is pasted to the Debugger’s Public Key or Certificate, “Signature Verified” is displayed to indicate that the token has not been falsified.

Endorse

This completes the verification of the token issued by SORACOM Endorse.

As supplemental information, how to use the user data is explained below.

Using the User Data

Besides the IMSI, IMEI, MSISDN and other information appended by the server, the Endorse’s token can also include any Key Value pairs as requestParameters. For example, in the case where the token is obtained by redirecting the client from a Website or authenticating server to the Endorse endpoint, a use case that includes the original site’s session ID in the token is plausible.

To use requestParameters, first set {requestParameters: true} to the Endorse’s SoracomEndorse.parametersToEndorse. Then the Key Value pair, sent as a query parameter via GET or as a request body via POST, will be included in the Endorse’s token.

An example of obtaining a token that includes {“username”: “foo”, “sessionId”: “bar”} in requestParameters is shown.

$ curl https://endorse.soracom.io?username=foo&sessionId=bar

Also, by setting the URL to where the client is to be redirected with the redirecturl parameter used as a query parameter, the token is set as a query parameter called soracomendorse_token instead of being sent to the client. The client is thereby redirected to the specified URL.

$ curl https://endorse.soracom.io?username=foo&sessionId=bar&redirect_url=https://example.com/login

When using this function, the redirect URL must be set to SoracomEndorse.authorizedRedirectUrls beforehand. If the specified URL is not set, the request will be denied.

$ curl -X POST -d '{"username":"foo","sessionId":"bar"}' https://endorse.soracom.io

Shown below is an example of the information that includes the reply for when the above request is executed.

{
  "iss": "https://soracom.io",
  "aud": "soracom-endorse-audience",
  "exp": 1451116301,
  "jti": "hkK7qNyXzEMVAXfTq1MBuA",
  "iat": 1451116121,
  "nbf": 1451116061,
  "sub": "soracom-endorse",
  "soracom-endorse-claim": {
    "imsi": "440XXXXXXXXXXXX",
    "requestParameters": {
      "username": "foo",
      "sessionId": "bar"
    }
  }
}

This completes the verification of the token issued by SORACOM Endorse, with the inclusion of supplemental information.

Since we plan to add more functions in the future, we welcome any feedback.

Getting Started

SORACOM Air for Cellular

SORACOM Air for Sigfox

SORACOM Beam

SORACOM Canal/Direct/Door

SORACOM Endorse

SORACOM Funnel

SORACOM Gate

SORACOM Harvest

SORACOM Inventory

SORACOM Junction

SORACOM Krypton

SORACOM Lagoon

Service Detail

Developer Tools

pagetop