Adxstudio Portals provides authentication functionality built on the ASP.NET Identity API. ASP.NET Identity is in turn built on the OWIN framework which is also an important component of the authentication system. The services provided include:

  • Local (username/password) user sign-in
  • External (social provider) user sign-in through third party identity providers
  • Two-factor authentication with email or SMS
  • Email address confirmation
  • Password recovery
  • Invitation code sign-up for registering pre-generated contact records

Requirements

  • Adxstudio Portals 7.0.0018
  • Adxstudio Portals Base (AdxstudioPortalsBase.zip), the Adxstudio Identity (AdxstudioIdentity.zip), and the Adxstudio Identity Workflows (AdxstudioIdentityWorkflows.zip) solution packages

New installations of version 7.0.0018 or greater will have ASP.NET Identity authentication enabled by default. To upgrade from a previous version refer to the instructions on how to proceed.

Overview

Returning portal visitors have the option to authenticate using local user credentials and/or external identity provider accounts. A new visitor can register for a new user account either by providing a username/password or by signing-in through an external provider. Visitors who are sent an invitation code (by the portal administrator) have the option to redeem the code in the process of signing-up for a new user account.

Related Site Settings:

  • Authentication/Registration/Enabled
  • Authentication/Registration/LocalLoginEnabled
  • Authentication/Registration/ExternalLoginEnabled
  • Authentication/Registration/OpenRegistrationEnabled
  • Authentication/Registration/InvitationEnabled
  • Authentication/Registration/RememberMeEnabled
  • Authentication/Registration/ResetPasswordEnabled
  • 1) Sign-in with a local identity or external identity

  • 2) Sign-up with a local identity or external identity

  • 3) Redeem an invitation code manually

Forgot Password / Password Reset

Returning visitors that require a password reset (and have previously specified an email address on their user profile) have the option of requesting a password reset token to be sent to their email account. A reset token allows its owner to set a new password of their choosing. Alternatively, the token can be abandoned leaving the users original password unmodified.

Related Site Settings:

  • Authentication/Registration/ResetPasswordEnabled
  • Authentication/Registration/ResetPasswordRequiresConfirmedEmail

Related Processes:

  • Send Password Reset To Contact
    • Customize the email in the workflow as necessary
  • 1) Submit email to invoke process

  • 2) Visitor prompted to check email

  • 3) Process: Send Password Reset To Contact

  • 4) Password reset email with instructions

  • 5) Visitor returns to the reset form

  • 6) Password reset complete

Redeem Invitation

Redeeming an invitation code allows a registering visitor to be associated to an existing contact record that was prepared in advance specifically for that visitor. Typically, the invitation codes are sent out by email but a general code submission form is available for codes sent though other channels. After a valid invitation code is submitted, the normal user registration (sign-up) process takes place to setup the new user account.

Related Site Settings:

  • Authentication/Registration/InvitationEnabled

Related Processes:

  • Send Invitation
    • Note: the email sent by this workflow must be customized with the URL to the redeem invitation page on the portal.
      • http://portal.contoso.com/register/?returnurl=%2f&invitation={Invitation Code(Invitation)}
  • 1) Create invitation for a new contact

  • 2) Customize and save the new invitation

  • 3) Process: Send Invitation

  • 4) Customize the invitation email

  • 5) Invitation email opens the redemption page

  • 6) Sign-up using the submitted invitation code

Profile Page

Authenticated users manage their user accounts through the Security navigation bar of the profile page. Users are not limited to the single local account or single external account chosen at user registration time. Users with an external account may choose to create a local account by applying a username and password. Otherwise, users that started with a local account can choose to associate multiple external identities to their account. The profile page is also where the user is reminded to confirm their email address by requesting a confirmation email to be sent to their email account.

Related Site Settings:

  • Authentication/Registration/LocalLoginEnabled
  • Authentication/Registration/ExternalLoginEnabled
  • Authentication/Registration/TwoFactorEnabled
  • Authentication/Registration/MobilePhoneEnabled

Set/Change Password

A user with an existing local account can apply a new password by providing the original password. A user without a local account can choose a username and password to setup a new local account. The username cannot be changed after it is set.

Related Site Settings:

  • Authentication/Registration/LocalLoginEnabled
  • 1) Create a username and password

  • 2) Change an existing password

Change/Confirm Email

