How to use SAS tokens

In some scenarios it could be relevant to call MIKE Cloud Platform services directly instead of via Metadata service. In the following case standart authentication procedures apply for retrieval of the SAS token which later can be used calling relevant services directly.

To find out the base URI for a service use the following end point:

GET/api/services/{serviceName}/baseuri

Example response could look something like below.

{
    "data": "https://core-engine-dev0.azurewebsites.net/api/"
}

There serviceName is service id which can be retrieved using the following endpoint:

GET/api/services/ids

Example response could look something like below.

[
    "md",
    "engine",
    "timeseries",
    "gis",
    "coordinatesystems",
    "raw",
    "sharing"
]

What is SAS token

• SAS token is authorization token (represented by url-friendly string) that can be issued for a specific project, or a dataset within a project, or a subtree of folders under a given project.
• The SAS token contains information about the customer and user who issued it, an expiration date, resource identification (project/dataset), and set of privileges that the issuer has with respect to the resource (at the time of creation).
• The inner services (such as Multidimensional service, Timeseries storage etc.) can accept this token, and validate that the caller can access the requested resource. And the token is the only authentication/authorization method used in the call - with the token no AD registration is necessary to exist for the caller.
• In some cases even the Metadata service itself can accept a SAS token to perform certain operations (e.g. file upload).

SAS token retrieval

The following endpoints are exposed by the Metadata service to get the SAS token:

GET/api/services/sastoken?projectId=<projectId>&resourceId=<datasetId> - generates a token for the given project (and optionally a dataset)

GET/api/services/recursivesastoken?projectId=<projectId>&expiration=<datetime> - generates a recursive token for the given project (with optional expiration specification). The recursive token contains privileges that can be applied to ALL subprojects of the given projects. I.e. in order for the token to be usefull, the caller should have at least a READ privilege in all subfolders of the given folder.

SAS token use

To stich all the above lets take an example where we try to run engine execution using SAS token. In the following example we would first send a request to Metadata service to retrieve base URI for engine execution.

Click to show example shell script to retrieve engine service base URI

projectId="<replacewithprojectid>"
openapikey="<replacewithopenapikey>"

# create execution
curl -L -X GET "https://api.mike-cloud-test.com/services/engine/baseuri" \
  -H 'api-version: 1' \
  -H "dhi-open-api-key: $openapikey" \
  -H 'Content-Type: application/json' \

Next we should call Metadata service to retrieve valid SAS token.

Click to show example shell script to retrieve SAS token

projectId="<replacewithprojectid>"
openapikey="<replacewithopenapikey>"

# create execution
curl -L -X GET "https://api.mike-cloud-test.com/api/services/sastoken?projectId=<projectId>" \
  -H 'api-version: 1' \
  -H "dhi-open-api-key: $openapikey" \
  -H 'Content-Type: application/json' \

Next we should use the generated SAS token and retrieved service URI calling engine service directly.

Click to show example shell script to start an engine execution using SAS token

projectId="<replacewithprojectid>"
sasToken="<replacewithgeneratedsastoken>"
baseUri="<replacewithretrievedbaseuri>"

# create execution
curl -L -X POST "https://api.mike-cloud-test.com/api/compute/execution" \
  -H 'api-version: 2' \
  -H "dhi-sas-token: $sasToken" \
  -H 'Content-Type: application/json' \
  --data-raw '{
      "inputs": [
        {
          "uri": "https://coreenginedev0inputs.blob.core.windows.net/data/lake.m21fm",
          "engine": "FemEngineHD"
        },
        {
          "uri": "https://coreenginedev0inputs.blob.core.windows.net/data/lake.mesh"
        }
      ],
      "options": {
        "poolType": "VM-S-5",
        "nodeCount": 1
      }
    }'