Creating an External Login Provider

This topic explains the process used to create an External Login Provider. For information about the settings required to enable your provider after you have coded and deployed it, or for a general overview of the topic, please refer to External Providers.

This help topic is intended for software developers who are tasked with implementing this type of provider for an organization. This help topic will refer to your implementation of the External Login Provider as the "provider" for simplicity.

There are several steps required to get the provider working:

Creating, testing, and deploying the provider. (Topics covered on this page.)
Configuring the provider inside of SmarterStats at the system level.
For each site that you want to use the provider, changing its user authentication setting to External Provider. (This can also be done through site propagation.)

Once it is set up, all users created for sites using the External Login Provider will be authenticated ONLY through the provider. Any login credentials stored within SmarterStats for these sites will no longer function. NOTE: The system administrator is always authenticated internally, and at this time system administrator credentials cannot be attached to the provider.

Implementing the User Login Provider

The provider is a web API endpoint. A sample provider written in ASP.Net Web API using C# and Microsoft.Net 5.0 is available for download. In reality, a provider can be written in any programming language (Node.js, Java, Python, PHP, etc.) that you are comfortable with, as long as it conforms to the requests and responses that SmarterStats expects.

Sample External Login Provider on GitHub

The Provider should be implemented as a single POST API call that takes three inputs as a JSON body in the request:

site_id (an integer)
username
password

For example:

{ 
              "site_id": 5, 
              "username": "bjones", 
              "password": "mySuperSecurePassword" 
        }

The provider should take this input and generate a response with one of the following result formats as JSON:

{ 
              "login_successful": false,
              "reason": "Message to show to the user."
        }

{
              "login_successful": true
        }

All responses should have a status code of 200 (OK). Any result other than that will be considered an error and will be treated as an authentication failure.

In the sample we have provided, the file LoginController.cs does the bulk of the work of the API call and looking up the users. You can use that sample for reference to replace with your own implementation. Follow the comments in the code to understand why certain things are there, and what areas you'd need to replace with your own logic.

Allowing your Provider to create new users in SmarterStats

By default, your provider is called only if a user already exists with the username and Site ID provided on the SmarterStats login page. In this scenario, the provider is only used as an authentication method, it does not handle user creation. This is how the majority of SmarterStats administrators have the product configured. If you are using SmarterStats this way, you can skip this section. However, if you want the provider to create users for different Site IDs, read on.

If you enable the option within SmarterStats to allow the provider to create users, then your provider will be called on every login attempt for site IDs that exist and are set to authenticate with the provider. If you enable that option, other return values are required from your API in order to know how to create the users, if necessary.

{
              "login_successful": true,
              "username": "bjones",
              "email_address": "bjones@example.com",
              "is_site_administrator": false 
        }

username - The username that should be created. This should match the one sent to the provider, but may be cleaned up (e.g., remove spaces) or normalized to a specific letter casing if need be.
email_address - The email address for the user for things such as email reports.
is_site_administrator - Determines whether the user has access to settings for their site, such as site import rules or scheduled reports.

If the user already exists, they will not be recreated or changed in any way. But if they do not, they will be created with the default user settings and the items you pass back.

Unit Testing your Provider

It is strongly advised to test all possible scenarios for your provider. Using unit tests is a fairly straightforward way to do so.

While the specifics of implementing unit tests is beyond the scope of this document, the sample project we provide uses nUnit in c# in the ExternalProviderSample.Tests project to test various situations in the provider. You may want to use this for inspiration for your own tests, or expand from it to test things like database disconnects or internet failures.

Securing your Provider

Use one or more of the following to secure access to your API and prevent others from using it to harvest user data. At the very minimum, HTTPS and either firewall rules or IP restrictions are required.

Use HTTPS

Deploying any public facing Web API without HTTPS is a very bad idea. This is especially true for a login provider. The ONLY time that the provider should be deployed without HTTPS is if it is accessible only on a private IP and restricted to intranet callers only. If the API can be accessed at all from the outside world, or if there is any chance that someone may fiddle with the bindings and allow it to be accessed from the outside, you should take the time and configure HTTPS and disable HTTP calls to the provider.

How to do this depends on what web hosting software you use to host your provider, and is beyond the scope of this document.

Protect it with a firewall

If your provider and SmarterStats installs share the same private IP space, there is no need to expose the provider publicly. Use a private IP, or use firewall rules to block access to the provider from the outside world.

How to do this depends on the environment you use to host your provider, and is beyond the scope of this document.

Use IP Restrictions within your hosting software

You may wish to use your hosting software (such as IIS or Apache) to restrict access to the provider to only come from the IP addresses of your SmarterStats MRS server. This is one of the strongest ways to protect your provider.

How to do this depends on what web hosting software you use to host your provider, and is beyond the scope of this document, but some sources of information can be found below:

IIS

Apache

Requiring an Access Token to use your Provider

If desired, you can add an access token requirement to your provider. You create a restriction inside of your code that requires a certain HTTP Header name/value pair, and in SmarterStats you can configure that same pair. Note that using this option without using HTTPS is strongly discouraged, since the header can be sniffed over the wire and repeated.

In the sample code, linked above, you can see this by searching for uses of RequireHttpHeaderToPass, and you'll see where we implemented a fake access token check that you can replace with your own headers.

Secure connection with Client Certificates

Client certificates can be used to tightly protect your provider if you must expose your API on a public network. How to require client certificates and access them differs on every hosting platform and programming language, so refer to the corresponding documentation if you wish to implement this type of security.

If you configure your provider to require a client certificate, you may attach the client certificate to SmarterStats using the certificate file and password within the External Providers configuration page. This will instruct SmarterStats to always use the certificate when connecting to the provider.