Action token for external user file download management
Actions tokens are a particular type of token that allows unauthenticated users to perform some limited and predefined actions.
In this article we will see how to use them to create authenticated download links with a simple and short PHP script intended to run on shared web hosting.
After writing my first article about action tokens : https://please-open.it/blog/action-token/ I though there was an obvious possible usage of this kind of then.
Action tokens are basically a way to have authenticated urls. However at please-open.it we wanted to have a straightforward way to send large files through the web to our clients without having to rely on third party cloud providers.
Note : Cloud providers are very good including on security subjects, we mainly wanted our download links to serve as technical demonstration of our knowledge.
So guess what we are going to do today ? Send files through authenticated links using action tokens !
One of the prerequisites of this project is to be able to run on a shared web hosting. This kind of web hosting allows only PHP as scripting language, so most of the code for this example is written in PHP.
First step of the process, we need to allow the user to upload a file, then generate an unique token & link for an unauthenticated user to download the file.
Process for login and retrieving an access token will not be documented here. Such thing are very common & well documented operations : https://www.keycloak.org/docs/latest/securing_apps/#_javascript_adapter
We will assume that you already have a frontend implementing authorisation code flow and are able to do HTTP requests with a valid access token.
The following curl command will simulate the frontend :
curl --location --request POST 'http://localhost:9002/upload.php' \
--header 'Authorization: Bearer <access_token>' \
--form 'userfile=@"<path_to_file>.txt"'
First of all we need to check if there is a bearer token inside the HTTP request :
$configs = include('config.php');
$bearer = getallheaders()["Authorization"];
$auth_header = 'Authorization: ' . $bearer;
if (substr($bearer, 0, 7) != "Bearer ") {
die('Must have a token bearer');
}
Once the token presence is ensured, we need it to be validated with the keycloak server. A simple call to userinfo, with the token as authorization header, will tell us if our token is valid or not :
$url = $configs["kcBaseUrl"]."realms/".$configs["kcRealm"]."/protocol/openid-connect/userinfo";
$context = stream_context_create([ 'http' => [ 'method' => 'GET', 'header' => ['Accept: application/json', 'Content-Type: application/json', $auth_header ]]]);
$result = file_get_contents($url, false, $context);
if ($http_response_header[0] != "HTTP/1.1 200 OK") {
die('Invalid access token');
}
Since that point we know that our user is authenticated and his request is legit.
Nothing special here, just a very simple upload script written in PHP.
$uploaddir = 'data/';
$uploadfile = $uploaddir . basename($_FILES['userfile']['name']);
if (!move_uploaded_file($_FILES['userfile']['tmp_name'], $uploadfile)) {
die('Invalid file upload');
}
Note : In production configuration, rename each file on disk at this point to ensure name unicity and prevent overwriting. (Or create a unique folder for each file)
Once the file properly uploaded we can generate an unique action token allowing download for this particular file.
The action token will be generated by a custom endpoint in keycloak.
From the PHP perspective we only need to call this custom endpoint and return (echo) the action token :
$postdata = json_encode (
array(
"userId"=> "userId",
"applicationId"=> "file-upload",
"fileName"=> $uploadfile
)
);
$url = $configs["kcBaseUrl"]."realms/".$configs["kcRealm"]."/file/generate-token";
$context = stream_context_create([ 'http' => [ 'method' => 'POST', 'header' => ['Accept: application/json', 'Content-Type: application/json', "Authorization: $bearer" ], 'content' => $postdata]]);
$result = file_get_contents($url, false, $context);
if ($http_response_header[0] != "HTTP/1.1 200 OK") {
die('Can not generate action token');
}
echo $result;
The userId parameter can be set to track the user who is generating the action token. ApplicationId defines the type of action token we want to generate. FileName is encoded inside the token. The action token is a JWT and as any other JWT it is signed with a private key. Thus preventing any kind of modification, the action token can only give access to a specific file.
The action token generation is a simple Token object instantiation then serialization :
@POST
@NoCache
@Produces(MediaType.APPLICATION_JSON)
@Path("generate-token")
public Output getActionToken(Input input, @Context UriInfo uriInfo) {
KeycloakContext context = session.getContext();
// Generate action token
String applicationId = input.getApplicationId();
int validityInSecs = context.getRealm().getActionTokenGeneratedByUserLifespan();
int absoluteExpirationInSecs = Time.currentTime() + validityInSecs;
final AuthenticationSessionModel authSession = context.getAuthenticationSession();
final String clientId = authSession.getClient().getClientId();
// Create a token used to return back to the current authentication flow
String token = new ExternalApplicationNotificationActionToken(
//context.getUser().getId(),
input.getUserId(),
absoluteExpirationInSecs,
clientId,
applicationId, input.getFileName()
).serialize(
session,
context.getRealm(),
uriInfo
);
System.out.println(token);
System.out.println("Ok" + input.getUserId());
return new Output(token);
}
Upload response with action token encoded :
{
"actionToken": "eyJhbGciOiJIUzI1NiIsInR5cCIgOiAiSldUIiwia2lkIiA6ICJiMWIzM2U0My0yZjRjLTQ4ZTItYTBmZS04YzQ3YmFmMDZmZWYifQ.eyJleHAiOjE2MTcxMjk3MTYsImlhdCI6MTYxNzEyOTQxNiwianRpIjoiM2QzNTYxYzEtYTZkOS00YjYxLWE5MmUtMjQ4MjliZGZjMDhjIiwiaXNzIjoiaHR0cDovL2tleWNsb2FrOjgwODAvYXV0aC9yZWFsbXMvdGVzdCIsImF1ZCI6Imh0dHA6Ly9rZXljbG9hazo4MDgwL2F1dGgvcmVhbG1zL3Rlc3QiLCJzdWIiOiJ1c2VySWQiLCJ0eXAiOiJleHRlcm5hbC1hcHAtbm90aWZpY2F0aW9uIiwibm9uY2UiOiIzZDM1NjFjMS1hNmQ5LTRiNjEtYTkyZS0yNDgyOWJkZmMwOGMiLCJhcHAtaWQiOiJmaWxlLXVwbG9hZCIsImZpbGUiOiJkYXRhL3Rlc3QudHh0IiwiYXNpZCI6ImFjY291bnQiLCJhc2lkIjoiYWNjb3VudCJ9.fFMM-YqA5MljtScGNvdl6IvjmqSoValwX6RR9xhfffc"
}
Decoded token payload :
{
"exp": 1617129716,
"iat": 1617129416,
"jti": "3d3561c1-a6d9-4b61-a92e-24829bdfc08c",
"iss": "http://keycloak:8080/auth/realms/test",
"aud": "http://keycloak:8080/auth/realms/test",
"sub": "userId",
"typ": "external-app-notification",
"nonce": "3d3561c1-a6d9-4b61-a92e-24829bdfc08c",
"app-id": "file-upload",
"file": "data/test.txt",
"asid": "account"
}
Downloading the file is very simple. As simple as clicking on a link.
The following curl example shows how to use the action token inside an url to authenticate the file download :
curl 'http://localhost:9002/?key=eyJhbGciOiJIUzI1NiIsInR5cCIgOiAiSldUIiwia2lkIiA6ICJiMWIzM2U0My0yZjRjLTQ4ZTItYTBmZS04YzQ3YmFmMDZmZWYifQ.eyJleHAiOjE2MTcxMjk3MTYsImlhdCI6MTYxNzEyOTQxNiwianRpIjoiM2QzNTYxYzEtYTZkOS00YjYxLWE5MmUtMjQ4MjliZGZjMDhjIiwiaXNzIjoiaHR0cDovL2tleWNsb2FrOjgwODAvYXV0aC9yZWFsbXMvdGVzdCIsImF1ZCI6Imh0dHA6Ly9rZXljbG9hazo4MDgwL2F1dGgvcmVhbG1zL3Rlc3QiLCJzdWIiOiJ1c2VySWQiLCJ0eXAiOiJleHRlcm5hbC1hcHAtbm90aWZpY2F0aW9uIiwibm9uY2UiOiIzZDM1NjFjMS1hNmQ5LTRiNjEtYTkyZS0yNDgyOWJkZmMwOGMiLCJhcHAtaWQiOiJmaWxlLXVwbG9hZCIsImZpbGUiOiJkYXRhL3Rlc3QudHh0IiwiYXNpZCI6ImFjY291bnQiLCJhc2lkIjoiYWNjb3VudCJ9.fFMM-YqA5MljtScGNvdl6IvjmqSoValwX6RR9xhfffc'
First we will check the action-token validity. As shown inside my previous article there is a specific endpoint in keycloak to validate and handle action token. In this case we will use an empty handler, we only need to validate the token.
$configs = include('config.php');
error_reporting(0);
$url = "http://keycloak:8080/auth/realms/test/login-actions/action-token?key=".$_GET['key'];
$context = stream_context_create([ 'http' => [ 'method' => 'GET', 'header' => ['Accept: application/json', 'Content-Type: application/json']]]);
$result = file_get_contents($url, false, $context);
if ($http_response_header[0] != "HTTP/1.1 200 OK") {
die('Invalid action token');
}
Once the token validated we can trust its content. So we retrieve the filename from the token then we serve it for download through the readfile function.
$decoded_token = json_decode(base64_decode(str_replace('_', '/', str_replace('-','+',explode('.', $_GET['key'])[1]))));
$file = basename($decoded_token->file);
if(!file_exists($file)){ // file does not exist
die('file not found');
} else {
header("Cache-Control: public");
header("Content-Description: File Transfer");
header("Content-Disposition: attachment; filename=$file");
header("Content-Type: application/octet-stream");
header("Content-Transfer-Encoding: binary");
// read the file from disk
readfile($file);
}
Action tokens can serve many purposes. Authenticated links for download is another good example. More generally action token are allowing link authentication for limited actions. Usually lost password or e-mail validation. Here is a file download example, but many other usage can be imaginated.