Changing an email (or setting it for the first time) puts the email into an unconfirmed state. The user can request a confirmation email to be sent to the new email address including instructions on completing the email confirmation process.

Related Processes:

  • Send Email Confirmation To Contact
    • Customize the email in the workflow as necessary
  • 1) Submit a new email (unconfirmed)

  • 2) Check email for confirmation

  • 3) Process: Send Email Confirmation To Contact

  • 4) Customize the confirmation email

  • 5) Click the confirmation link to complete

Change/Confirm Mobile Phone

Changing the mobile phone value occurs slightly differently from changing the email. The new value is held in a temporary storage without changing the original value. A SMS message is sent to the new mobile phone number containing a security code. Only after the security code is submitted back to the portal (and verified) is the old mobile number replaced with the new value.

Related Processes:

  • Authentication/Registration/MobilePhoneEnabled

Related Processes:

  • Send Sms Confirmation To Contact
    • Note: the workflow for this process contains a temporary step that sends the security code by email. This is a placeholder step that needs to be replaced by a new step capable of sending SMS messages.
  • 1) Submit new mobile phone (unconfirmed)

  • 2) Wait for SMS with security code

  • 3) Process: Send Sms Confirmation To Contact

  • 4) Replace this email step with SMS step

  • 5) After submitting a valid security code

Enable Two-Factor Authentication

The two-factor authentication feature increases user account security by requiring proof of ownership of a confirmed email or mobile phone in addition to the standard local/external account sign-in. A user trying to sign into an account with two-factor authentication enabled is sent a security code to the confirmed email or mobile phone associated to their account. The security code must be submitted to complete the sign-in process. A user can choose to remember the browser that successfully passes the verification such that the security code is not required for subsequent sign-ins from the same browser.

Each user account enables this feature individually and requires either a confirmed email or confirmed mobile phone. User accounts with both may choose which method to receive the security code.

Related Site Settings:

  • Authentication/Registration/TwoFactorEnabled
  • Authentication/Registration/RememberBrowserEnabled

Related Processes:

  • Send Email Two Factor Code To Contact
  • Send Sms Two Factor Code To Contact
  • 1) Enable two-factor authentication

  • 2) Choose to receive security code by email or SMS

  • 3) Wait for email/SMS with security code

  • 4) Process: Send Email Two Factor Code To Contact

  • 5) Process: Send Sms Two Factor Code To Contact

  • 6) Two-factor authentication can be disabled

Manage External Accounts

An authenticated user may connect (register) multiple external identities to their user account. A single identity from each of the configured identity providers can be connected. Once connected, the user may choose to sign-in with any of the connected identities. Existing identities can also be disconnected as long as a single external or local identity remains.

Related Site Settings:

  • 1) Select a provider to connect

  • 2) Sign-in with provider to connect

  • 3) Provider is connected

  • 4) Provider can be disconnected

Enable ASP.NET Identity Authentication

The ASP.NET Identity authentication mode is enabled by modifying the web.config of the web application. When the system.web/authentication configuration element is configured for Forms authentication, the portal runs on the MembershipProvider based authentication API. Remove or comment out the authentication element to enable the newer ASP.NET Identity authentication system.

<configuration>
 <system.web>

  <!--
    Include the <authentication> element to use Membership Provider (<membership> element) authentication.
    Exclude the <authentication> element to use ASP.NET Identity authentication.
  -->

  <!--
  <authentication mode="Forms">
   <forms timeout="525600" loginUrl="~/login/" />
  </authentication>
  -->

 </system.web>
</configuration>

Configure Portal Content

The default portal content is setup for MembershipProvider based authentication and a few content changes are necessary to improve the portal experience for the new ASP.NET Identity authentication system.

  1. Remove the Change Password web link from the Profile Navigation web link set
    • In CRM, navigate to Portals > Web Link Sets and open the Profile Navigation web link set
    • Under the Links section, delete the web link named Change Password
  2. Remove the Change Password web page
    • Navigate to Portals > Web Pages
    • Deactivate or delete the Change Password webpage

Authentication Site Settings

Settings for enabling/disabling various authentication features and behaviours.

