Authentication is the process in which an application verifies a user’s identity. In the simplest form, we can authenticate with an application by entering a username and password. In modern times, authentication flows can be a lot more complicated, especially when things like multi-factor authentication, conditional access, or other interactive components are involved. In this article, we will discuss some of the most common authentication scenarios with Sitefinity and The Portal Connector, and how the system can be customized when the default functionality is not enough.
Overview
At a high level, Sitefinity needs to authenticate with at least one application (The database that hosts the application), alongside all the users that are logging in to the system. The Portal Connector on the other hand only needs to authenticate with Dynamics CRM whether that be online or on-premises. The Portal Connector leverages Sitefinity’s built-in authentication and security to determine a user’s identity. Of course, Sitefinity and The Portal Connector offer add-ons for additional services that require authentication, but in this article, we will be looking at the authentication processes described above.
User Authentication
Sitefinity is an application that has been on the market for a very long time, and as a result it has seen many different front-end authentication technologies come and go. The original authentication mechanism for Sitefinity was form-based authentication. Form-based authentication goes back to the days of legacy ASP.NET and has since been deprecated in Sitefinity 14.0 in favour of claims-based authentication. When it comes to authentication protocols, Sitefinity supports OpenID and the new Default protocol that was released in Sitefinity 14. OpenID protocol is built on top of IdentityServer3 and is an industry standard protocol that is certified by the OpenID Foundation.
For a very long time this has been the go-to mechanism for implementing external login providers with Sitefinity and offers a very easy way to integrate with external providers out of the box. It is built as a separate Microsoft OWIN component and allows the use of various authentication middleware libraries. In Sitefinity 14, they released the new “Default” provider, which is built on the same secure foundation, but no longer utilizes IdentityServer3. The Default provider promises to be more lightweight, easier to configure, and more extensible going forward.
Default Authentication Providers
Nothing is better than being able to utilize built-in functionality and have authentication work directly out of the box. Sitefinity offers a very generous number of built-in authentication providers that can be easily configured without writing any custom code. Currently, Sitefinity supports the following providers:
- Windows Authentication (LDAP)
- Active Directory Federation Services (ADFS)
- Facebook
- Google
- Microsoft
- Twitter
- LinkedIn
- OpenIdConnect
All the providers listed above can be configured through the Sitefinity Backend and will have your custom authentication scenarios up and running in a matter of hours. OpenIdConnect is a special provider, due to its industry standard authentication protocol that is supported by most external identity solutions.
Please see the following documentation if you are interested in learning more about configuring OpenIdConnect with Sitefinity: https://www.progress.com/documentation/sitefinity-cms/administration-configure-the-openid-connect-provider
Claim-to-Field Mappings
One of the greatest features that you can benefit from using the OpenIdConnect protocol with Sitefinity is built in claim-to-field mappings. To understand this feature we first need to understand how claims-based authentication works. Essentially, we have an identity server or issuer that we trust to authenticate the user. When the user logs in using the OpenIdConnect protocol or an external provider in general, we allow the external identity server to tell our application who that user is.
The information about the user is then passed back to the application using a token. The token can be an access token, or an identity token. In either case, the token contains encrypted information about the user in the form of “claims”. A claim is a single statement about the user that is trying to authenticate with the application. A group of claims is called a “scope.” For example, two of the most common claims that are passed using OpenIdConnect is family name and given name. These claims tell the application the first and last name of the user, which is certainly important when trying to establish a user profile. By default, Sitefinity will map the first name, last name, nickname, external user ID, and email address to the Sitefinity Profile.
The beauty of this feature is when you need to store custom information about the Sitefinity User that is available from your identity server. For example, maybe you want to also bring the users phone number because it is required for various interactions with your portal. The first step would be to add a new field to the Sitefinity Profile that will accept a short string called “Phone”. After you have created the custom field in the Sitefinity profile, you need to create a “Claims to fields mapping” in the OpenIdConnect provider that will map the “phone number” claim to the Sitefinity Profile “Phone” field you created earlier. After this mapping has been added, the phone number on the Sitefinity Profile will reflect the information that is stored inside of your external identity provider instance! Assuming that the identity token is configured to include that claim.
Authentication Provider Extensibility
As you can see, Sitefinity provides quite a bit of functionality directly out of the box, but sometimes that functionality is simply not enough to cover our authentication requirements. An example of a case where this may happen would be if you need to authenticate using a SAML token (maybe your provider does not support OpenId Connect protocol), or maybe your authentication flow is just too complicated to use anything that is built into the system. In this case, we can create our own custom authentication providers using the new Default authentication mechanism. Now, to cover the implementation of an external authentication provider may be a little complex and long-winded for this blog post, but below you will find resources on how to create a custom external authentication provider based on OpenIdConnect, as well as how to write a completely custom authentication provider from scratch using the new Default provider.
OpenId Connect Custom Authentication Provider – https://www.progress.com/documentation/sitefinity-cms/for-developers-implement-custom-external-identity-providers
Default Custom Authentication Provider - https://www.progress.com/documentation/sitefinity-cms/custom-external-authentication-providers
Sitefinity Authentication and Katana Logging (OpenIdConnect)
In many cases, utilizing the base OpenID Connect authentication provider can save you a lot of time when creating a custom external authentication provider rather than building one from scratch (as this allows you to leverage IdentityServer3). This type of authentication provider leverages IdentityServer3, allowing us to use Katana logging to troubleshoot and resolve any issues with the authentication process that may be swallowed up by the middleware. Additionally, Sitefinity has its own Authentication logging setting that can be utilized to troubleshoot and resolve authentication issues that have surfaced to Sitefinity.
To enable Authentication logging with Sitefinity, go to the following location in the Sitefinity Backend: Administration > Settings > Advanced > Authentication > SecurityTokenService > IdentityServer, and set Enable Logging to true. Save the changes and then restart the application.
In the case that you do not have access to the backend of the website, you can always modify the Authentication Config.config file directly. This config file can be found in the web application at the path: App_Data/Sitefinity/Configuration/AuthenticationConfig.config. In the identityServerSettings tag, you need to set the enableLogging flag to true. Once enabled, once an authentication error occurs you should see a file in the logs called Authentication.log.
<authenticationConfig>
<securityTokenServiceSettings>
<identityServerSettings enableLogging="True" />
</securityTokenServiceSettings>
</authenticationConfig>
Now sometimes enabling the Sitefinity Authentication logging will not surface the information you really need to resolve authentication errors. In which case, we can use Katana logging to get the information directly from IdentityServer3. To re-iterate, this will only work when using the “OpenIdConnect” provider rather than the “Default” provider for authentication. To enable katana logging, you will need to add something like the example below to the configuration (root) element of the web.config file and restart your application. Any logs that IdentityServer3 creates will be written to the location specified by the initializeData attribute, in this case it will be written to ~/katana.log.
<!-- Add Katana Logging-->
<system.diagnostics>
<trace autoflush="true" indentsize="4" />
<sources>
<source name="Microsoft.Owin" switchName="Microsoft.Owin" switchType="System.Diagnostics.SourceSwitch">
<listeners>
<add name="KatanaListener" />
</listeners>
</source>
</sources>
<sharedListeners>
<add name="KatanaListener" type="System.Diagnostics.TextWriterTraceListener" initializeData="katana.log" traceOutputOptions="ProcessId, DateTime" />
</sharedListeners>
<switches>
<add name="Microsoft.Owin" value="All" />
</switches>
</system.diagnostics>
Hopefully this article has provided a high-level overview of what you can expect with authentication using Sitefinity and The Portal Connector, and some resources in case you find yourself working on your own custom authentication implementation in the future.
Next we will dive into more integration with The Portal Connector and discuss Sitefinity Client/Service layer authentication.
Check out Part Two "Authentication with Sitefinity and The Portal Connector"