DocumentationAdobe PassAdobe Pass Authentication

Single sign-on using service token flows single-sign-on-service-token-full-flows

Last update: Fri Dec 06 2024 00:00:00 GMT+0000 (Coordinated Universal Time)
IMPORTANT
The content on this page is provided for information purposes only. Usage of this API requires a current license from Adobe. No unauthorized use is permitted.
IMPORTANT
REST API V2 implementation is bounded by the Throttling mechanism documentation.

The Service Token method enables multiple applications to use a unique user identifier to achieve single sign-on (SSO) across multiple devices and platforms when using Adobe Pass services.

The applications are responsible for retrieving the unique user identifier payload using external identity services, outside of Adobe Pass systems, such as:

  • A direct-to-consumer (DTC) service, where users log in on each device using the same credentials and are associated with the same user ID or user account name.
  • A third-party authentication service, such as Google or Facebook, where users log in on each device using the same credentials and are associated with the same email address.

The applications are responsible for including this unique user identifier payload as part of the AD-Service-Token header for all requests that specify it.

For more details about AD-Service-Token header, refer to the AD-Service-Token documentation.

Perform authentication through single sign-on using service token performing-authentication-flow-using-service-token-single-sign-on-method

Prerequisites prerequisites-scenario-performing-authentication-flow-using-service-token-single-sign-on-method

Before performing the authentication flow through single sign-on using a service token, ensure the following prerequisites are met:

  • The external identity service must return consistent information as JWS payload across all applications over multiple devices and platforms.
  • The first streaming application must retrieve the unique user identifier and include the JWS payload as part of the AD-Service-Token header for all requests that specify it.
  • The first streaming application must select an MVPD.
  • The first streaming application must initiate an authentication session to sign in with the selected MVPD.
  • The first streaming application must authenticate with the selected MVPD in a user agent.
  • The second streaming application must retrieve the unique user identifier and include the JWS payload as part of the AD-Service-Token header for all requests that specify it.
IMPORTANT
Assumptions
  • The first streaming application supports user interaction to select an MVPD.
  • The first streaming application supports user interaction to authenticate with the selected MVPD in a user agent.

Workflow workflow-steps-scenario-performing-authentication-flow-using-service-token-single-sign-on-method

Perform the given steps to implement the authentication flow through single sign-on using a service token as shown in the following diagram.

Perform authentication through single sign-on using service token

Perform authentication through single sign-on using service token

  1. Authenticate with identity service: The first streaming application calls the identity service, outside of Adobe Pass systems, to obtain the JWS payload associated with the unique user identifier.

  2. Return unique user identifier as JWS: The first streaming application validates the response data to ensure that basic security conditions are met:

    • Payload is not expired.
    • Payload is signed.

  3. Create authentication session: The first streaming application gathers all the necessary data to initiate an authentication session by calling the Sessions endpoint.

    note important
    IMPORTANT
    Refer to the Create authentication session API documentation for details on:
    • All the required parameters, like serviceProvider, mvpd, domainName, and redirectUrl
    • All the required headers, like Authorization, AP-Device-Identifier
    • All the optional parameters and headers
    The streaming application must ensure it includes a valid value for the unique user identifier before making a request.
    For more details about AD-Service-Token header, refer to the AD-Service-Token documentation.

  4. Indicate the next action: The Sessions endpoint response contains the necessary data to guide the first streaming application regarding the next action.

    note important
    IMPORTANT
    Refer to the Create authentication session API documentation for details on the information provided in a session response.
    The Sessions endpoint validates the request data to ensure that basic conditions are met:
    • The required parameters and headers must be valid.
    • The integration between the provided serviceProvider and mvpd must be active.
    If validation fails, an error response will be generated, providing additional information that adheres to the Enhanced Error Codes documentation.

  5. Open URL in user agent: The Sessions endpoint response contains the following data:

    • The url which can be used to initiate the interactive authentication within the MVPD login page.
    • The actionName attribute is set to “authenticate”.
    • The actionType attribute is set to “interactive”.

    If the Adobe Pass backend does not identify a valid profile, the first streaming application opens a user agent to load the provided url, making a request to the Authenticate endpoint. This flow may include several redirects, ultimately leading the user to the MVPD login page and provide valid credentials.

  6. Complete MVPD authentication: If the authentication flow is successful, the user agent interaction saves a regular profile in the Adobe Pass backend and reaches the provided redirectUrl.

  7. Retrieve profile for specific code: The first streaming application gathers all the necessary data to retrieve profile information by sending a request to the Profiles endpoint.

    note important
    IMPORTANT
    Refer to the Retrieve profile for specific code API documentation for details on:
    • All the required parameters, like serviceProvider, code
    • All the required headers, like Authorization, AP-Device-Identifier
    • All the optional parameters and headers
    note tip
    TIP
    Suggestion: The streaming application can wait for the user agent to reach the provided redirectUrl to check if the regular profile was successfully generated and saved.

  8. Find regular profile: The Adobe Pass server identifies a valid profile based on the received parameters and headers.

  9. Return information about regular profile: The Profiles endpoint response contains information about the found profile associated with the received parameters and headers.

    note important
    IMPORTANT
    Refer to the Retrieve profile for specific code API documentation for details on the information provided in a profile response.
    The Profiles endpoint validates the request data to ensure that basic conditions are met:
    • The required parameters and headers must be valid.
    If validation fails, an error response will be generated, providing additional information that adheres to the Enhanced Error Codes documentation.

  10. Proceed with decisions flows: The first streaming application can continue with subsequent decisions flows.

    note important
    IMPORTANT
    The streaming application must ensure it includes a valid value for the unique user identifier before making a request.
    For more details about AD-Service-Token header, refer to the AD-Service-Token documentation.

  11. Authenticate with identity service: The second streaming application calls the identity service, outside of Adobe Pass systems, to obtain the JWS payload associated with the unique user identifier.

  12. Return unique user identifier as JWS: The second streaming application validates the response data to ensure that basic security conditions are met:

    • Payload is not expired.
    • Payload is signed.

  13. Retrieve profiles: The second streaming application gathers all the necessary data to retrieve all profiles information by sending a request to the Profiles endpoint.

    note important
    IMPORTANT
    Refer to the Retrieve profiles API documentation for details on:
    • All the required parameters, like serviceProvider
    • All the required headers, like Authorization, AP-Device-Identifier
    • All the optional parameters and headers
    The streaming application must ensure it includes a valid value for the unique user identifier before making a request.
    For more details about AD-Service-Token header, refer to the AD-Service-Token documentation.

  14. Find single sign-on profile: The Adobe Pass server identifies a valid single sign-on profile based on the received parameters and headers.

  15. Return information about single sign-on profile: The Profiles endpoint response contains information about the found profile associated with the received parameters and headers.

    note important
    IMPORTANT
    Refer to the Retrieve profiles API documentation for details on the information provided in a profile response.
    The Profiles endpoint validates the request data to ensure that basic conditions are met:
    • The required parameters and headers must be valid.
    If validation fails, an error response will be generated, providing additional information that adheres to the Enhanced Error Codes documentation.

  16. Proceed with decisions flows: The second streaming application can continue with subsequent decisions flows.

    note important
    IMPORTANT
    The streaming application must ensure it includes a valid value for the unique user identifier before making a request.
    For more details about AD-Service-Token header, refer to the AD-Service-Token documentation.