Site Setting Name Description
Authentication/Registration/LocalLoginEnabled Enables or disables local account sign-in based on a username (or email) and password. Default: true
Authentication/Registration/LocalLoginByEmail Enables or disables local account sign-in using an email address field instead of a username field. Default: false
Authentication/Registration/ExternalLoginEnabled Enables or disables external account sign-in and registration. Default: true
Authentication/Registration/RememberMeEnabled Enables or disables a "Remember Me?" checkbox on local sign-in to allow authenticated sessions to persist even when the web browser is closed. Default: true
Authentication/Registration/TwoFactorEnabled Enables or disables the option for users to enable two-factor authentication. Users with a confirmed email address or confirmed mobile number can opt into the added security of two-factor authentication. Default: true
Authentication/Registration/MobilePhoneEnabled Enables or disables the option to add and confirm a mobile phone number. When enabled, it is also necessary to update the Send Sms Confirmation To Contact process in CRM such that the workflow is able to send out SMS messages. Default: true
Authentication/Registration/RememberBrowserEnabled Enables or disables a "Remember Browser?" checkbox on 2nd-factor validation (email/SMS code) to persist the 2nd-factor validation for the current browser. The user will not be required to pass the 2nd-factor validation for subsequent sign-ins as long as the same browser is being used. Default: true
Authentication/Registration/ResetPasswordEnabled Enables or disables the password reset feature. Default: true
Authentication/Registration/ResetPasswordRequiresConfirmedEmail Enables or disables password reset for confirmed email addresses only. If enabled, unconfirmed email addresses cannot be used to send password reset instructions. Default: false
Authentication/Registration/TriggerLockoutOnFailedPassword Enables or disables recording of failed password attempts. If disabled, user accounts will not be locked out. Default: true
Authentication/Registration/IsDemoMode Enables or disables a demo mode flag to be used in development or demonstration environments only. Do not enable this setting on production environments. Demo mode also requires the web browser to be running locally to the web application server. When demo mode is enabled, the password reset code and 2nd-factor code are displayed to the user for quick access. Default: false
Authentication/Registration/LoginButtonAuthenticationType

If a portal only requires a single external identity provider (to handle all authentication), this allows the Sign-In button of the header nav bar to link directly to the login page of that external identity provider (instead linking to the intermediate local login form and identity provider selection page). Only a single identity provider can be selected for this action. Specify the AuthenticationType value of the provider.

For OAuth2 based providers the accepted values are: Facebook, Google,Yahoo,Microsoft, LinkedInYammer, or Twitter

For WS-Federation based providers use the value specified for the Authentication/WsFederation/ADFS/AuthenticationType and Authentication/WsFederation/Azure/[provider]/AuthenticationType site settings. Examples: http://adfs.contoso.com/adfs/services/trust, Facebook-0123456789, Google, Yahoo!, uri:WindowsLiveID.

Registration Site Settings

Settings for enabling/disabling user registration (sign-up) options.

Site Setting Name Description
Authentication/Registration/Enabled Enables or disables all forms of user registration. Registration must be enabled for the other settings in this section to take effect. Default: true
Authentication/Registration/OpenRegistrationEnabled Enables or disables the sign-up registration form for creating new local users. The sign-up form allows any anonymous visitor to the portal to create a new user account. Default: true
Authentication/Registration/InvitationEnabled Enables or disables the invitation code redemption form for registering users who possess invitation codes. Default: true

User Credential Validation Site Settings

Settings for adjusting username and password validation parameters. Validation occurs when signing up for a new local account or changing a password.

Site Setting Name Description
Authentication/UserManager/UserValidator/AllowOnlyAlphanumericUserNames Whether to allow only alphanumeric characters for the user name. Default: false. MSDN.
Authentication/UserManager/UserValidator/RequireUniqueEmail Whether unique e-mail is needed for validating the user. Default: false. MSDN.
Authentication/UserManager/PasswordValidator/RequiredLength The minimum required password length. Default: 6. MSDN.
Authentication/UserManager/PasswordValidator/RequireNonLetterOrDigit Whether the password requires a non-letter or digit character. Default: false. MSDN.
Authentication/UserManager/PasswordValidator/RequireDigit Whether the password requires a numeric digit ('0' - '9'). Default: false. MSDN.
Authentication/UserManager/PasswordValidator/RequireLowercase Whether the password requires a lower case letter ('a' - 'z'). Default: false. MSDN.
Authentication/UserManager/PasswordValidator/RequireUppercase Whether the password requires an upper case letter ('A' - 'Z'). Default: false. MSDN.

