Secure Session Management (SSM)

1. Overview

SSP provides a service called Secure Session Manager (SSM). The goal of this service is to implement as securely as possible the enforcement of OTT session concurrency requirements. SSP SSM supports:

• A common set of APIs to be integrated by devices using DRM as much as possible to reach the best implementation robustness possible

• Different ways to define concurrency requirements per playback session from the backend

• Several back-end APIs to close sessions covering various use cases

SSM is only available in the SSP SaaS offering running in AWS.

SSM can be used on any device supported by SSP. The robustness of the support depends on the DRM used:

To optimize the security and consistency of the deployment, the following table sums up the recommended way of integrating SSM per device platform:

Note that for backward compatibility reasons, Fairplay Streaming DRM enforcement is deactivated by default and requires a configuration update.

2. Device integration

In all scenarios described hereafter, the application is supposed to be aware if SSM needs to be used because concurrency rules apply in this playback context or if SSM is not needed because no concurrency rules apply. This can be achieved thanks to downloaded metadata in the catalogue, for example.

Additionally, the application needs to receive either a DevAuthN or ContentAuthZ token from the customer portal depending on the selected OTT authorization method.

2.1. Application-level enforcement

2.1.1. Post-delivery

The above diagram depicts the SSM integration when DRM is not used to implement the enforcement. In detail:

• /ssm/v1/sessions/setup is used to set up a new playback session. The context of this session will be defined by the token provided as input of the request.

  • If successful, one new session will be added to the corresponding context in the SSM DB and a sessionToken will be sent back.

  • If the maximum session limit for the context is reached, the request will fail.

• The license server matching the selected DRM on the device is called to request a license for the content. The DRM challenge, the original token provided in the session setup operation, and the sessionToken are all provided as input to the request.

  • If the sessionToken is not valid, or is expired or not related to the original token, the license request will fail.

• The license included in the response can be sent to the DRM client and playback can start.

• Periodically depending on the "heartbeat" period returned in the setup call, the application must call /ssm/v1/sessions/heartbeat to keep the session alive in SSM.

  • The license does not need to be renewed (session is not DRM enforced).

  • A new session token will be included in the response and needs to be provided in any subsequent SSM request, being the next "heartbeat" or "teardown" call.

  • The session is kept alive until the next heartbeat in the SSM.

• When the user stops playback, the application must call /ssm/v1/sessions/teardown with the last session token.

  • This operation immediately frees a session slot in the context.

2.1.2. Pre-delivery

OTT pre-delivery is supported by HW-PRM, SW-PRM, and Connect and consists of retrieving the DRM licenses before the user actually decides to play anything. When this mode is used, the application can safely rely on the DRM client to determine if a DRM license needs to be acquired or if a valid license is already present in the device at playback time. If a license is already available, then steps 4, 5, 6, 7 and 8 in the previous diagram are bypassed. 

2.2. DRM-level enforcement with post-delivery

In this mode, SSM relies on DRM license renewal mechanisms to enforce the concurrency rules. In particular, devices have to regularly get a new DRM license to continue playing. By doing so, they have to contact SSM which can then enforce the concurrency rules during the license renewal authorization. In detail:

1. /ssm/v1/sessions/setup is used to set up a new playback session. The context will be defined by the token provided as an input to the request. This call is similar to the application-level enforcement case.

   • If successful, one new session will be added to the corresponding context in the SSM and a sessionToken will be sent back.

   • If the maximum session limit for the context is reached, the request will fail.

2. The license server matching the selected DRM on the device is called to request a license for the content. The DRM challenge, the original token, and the sessionToken are provided as inputs to the request.

   • If the sessionToken is not valid or is expired or not related to the original token, the license request will fail.

   • If concurrency rules are enforced using DRM license renewal, the license server will return a sessionToken in the license response. This mechanism allows the application to determine if dynamic license renewal is required or not. Note that for Widevine, license renewal is systematically used even if session tokens are never returned in the license response.

3. The license included in the response can be sent to the DRM client and playback can start.

4. Periodically, the application must refresh the license to keep the session alive in SSM and to continue playing.

   • For Widevine, /ssm/v1/renewal-license-wv needs to be called and the WV DRM client will notify the application when it is time to renew the license.

   • For Playready, /prls/contentlicenseservice/v1/licenses needs to be called only if a sessionToken was returned in the original license response and with the "renew" query parameter. As the PR DRM the client will NOT notify the application when it is time to renew the license, the renewal logic needs to be implemented in the application by relying on the "heartbeat" parameter returned in the setup operation.

   • For FairPlay Streaming, /fpsls/contentlicenseservice/v1/licenses needs to be called only if a sessionToken was returned in the original license response and with the "renew" query parameter. As the FPS DRM client will NOT notify the application when it is time to renew the license, the renewal logic needs to be implemented in the application by relying on the "heartbeat" parameter returned in the setup operation.

   • A new session token will be included in the response and needs to be provided in any subsequent SSM request, being the next license renewal or "teardown" call.

   • The session is kept alive until the next renewal call to SSP.

5. When the user stops playback, the application must call /ssm/v1/sessions/teardown.

   • This operation immediately frees a session slot in the context.

