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 standard authentication procedures apply for retrieval of the SAS token which later can be used calling relevant services directly. First, determine the direct service base URI. Then, get a Shared Access Signature Token (SAS Token) from the root api host and use it for requests to the direct service.
To find out the base URI for a service use the following end point:
GET/api/services/{serviceName}/baseuri
api-version 3
Example response could look something like below.
{
"data": "https://<seviceName>-mike-platform-dev.eu.mike-cloud-dev.com/api/"
}
There serviceName
is service id which can be retrieved using the following endpoint:
GET/api/services/ids
api-version 1
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/security/sastoken?projectId=<projectId>&resourceId=<datasetId>
- api-version 2
generates a token for the given project (and optionally a dataset)
GET/api/security/recursivesastoken?projectId=<projectId>&expiration=<datetime>
- api-version 2
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 useful, the caller should have at least a READ privilege in all subfolders of the given folder.
SAS token use¶
To stich all the above let's 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. It returns the SAS token in the following response:
{
"data": <sas token as string>
}
It is strongly recommended not to modify or even get information from the SAS token. The structure and content of the SAS token is driven by internal rules of the Platform and it is not versioned. Therefore, any logic based on the internal structure of the SAS token could break over time.
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/security/sastoken?projectId=<projectId>" \ -H 'api-version: 2' \ -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 } }'