Introduction
The OEM API enables setting an authentication flow based on users automatically accessing an Astrato tenant without their password.
The flow is highlighted in the image below.
Astrato Tenant Settings
In the Astrato, tenant navigate to the Administration section.
In the Administration section, click on View System Settings, which is at the top section.
Look for the OEM Management API section in the System Settings section; if it's the first time, click on Enable.
If it has already been enabled, click on View.
When you click on View, you'll see the Client_ID and Client_Secret.
If a new set is needed, click on Rotate.
Copy them to set up your OEM API authentication flow.
Authentication Flow
The flow is explained in a sequence of requests:
Requests to manage API tokens and session ticket endpoints should not be triggered publicly by the browser. Client ID, Client Secret, and an obtained astrato access token are confidential and, when exposed publicly, will lead to providing full control to the tenant to the world. For security reasons, request those endpoints from a backend service that only exposes a Ticket ID.
Steps:
POST
/auth/proxy/m2m/tokenAuthentication: public
To get a token, you must authenticate your next requests from Client App Service to the Astrato OEM API.
Request:
curl --location 'https://astrato.io/auth/proxy/m2m/token' \
--header 'Content-Type: application/json' \
--data '{
"clientId": "your client id",
"clientSecret": "your client secret"
}'For example, in PHP it can be used as
function getManagementApiToken() {
$client = new Client();
$headers = ['Content-Type' => 'application/json'];
$body = json_encode([
'clientId' => $_ENV['ASTRATO_CLIENT_ID'],
'clientSecret' => $_ENV['ASTRATO_CLIENT_SECRET']
]);
$url = $_ENV['ASTRATO_URL'] . '/auth/proxy/m2m/token';
$request = new Request('POST', $url, $headers, $body);
$res = $client->send($request);
$result = json_decode($res->getBody(), true)['access_token'];
return $result;
}Response:
{
"access_token": "XXXXXXXXJSUzI1NiIsInR5cCI6IkpXVCJ9.eyJuYW1lIjoiT0...",
"expires_in": 1699891513107
}POST
/oem/setupAuthentication: m2m bearer token
Setup endpoint, which prepares a user session. If a user account doesn't exist, it will be created in a tenant
Request:
curl --location 'https://astrato.io/oem/setup' \
--header 'Content-Type: application/json' \
--header 'Authorization: Bearer eyJhbGciOiJSUzI...' \
--data-raw '{
"email": "XXXXXX@astrato.io",
"name": "Developer Viewer",
"groupIds": ["XXXXXX-07bb-429a-8795-5164fddc9e17","XXXXXX-2708-4444-8e71-a3cdfe6e24f8"]
}'An example in PHP:
function getSessionTicket($accessToken, $email, $groupIds = []) {
$client = new Client();
$headers = [
'Content-Type' => 'application/json',
'Authorization' => "Bearer $accessToken"
];
$body = json_encode([
'email' => $email,
'groupIds' => $groupIds
]);
$request = new Request('POST', $_ENV['ASTRATO_URL'] . '/oem/setup', $headers, $body);
$res = $client->sendAsync($request)->wait();
$result = json_decode($res->getBody(), true);
return $result['ticket'];
}Email(required): if a user with such an email doesn't exist, the account will be created
groupIds (optional): list of groups to temporarily assign users. Membership won't make permanent changes to group membership or be visible on group management views.
Response:
{
"ticket": "XXXXXXX-b1cb-4a84-844e-8XXXXXXXX"
}GET
/auth/proxy/oem/ticket/:ticketId/embedAuthentication: public
It creates a user session cookie under the hood and redirects to Astrato UI. Due to cookie policy, this link cannot be used by embeds. To make it work with embeds, the browser needs to make a top-level request, and when it's done, an embed with a proper link should be injected into the front end.
PHP Example:
rxjs.fetch.fromFetch(`${ASTRATO_URL}auth/proxy/oem/ticket/${data.ticketId}?embed`, { credentials: 'include', selector: response => response.json() }The resolved user will be returned with groupIds that were requested on OEM/setup
Basic setup can be found on this support page https://help.astrato.io/en/articles/9413603-auth-oem-api