3. Back-end integration

3.1. SSM basic integration

In this mode, SSP ADM, ISPM, DevAuthN, and ContentAuthZ tokens are used to define the concurrency requirements per OTT content and account. SSP supports:

• Defining the applicable "account profile" ID ("accountProfileId") per "account" in ADM. In an "account profile", session control can be activated thanks to "enableSessionLimit" and if it is enabled, then "maxSessionsAllowed" defines the limit for the number of simultaneous OTT sessions accessible by the account profile.

• Defining if SSM is required or not to access this content ("sessionControlEnabled" set to true or false) per "channel" or "OTT asset" in ISPM.

• Referring an "accountId" and/or "deviceId" defined in ADM in a DevAuthN token and using this token to start a playback session for content defined in ISPM.

• For content not defined in ISPM, defining in a ContentAuthZ token if using SSM is required or not to access the referred content ("sessionControl" section present or not in the token). If present, "sessionControl" should be empty and "accountId" should refer the value defined in ADM so that SSM can retrieve the applicable "account profile" from ADM.

In this integration mode, SSP implements the full business rules and ensures that at any time the maximum number of simultaneous OTT playback sessions running from one account is lower than or equal to the "maxSessionsAllowed" in the ADM account profile. For any additional session started after reaching the "maxSessionAllowed", the SSM setup operation will fail.

3.2. SSM extended integration

In this mode, additional fields are used in the ContentAuthZ "sessionControl" section to overwrite any concurrency settings defined in SSP ADM or ISPM:

• "groups" allows the OTT playback session to be assigned to several abstract entities instead of the single "accountId" in the previous section. For each group:

  • "groupId" identifies the abstract entity in which several sessions will be grouped together. As business rules are generally applied per account, a good practice is to use the accountId as prefix of the "groupId" to apply the related "maxSessions" only to a given account.

  • "maxSessions" defines the maximum number of simultaneous session in the group.

This array of session groups embedded in a single token can be used to implement advanced and potentially conflicting business rules such as:

• Maximum number of sessions per content provider, for example, one session max for live soccer.

• Maximum number of sessions per content type, for example, two sessions max for VOD, three sessions max for live. In this case, the same "groupId" is used for all the VOD sessions consumed in an account and another one is used for the live sessions.

• Maximum number of sessions per device type, for example, two sessions max for open devices, three sessions max for STB. In this case, the same "groupId" is used for all the sessions started from the open devices of an account and another one is used for the sessions started from STB.

• Maximum number of sessions per network, for example three sessions max inside the home, one session max outside of home. In this case, the same "groupId" is used for all sessions started from inside the home of an account and another one is used for the sessions started outside the home.

For even more complex rules, the ContentAuthZ "sessionControl" section lets the back-end service in charge of creating the token assign a "sessionId" to the playback session. This mechanism, combined with the SSM "forbidsession" operation, lets a back-end service completely control which sessions are running and which need to be terminated if they were running (or prevented to start if they were not yet running) to implement the business rules. This can be used to implement requirements as complex as:

• Sessions started from STB must have priority compared to sessions started from open devices. In this case, the back-end has the flexibility to kill sessions from open devices if needed while taking into account when the session was started or from which kind of device.

• Maximum number of simultaneous session changing temporally per event. For example, three max per account but only two max when some soccer events are live.

In this mode, SSP ensures that at any time, the maximum amount of simultaneous OTT playback sessions running associated with any "groupId" is lower or equal to the "maxSessions" defined for that "groupId in a ContentAuthZ token and no session associated to a black-listed "sessionId" actually runs. So, this mode supposes that a larger part of the business logic is implemented outside of SSP to create SSP tokens and to call SSM operations with the right parameters at the right time.

4. Closing sessions

SSM supports several different ways to close sessions:

• End user applications must call /ssm/v1/sessions/teardown whenever the playback session was stopped on the device, to free the slot.

• SSM will automatically close running sessions:

  • If either the heartbeat or the DRM license renewal operations were not called before the heartbeat period ends. This is required to covered cases like application crashes.

  • If the session reaches the maximum allowed duration. This is a tenant-specific configuration. The default value is 24h.

• Customer's back-end or anti-piracy teams can call the online SSM kill session APIs:

  • /ssm/v1/sessions/killAccountSessions closes all the sessions of a given account.

  • /ssm/v1/sessions/killDeviceSessions closes all the sessions of a given device.

  • /ssm/v1/sessions/forbidsession closes a given session identified by a "sessionId" and blacklists it for a "duration".

• Schedule an automatic session tear down process in SSM including:

  • The list of accounts targeted by this automatic procedure

  • The time frame during which the automatic session tear down will be enforced. This can be a recurrent period (e.g., Tue and Thurs from 18:00 to 20:00 for one month)

  • Once this configuration is in place, SSM will tear down any existing sessions for the accounts in the list as well as reject any further session set-up requests from devices belonging to those accounts.

  • To access this feature, please log into the SSP Console or contact your NAGRA support team.

Once a session has been closed, any new call to SSM heartbeat or DRM license renewal operations referring to that session will fail. In addition, for /ssm/v1/sessions/forbidsession, any call to SSM setup referring to that session would also fail.