Hello @wawa,
Based on how you phrased your question, I believe you are already familiar with some of the background I’m about to provide; nonetheless, it never hurts to reiterate and this may also be beneficial to others who have similar inquiries.
The mechanism that is of interest in this scenario is called content entitlement. For a high level overview, please see:
https://developer.kaltura.com/api-docs/Secure_Control_and_Govern/Content-Categories-Management.html
https://developer.kaltura.com/api-docs/Secure_Control_and_Govern/Content-Entitlements-Privacy-Enforcement.html
The way to determine whether a certain API request should be allowed is by looking at the KS (Kaltura Session) parameter.
This is true to all API requests, made by Kaltura’s own applications (KMC, MediaSpace, etc) as well as third party/customer applications.
A KS consists of multiple fields, the most important ones being:
- Partner ID
- Expiration date (represented as a UNIX/Epoch timestamp)
- Type (USER or ADMIN)
- user ID
- Privileges
A detailed explanation of the KS mechanism can be found here:
https://developer.kaltura.com/api-docs/VPaaS-API-Getting-Started/Kaltura_API_Authentication_and_Security.html#ks-components
To better illustrate the above, please consider this output (the result of decoding the KS string):
real_str $PARTNER_ID;$PARTNER_ID;1564681348;2;1564594948.5176;james;swiew:$ENTRY_ID;
partner_id $PARTNER_ID
partner_pattern $PARTNER_ID
valid_until 1564681348 = 2019-08-01 17:42:28 (will expire in 23 hours and 59 minutes)
type 2
rand 1564594948.5176
user james
privileges disableentitlementforentry:$ENTRY_ID,setrole:PLAYBACK_BASE_ROLE,sview:$ENTRY_ID
In this example, because the KS was generated with these privileges:
disableentitlementforentry:$ENTRY_ID,setrole:PLAYBACK_BASE_ROLE,sview:$ENTRY_ID
If you attempt to use it to view a different entry ID, it will fail.
The privileges field can be used to limit the actions that can be performed with the KS in question.
For the use-case at hand, we only want the KS to allow playback and therefore, the sview privilege is sufficient.
By setting sview:$ENTRY_ID in the privileges field when generating the KS, one can limit playback to one specific entry.
If you don’t wish to restrict the KS to one given entry ID, you may set the below in the privileges param:
disableentitlement,setrole:PLAYBACK_BASE_ROLE,sview
With the resulting KS, playback should work for all entry IDs but the different CUD (Create, Update, Delete) operations should not. Please be sure to test that.
As is always the case, the principle of least privilege (PoLP) applies. If you can be explicit and restrict per entry ID, I suggest that you do so.
There are two main methods for generating a KS:
Both methods allow you to set a specific user ID and the desired privileges and select the session type (you’ll want a USER session in this case, not ADMIN).
As you are already aware, we also offer a mechanism called appToken (https://developer.kaltura.com/workflows/Generate_API_Sessions/App_Token_Authentication)
The main advantage of using that method is that a given token can easily be revoked whereas, if the admin secret needs to be changed, you will have to put the request to us.
For a full list of supported privileges, please see: https://github.com/kaltura/server/blob/12569d19a27a88a55d72226dbcd7f0ab08378752/alpha/apps/kaltura/lib/request/kSessionBase.class.php#L28
Cheers,