Last updated: Oct 10 2017

Episerver User-Generated Content (UGC)

Episerver User-Generated Content (UGC) is a content discovery tool that can retrieve content from popular social sites (such as Facebook, Twitter, Google) and embed the content into your website. This topic describes how to configure and integrate Episerver UGC, and EAUI in your site.

In this topic

Configuring Episerver UGC

Note: To use UGC Addon you must have an Episerver UGC (powered by Stackla) account.

  1. Register a UGC account (Episerver UGC account).
  2. Log into https://my.stackla.com/myaccount/login.
  3. After logging, on the left sidebar click on Plugins menu, then look for Episerver UGC.
  4. Click Configure.
  5. In web.config, modify the following sections
    • Permitted domains. Your current domain names running Episerver CMS site (without http or https). For example, stacklaaddon.azurewebsites.net.

      Note: Only domains with an SSL certificate (HTTPS) are permitted.

    • Redirect URLs. The URL for Stackla authentication and handle exchanging code of access token after authenticating successfully. Replace {domainNameHere} with your actual current domain name: https://{domainNameHere}/EPiServer/EPiServer.UGC/EAUI/ExchangeCodeForToken.

      Warning: The Redirect URL is case-sensitive. The redirect URL in the configuration page must match exactly.

    • Embed code. Code from the configuration page to embed into an existing web portal. Copy the embed code, and add it to the page section where the integration occurs. Replace [ADD_YOUR_SESSION_TOKEN] with your session token obtained from Stackla’s API. After you embed the code, Stackla generates an iFrame within the Episerver page.
    • Roles access. If you want users with specific roles to have access to the Stackla administration functions, modify the StacklaAdministrators code in web.config as shown in the following example.
  6. After configuring permitted domains and redirect URLs, click Download Json to download credentials information for use in the next step.
  7. In Episerver, select CMS > Admin > Config tab > Episerver UGC. The Episerver UGC Configuration pane appears.
  8. Enable the Upload Credentials checkbox.
  9. Click Choose File and select the JSON file that you downloaded, which provides authentication information.
  10. Click Save. The information is saved to the Dynamic Data Store (DDS).
  11. If you are currently Disconnected on the setting page, click Login to give your site access rights to the UGC account. The browser opens a UGC login window.
  12. Enter username and password and click Login.
  13. Click Authorize.

You are connected to your Episerver UGC account.

Getting an access token via OAuth

Prior to making any API calls, perform the following steps:

  1. Specify a redirect URL to support the back and forth process required to complete an OAuth exchange, then call the URL directly in address bar of browser.

    https://api.stackla.com/api/oauth2/authenticate?response_type=code&client_id={:clientId}&redirect_uri={:redirectUrl}&state={:anyState}

    • The clientId and redirect_uri parameter values are retrieved from the configuration page.
    • Stackla supports any of the state parameters supported in OAuth.
    • State Parameter in OAuth 2.0 helps to mitigate XSRF attacks. Before making a request for authentication, generate a random string called state then send it along with the request as parameter. After authenticating successfully, the Stackla Provider redirects to your configured redirectUri including the state parameter that you generated.
  2. Next, compare the value of two states. If they are not matched then reject that response and stop handling the next step.

    Note: The generated State Parameter is used only once. That means, every time you authenticate with a Stackla account, you have to generate it, and store it in somewhere (static variable for example) for later use. See The State Parameter.

  3. You are prompted for your username and password from Stackla (if you have not already logged into authorize the OAuth2 App to use the user account).
  4. Go to CMS > Admin > Config tab > Episerver UGC. The text Disconnected on setting page indicates that you are not logged in with a Episerver UGC account.
  5. Click Login to give your site access rights to the Stackla account. The browser opens a Stackla login window.
  6. Enter username and password and click Login.
  7. Click Authorize.

After you authorize the OAuth2 App to use the user account, OAuth2 redirects back to the provided Redirect URL with a short term code for Access Token exchange. For example:

{:providedRedirecUrl}?code=0123456789xxxxxxxx9876543210&state={:anyState}

For example the providedRedirectUrl is https://stacklatest.local/EPiServer/EPiServer.UGC/EAUI/ExchangeCodeForToken

  • EAUI/ExchangeCodeForToken is the controller name and action name in CMS site that will be responsible for handling authentication and exchange code of access token.
  • providedRedirecUrl is the exact Redirect URL you set up in the administrator configuration page.
  • State Parameter in OAuth 2.0 is used to help mitigate XSRF attacks.
  • Code parameter obtains the access token. The API endpoint to generate the token is

    https://api.stackla.com/api/oauth2/token?grant_type=authorization_code&code={:code}&client_id={:clientId}&client_secret={:clientSecret}&redirect_uri={:providedRedirectUrl}

  • The POST method call places the parameters into the request body. If the process of exchanging code is successful, the response contains the valid Access Token and other information about the Access Token. For example:

Note: The OAuth Access Token for the EAUI is valid for 12 months. Also, expires_in value is in seconds.

After the processes are done, the Episerver UGC Configuration page shows that you are connected. The information in the Connected section is what Stackla API responds back and it is automatically saved to DDS immediately when a response is received.

Getting a session token

The session token embeds code of Admin UI into our application. Make a POST request to url as follows:

https://api.stackla.com/api/oemsession?stack={:stackShortName}&grant_type=exchange_token&client_id={:oauthClientId}&access_token={:accessToken}

The parameters stackShortName, client_id are retrieved from Stackla Admin configuration page. The value of access token parameter is the access via OAuth. If the exchange Session Token is a success the response contains the valid session token as data. For example:

{
    "data": "123456789xxx0987654321",
    "errors": []
}

Note: The session token is valid for 60 seconds only and for one use.

Embedding the Stackla Admin UI code into the website

Copy the embedded code from the Stackla Admin configuration page and paste it into a page such as EmbedAdminUIPage. Replace [ADD_YOUR_SESSION_TOKEN] with a valid Session Token. The value of data-stack-name is episerver-dev-sandbox.  Each time the EmbedAdminUIPage is loaded, call the Stackla API to get Session Token first.

From the Episerver global menu, click Episerver UGC. The entire Stackla Admin page is embedded into your page.