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
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 setup, 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
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
- site_id (an integer)
The provider should take this input and generate a response with one of the following result formats as JSON:
"reason": "Message to show to the user."
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
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.
- 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.
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
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
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
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:
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
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.
(c) 2002-2021 SmarterTools Inc.