Retrieve authorization decisions through single sign-on using service token performing-authorization-flow-using-service-token-single-sign-on-method

Prerequisites prerequisites-scenario-performing-authorization-flow-using-service-token-single-sign-on-method

Before performing the authorization flow through single sign-on using a service token, ensure the following prerequisites are met:

  • The external identity service must return consistent information as JWS payload across all applications over multiple devices and platforms.
  • The first streaming application must retrieve the unique user identifier and include the JWS payload as part of the AD-Service-Token header for all requests that specify it.
  • The second streaming application must retrieve an authorization decision before playing a user selected resource.
IMPORTANT
Assumptions
  • The first streaming application has performed authentication and has included a valid value for AD-Service-Token request header.

Workflow workflow-steps-scenario-performing-authorization-flow-using-service-token-single-sign-on-method

Perform the given steps to implement the authorization flow through single sign-on using a service token as shown in the following diagram.

Retrieve authorization decisions through single sign-on using service token

Retrieve authorization decisions through single sign-on using service token

  1. Authenticate with identity service: The second streaming application calls the identity service, outside of Adobe Pass systems, to obtain the JWS payload associated with the unique user identifier.

  2. Return unique user identifier as JWS: The second streaming application validates the response data to ensure that basic security conditions are met:

    • Payload is not expired.
    • Payload is signed.

  3. Retrieve authorization decision: The second streaming application gathers all the necessary data to obtain an authorization decision for a specific resource by calling the Decisions Authorize endpoint.

    note important
    IMPORTANT
    Refer to the Retrieve authorization decisions using specific mvpd API documentation for details on:
    • All the required parameters, like serviceProvider, mvpd, and resources
    • All the required headers, like Authorization and AP-Device-Identifier
    • All the optional parameters and headers
    The streaming application must ensure it includes a valid value for the unique user identifier before making a request.
    For more details about AD-Service-Token header, refer to the AD-Service-Token documentation.

  4. Find single sign-on profile: The Adobe Pass server identifies a valid single sign-on profile based on the received parameters and headers.

  5. Retrieve MVPD decision for requested resource: The Adobe Pass server calls the MVPD authorization endpoint to obtain a Permit or Deny decision for the specific resource received from the streaming application.

  6. Return Permit decision with media token: The Decisions Authorize endpoint response contains a Permit decision and a media token.

    note important
    IMPORTANT
    Refer to the Retrieve authorization decisions using specific mvpd API documentation for details on the information provided in a decision response.
    The Decisions Authorize endpoint validates the request data to ensure that basic conditions are met:
    • The required parameters and headers must be valid.
    • The integration between the provided serviceProvider and mvpd must be active.
    If validation fails, an error response will be generated, providing additional information that adheres to the Enhanced Error Codes documentation.

  7. Start stream with media token: The second streaming application uses the media token to play the content.

  8. Return Deny decision with details: The Decisions Authorize endpoint response contains a Deny decision and an error payload which adheres to the Enhanced Error Codes documentation.

    note important
    IMPORTANT
    Refer to the Retrieve authorization decisions using specific mvpd API documentation for details on the information provided in a decision response.
    The Decisions Authorize endpoint validates the request data to ensure that basic conditions are met:
    • The required parameters and headers must be valid.
    • The integration between the provided serviceProvider and mvpd must be active.
    If validation fails, an error response will be generated, providing additional information that adheres to the Enhanced Error Codes documentation.

  9. Handle Deny decision details: The second streaming application processes the error information from the response and can use it to optionally display a specific message on the user interface.

NOTE
The steps for the preauthorization flow are the same as those for the authorization flow, except that the endpoint used is the one described in the Retrieve preauthorization decisions using specific mvpd documentation.
recommendation-more-help
3f5e655c-af63-48cc-9769-2b6803cc5f4b