User Account Lockout Site Settings

Settings that define how and when an account becomes locked from authentication. When a certain number of failed password attempts are detected under a short period of time, the user account is locked for a period of time. The use can try again after the lockout period elapses.

Site Setting Name Description
Authentication/UserManager/UserLockoutEnabledByDefault Indicates whether the user lockout is enabled when users are created. Default: true. MSDN.
Authentication/UserManager/DefaultAccountLockoutTimeSpan The default amount of time that a user is locked out for after Authentication/UserManager/MaxFailedAccessAttemptsBeforeLockout is reached. Default: 00:05:00 (5 mins). MSDN.
Authentication/UserManager/MaxFailedAccessAttemptsBeforeLockout The maximum number of access attempts allowed before a user is locked out (if lockout is enabled). Default: 5. MSDN.

Data Migration Site Settings

Settings for enabling/disabling the migration of credentials created by previous authentication systems. Enable these settings when upgrading an existing portal containing registered users. ASP.NET Identity authentication stores credentials under a new set of fields and formats that are separate from the earlier MembershipProvider fields. In order to carry forward existing credentials, a data migration process is enabled to automatically transfer credentials as users sign-in to the portal.

Site Setting Name Description
Authentication/Registration/MembershipProviderMigrationEnabled

Enables or disables migration of existing MembershipProvider based credentials to ASP.NET Identity based credentials. Default: false

Enabling migration also requires the Authentication/Registration/LocalLoginByEmail setting to be set to false. Migration cannot be carried out for email based sign-in.

Authentication/Registration/GoogleOpenIdMigrationEnabled Enables or disables migration of Google OpenID 2.0 credentials to OpenID Connect credentials. Default: false

Cookie Authentication Site Settings

Settings for modifying the default authentication cookie behavior. Defined by the CookieAuthenticationOptions class.

Site Setting Name Description
Authentication/ApplicationCookie/AuthenticationType The type of the application authentication cookie. Default: ApplicationCookie. MSDN.
Authentication/ApplicationCookie/CookieName Determines the cookie name used to persist the identity. Default: .AspNet.Cookies. MSDN.
Authentication/ApplicationCookie/CookieDomain Determines the domain used to create the cookie. MSDN.
Authentication/ApplicationCookie/CookiePath Determines the path used to create the cookie. Default: /. MSDN.
Authentication/ApplicationCookie/CookieHttpOnly Determines if the browser should allow the cookie to be accessed by client-side javascript. Default: true. MSDN.
Authentication/ApplicationCookie/CookieSecure Determines if the cookie should only be transmitted on HTTPS request. Default: SameAsRequest. MSDN.
Authentication/ApplicationCookie/ExpireTimeSpan Controls how much time the application cookie will remain valid from the point it is created. Default: 14 days. MSDN.
Authentication/ApplicationCookie/SlidingExpiration The SlidingExpiration is set to true to instruct the middleware to re-issue a new cookie with a new expiration time any time it processes a request which is more than halfway through the expiration window. Default: true. MSDN.
Authentication/ApplicationCookie/LoginPath The LoginPath property informs the middleware that it should change an outgoing 401 Unauthorized status code into a 302 redirection onto the given login path. Default: ~/signin. MSDN.
Authentication/ApplicationCookie/LogoutPath If the LogoutPath is provided the middleware then a request to that path will redirect based on the ReturnUrlParameter. MSDN.
Authentication/ApplicationCookie/ReturnUrlParameter The ReturnUrlParameter determines the name of the query string parameter which is appended by the middleware when a 401 Unauthorized status code is changed to a 302 redirect onto the login path. MSDN.
Authentication/ApplicationCookie/SecurityStampValidator/ValidateInterval The period of time between security stamp validations. Default: 30 mins. MSDN.
Authentication/TwoFactorCookie/AuthenticationType The type of the two-factor authentication cookie. Default: TwoFactorCookie. MSDN.
Authentication/TwoFactorCookie/ExpireTimeSpan Controls how much time the two-factor cookie will remain valid from the point it is created. Default: 5 mins. MSDN.

External Identity Provider Site Settings

Third party identity providers can be integrated to allow users to authenticate through their existing social network user accounts. This integration occurs over protocols such as OAuth2, OpenID, and WS-Federation. For further details on adding specific external identity providers refer to the following: