Sign In With Third Party Services

Linked Authentication Providers provide users a way to login to Verint Community using credentials from other websites.

Getting Started

Implementing IExternalLinkedAuthenticationProvider provides the capability to use a third party service to provide user authentication. Our sample implementation will be based on Pinterest OAuth. Usage of this example requires you to create an app in Pinterest's Dev Center so you can obtain a client ID and secret. You can find more details and set up a client app here: https://developers.pinterest.com/docs/api/overview.

Required DLLs:

Telligent.Evolution.Platform

Existing Clients

Verint Community already has a number of external linked authentication providers that can be managed simply by enabling and configuring the corresponding plugin. These are all implementations of the IExternalLinkedAuthenticationProvider interface. You only need to implement a custom client if you are not planning on using one these sites/services.

Defining Client Properties

We define several properties from the interface as constant values for later use.

NameHtml is the name used by Verint Community when referring to your authentication provider--for instance, as mouseover text on your icon.

public string NameHtml { get; } = "Pinterest";

Id must be a unique value among all external linked authentication providers, identifying your provider.

public string Id { get; } = "pinterest";

The integration between the external authentication provider and Verint Community starts with an external URL provided by the provider to initiate the login workflow with the external authentication provider (via IExternalLinkedAuthenticationProvider.GetInitializeUrl()). The process ends when details about an authenticated user are returned by the provider to Verint Community via the controller (provided by Verint Community) method, SetLinkedUserData(). The Pinterest provider will make use of another controller method to registers the provider to handle callbacks through an existing HTTP handler. Because Pinterest implements OAuth, this callback will be provided to Pinterest as the OAuth redirect_uri parameter and will be presented to users configuring the plugin to register the redirect_uri with Pinterest.

When setting the controller, the Pinterest provider configures optional parameters and registers the callback URL, saving the resulting redirect URI to present to administrators and for use when calling Pinterest's OAuth endpoints. The registration includes the provider's handler for the callback which reads the OAuth result and handles it. When the response contains an authorization code (part of the OAuth authentication workflow), the handler will load details about the user and call the SetLinkedUserData() method to end the authentication workflow:

public void SetController(IExternalLinkedAuthenticationProviderController controller)
{
	_authController = controller;
	_authController.CssColor = () => "#BD081C";
	_authController.IconUrl = () => "https://developers.pinterest.com/static/img/badge.svg";
	_authController.PrivacyDetailsHtml = () => "Privacy statement";
	_redirectUri = _authController.RegisterAndGetCallbackUrl(async (options) =>
	{
		if (options.QueryString["error"] != null)
			throw new Exception($"Login Failed: {options.QueryString["error"]}");

		if (options.QueryString["code"] == null)
			throw new Exception("Login Failed: No code was received.");

		string authorizationCode = options.QueryString["code"];
		string state = options.QueryString["state"];
		string token = await GetAccessToken(authorizationCode, options.Token);

		if (string.IsNullOrEmpty(token))
			throw new Exception("Login Failed: A token could not be retrieved.");

		_authController.SetLinkedUserData(await GetUserData(token, options.Token), state);
	});
}

As mentioned above, the external authentication workflow starts with Verint Community retrieves the initialize URL from the authentication provider and redirects a user to that URL. The last required component of IExternalLinkedAuthenticationProvider is to implement GetInitializeUrl() to enable the authentication process to start:

public Task<string> GetInitializeUrl(ExternalLinkedAuthenticationInitializeOptions options)
{
	return TaskUtility.FromSync<string>(() =>
	{
		return $"https://api.pinterest.com/oauth/?client_id={HttpUtility.UrlEncode(_configuration.GetString(CLIENT_ID))}&redirect_uri={HttpUtility.UrlEncode(_redirectUri)}&response_type=code&scope=user_accounts:read&state={HttpUtility.UrlEncode(options.State)}";
	});
}

When implementing an external linked authentication provider, details about the authenticated user are returned to Verint Community via the controller method, SetLinkedUserData() which accepts an instance of ExternalLinkedAuthenticationUserData. ExternalLinkedAuthenticationUserData defines the following properties:

ExternalUserId - (REQUIRED) The user ID that uniquely identifies the authenticated user within the external authentication provider. This is the external user account identifier that Community will link to.
UserName - (REQUIRED) This is the unique username that will be assigned to the user in the community.
DisplayName - The full displayable name of the authenticated user, if available.
AvatarUrl - The full URL of the avatar for the authenticated user, if available.
Email - The email address of the authenticated user, if available. If not provided, the newly authenticated user will be asked to provide an email address the first time they login with the external authentication provider.

Seeing the Results

Once you've compiled and added the plugin to your Verint Community instance, you can enable it, input the key and secret, and your users will be able to sign in with Pinterest. There will be an icon on the sign in page, and clicking will begin the login process.

Full Sample

View the full sample project on github: https://github.com/Telligent/Pinterest-OAuth-Client