5. Advanced Configuration

5.1. Username formats

The “ADFS-Pro Authentication” module allows save DNN users in multiple formats. The “Username format” option determines how the DNN username will be saved in DNN. DNN framework keeps Username field in database under table “Users”. To manage “Username format” follow steps below:

1. First go to provider settings, these steps are described in chapter Accessing settings panel.

2. Select Other Settings tab, then expand list Username format, see figure below for reference.

   

By default “Username format” should has value Username with domain. To choose the right “Username format” you need to answer a few questions:

• how many portals exist in your DNN,
• can the same AD identity (AD user) login to only one DNN portal or to all DNN portals. You needs to know that DNN “Username” field needs to be unique across all DNN portals.
• what is the existing DNN username format. This is extremely important if “ADFS-Pro Authentication” is implemented in already existing DNN install, bacause you don’t want (or maybe you want) to override existing users.

Below is a table that describes available username formats. To aim that, we introduce the following assumptions:

• AD username is Barry,
• AD domain name is GS,
• the DNN portal has id 2;

Username Format	Output example
Username	Username -> Barry Active Directory user can exit only in one DNN portal. In our case AD user will be able to sign in to portal id 2 as Barry. It’s good option if your DNN install has one DNN portal. In DNN database under table “Users”, under column “Username” will be field Barry.
Username with Domain	AdDomain\Username -> GS\Barry Same as above, Active Directory user can exit only in one DNN portal, but it has AD domain prefix. In our case AD user will be able to sign in to portal id 2 as GS\Barry. In DNN database under table “Users”, under column “Username” will be field GS\Barry.
Portal Suffix	Username_{portal id} -> Barry_2 “Portal Suffix” format allows save one Active Directory user in each DNN portal and it will be separate user instance. In fact every DNN portal contains his own DNN user, that points to one Active Directory user. In this situation AD user Barry is able to login to all DNN portals. In DNN database under table “Users”, under column “Username” will be field Barry_2
Portal Suffix with Domain	Domain\username_{portal ID} -> GS\Barry_2 Same as above, Active Directory user can exist in each portal, but it has domain prefix. In DNN database under table “Users”, under column “Username” will be field GS\Barry_2.
Cross Portal User	Active Directory user can exist in each DNN portal, his username will be the same, but with independent user profile. More info about the “Multi User” feature that allows to re-use username, can be found at this location In DNN database under table “Users”, under column “Username” will be field Barry.
Cross Portal User with Domain	Same as above, Active Directory user can exist in each DNN portal, but with domain prefix. More info about the “Multi User” feature that allows to re-use username, can be found at this location In DNN database under table “Users”, under column “Username” will be field GS\Barry.
Email	Active Directory user can exit only in one DNN portal, in format username@domainName. In DNN database under table “Users”, under column “Username” will be field barry@gs1.local.

If “Username format” is set to Username or Cross Portal User, then “Identity claim” shold be set to:

c:[Type == "http://schemas.microsoft.com/ws/2008/06/identity/claims/windowsaccountname", Value =~ "^.*(\\).*$"]
=> issue(Type="http://schemas.xmlsoap.org/ws/2005/05/identity/claims/name", Value=RegexReplace(c.Value, ".*\\", ""));

If “Username format” is set to Username with Domain or to Cross Portal User with Domain, then “Identity claim” shold be set to:

c:[Type == "http://schemas.microsoft.com/ws/2008/06/identity/claims/windowsaccountname", Value =~ "^.*(\\).*$"]
=> issue(Type = "http://schemas.xmlsoap.org/ws/2005/05/identity/claims/name", Value = c.Value);

If “Username format” is set to Email, then “Identity claim shold be set to:

TODO: put email claim rule here

For more info see Configure Identity Claim

5.2. Session token encryption

Session token allows continue to browse to other pages within the same DNN application without having to re-authenticate with the identity provider for each page visit. Token with info about the identity is stored in the cookie that is encrypted. By default to write and read that token the DPAPI (Data Protection API) is used. All works fine if we host our application in a single machine. Problem starts when DNN website is deployed on multiple machines or behind a load balancer. This situation offten occuers on Azure. Then usually following error message is displayed:

A CryptographicException occurred when attempting to encrypt the cookie

To bypass that issue you must implement custom “session token” encryption. The idea is to use a certificate to encrypt and decrypt the session token. To do that add following lines in your web.config file:

<configuration>
<!-- the web.config code goes here -->

<!-- begin custom code -->
<system.identityModel.services>
    <federationConfiguration>
    <serviceCertificate>
<certificateReference x509FindType="FindByThumbprint" findValue="ThumbPrintValue" storeLocation="LocalMachine" storeName="My"/>
    </serviceCertificate>
    </federationConfiguration>
</system.identityModel.services>
<!-- end custom code -->
</configuration>

More info in chapter “The data protection operation was unsuccessful”.

5.3. Session Tokens protected by Machine Key

Session tokens by default are protected with DPAPI which auto-generates a key that is specific to the machine. This means, by default, that session tokens won’t work in a web farm or cloud based hosting. In that case session tokens can be configured to use the ASP.NET <machineKey> for protection instead. To enable that option go to “ADFS-Pro Authentication-> Other Settings” and enable attribute “Token Encryption”, see figure below:

References:

• https://brockallen.com/2013/02/18/configuring-machine-key-protection-of-session-tokens-in-wif-and-thinktecture-identitymodel/
• https://brockallen.com/2013/02/14/configuring-session-token-lifetime-in-wif-with-the-session-authentication-module-sam-and-thinktecture-identitymodel/

5.4. Password change

5.4.1. Background

Password change is the ability for a user to change his password with knowledge of the old password. Note that this is not password reset where the user does not know his password. This feature is usually for employees that are not connected to the corporate network, where they have “self reset passwords” at the press of Ctrl + Alt + Del keys.

5.4.2. ADFS configuration

Note

It’s worth to mention that if AD FS service is on Windows 2012R2, password change page will be displayed only for users that are accessing from registered device. To bypass that limitation a special hotfix was released see here

ADFS provides a special endpoint to change user password: https://YourAdfsServer.com/adfs/portal/updatepassword/, but for security reasons by default it’s disabled. When you try to open the page you will get a message like on the screen below.

To enable “password change” endpoint, please go to the list of AD FS endpoints and scroll to the end where should be something like: /adfs/portal/updatepassword/ see screen below. Enable that endpoint.

When the AD FS is correctly configured, user will get following form:

After password change following message is displayed:

5.4.3. Module configuration

The configuration process at the DNN side is very simple. All you need to do is:

1. First go to provider settings, these steps are described in chapter Accessing settings panel.
2. Select Other Settings tab, and enable option “Password change link”, see figure below:

5.5. Multi DNN portal environment

There are often situations where DNN has multiple sub portals. In that case all DNN portals can work with one ADFS user data store. On the figures below are described situation with two DNN portals: dnn922v5.test and dnn922v5.test/sandbox where both points to the same ‘Relying Party’.