View source for Documentation:SysUserAuthentication

You can add registration, password sign-in, external sign-in, and role-based access control to a Turnkey application by merging the '''SysUserAuthentication''' model pattern into your MDriven Designer model.

This pattern uses the ASP.NET Core Identity architecture to add user registration and sign-in. It handles both authentication (who you are) and authorization (what you are permitted to do).
[[File:SysUserAuthentication-Pattern.png|alt=SysUserAuthentication Pattern|none|thumb|896x896px]]
The Pattern supports external login using Google, Open ID, Microsoft, Facebook. [[Documentation:External login services in MDriven Turnkey|Check here]] for details on how to login with third party providers.
== What the pattern provides ==
The SysUserAuthentication pattern adds model classes that support '''authentication''' and '''authorization''' in a [[Documentation:TurnkeyUserLogin|Turnkey user login]] flow.

* '''Authentication''' establishes who the user is. For example, a person registers with a user name and password, then signs in with those credentials.
* '''Authorization''' determines what the signed-in user may access. For example, you can use a role and an access group to make an administrative ViewModel available only to administrators.

The pattern is based on the ASP.NET Core Identity architecture. It supports password-based registration and sign-in, and can support external sign-in providers including Google, Open ID, Microsoft, and Facebook. Configure and use external-login options as described in [[Documentation:TurnkeyUserLogin|Turnkey User Login]].
== Add the pattern to your model ==
# Download the SysUserAuthentication model from the Model Examples area of the wiki.
# Open your application model in '''MDriven Designer'''.
# Merge the downloaded model file into your model from TK Live View.
# Save the model.
# Start the local Turnkey Prototyper.
# Register a test user with an email address and password.
# Verify the result in the debugger by evaluating <code>SysUser.allinstances</code>. The collection should include the newly registered '''SysUser'''.

For a guided exercise that also covers the default superclass, singleton, login, and access groups, follow [[Training:Bootcamp:Chapter 11|Bootcamp Chapter 11]].
== Model classes ==

=== SysUser ===
'''SysUser''' represents an application user. Together with [[Documentation:SysUser|SysSingleton]], it participates in the login pattern.

{| class="wikitable"
! Member
! Type
! Purpose
|-
| '''isAdmin'''
| Boolean?
| Indicates whether the user has administrator permissions.
|-
| '''PasswordHash'''
| String?
| Stores the password hash rather than a plaintext password.
|-
| '''SecurityStamp'''
| String?
| Invalidates sessions and cookies when the user resets a password or adds an external login.
|-
| '''SendMeNews'''
| Boolean?
| Indicates whether the user subscribes to the newsletter.
|-
| '''UserName'''
| String
| The user's unique user name.
|}

{| class="wikitable"
! Method
! Arguments
! Returns
! Use
|-
| '''HashPassword'''
| <code>pwd: String</code>
| String
| Hashes a password. Use this when you need the password hash value.
|-
| '''SetPassword'''
| <code>pwd: String</code>
| —
| Sets '''PasswordHash''' by using '''HashPassword'''. Use this method when assigning a new password instead of setting '''PasswordHash''' directly.
|}

For example, when an authenticated user chooses a new password, pass the new password to '''SetPassword'''. The method updates the user's stored password hash; do not store the entered password in '''PasswordHash''' as plaintext.

Password-reset tickets, expiry, and reset UI are provided by the separate [[Documentation:Password Reset Package|Password Reset Package]].

To set a new password, use the HashPassword method as follows:
This method is used to set a new PasswordHash for a user using the HashPassword method.
<syntaxhighlight>
self.PasswordHash:=self.HashPassword(pwd)
</syntaxhighlight>
=== SysExternalLogin ===
'''SysExternalLogin''' handles a user's third-party login. For example, when a user signs in through Google, Microsoft, or Facebook, the external-login information is handled through this class rather than through a local password alone.

See [[Documentation:TurnkeyUserLogin|Turnkey User Login]] for the available Turnkey login options.
=== SysRole ===
'''SysRole''' defines user roles. Use roles together with access groups to control which ViewModels different user groups can access.

For example:
# Create an administrator access group.
# Build the access-group expression so that it identifies administrator users, such as users with '''isAdmin''' set.
# Assign that access group to an administrative ViewModel in the ViewModel Editor.
# Verify that the ViewModel is hidden or inaccessible when you are not signed in as an administrator.

In the Bootcamp exercise, a ViewModel is assigned to the '''IsLoggedIn''' access group. It is not available before sign-in and becomes available after sign-in. Learn how access groups control ViewModel permissions in [[Documentation:Access control system in MDriven|Access control system in MDriven]].
== Sessions and sign-in activity ==
The authentication merge model also includes [[Documentation:SysSession|SysSession]]. A SysSession tracks user login activity, including the user-agent and IP address used for the login.

Use SysSession when you need to inspect login activity associated with users. Keep session tracking separate from the definition of the user itself: '''SysUser''' represents the user account, while '''SysSession''' records login activity.
== Test the integrated flow ==
After merging the pattern, test both the account flow and access restrictions.

# Start the local Turnkey Prototyper.
# Confirm that an unauthenticated visitor cannot access a ViewModel assigned to an '''IsLoggedIn''' access group.
# Register a new user and sign in.
# Confirm in the debugger that a '''SysUser''' was created.
# Confirm that the signed-in user can now access the ViewModel assigned to '''IsLoggedIn'''.
# Assign an administrator-only access group to a test ViewModel.
# Test with a non-administrator and an administrator user to confirm that the access-group expression gives the intended result.
== Related login features ==
* For Turnkey login choices, social login, simulated login, and hiding password login, see [[Documentation:TurnkeyUserLogin|Turnkey User Login]].
* For password reset, including reset-ticket expiry and password update behavior, see [[Documentation:Password Reset Package|Password Reset Package]].
* For the downloadable ASP.NET Identity model package, see [[Documentation:Asp.Net Identity package|ASP.NET Identity package]].
* If registration has been turned back on in MDrivenServer and does not work as expected, see [[Documentation:Change password MDriven Server|Change password MDriven Server]].
== See also ==
* [[Documentation:TurnkeyUserLogin|Turnkey User Login]]
* [[Documentation:SysUser|SysUser]]
* [[Documentation:SysSession|SysSession]]
* [[Documentation:Password Reset Package|Password Reset Package]]
* [[Documentation:Access control system in MDriven|Access control system in MDriven]]
* [[Training:Bootcamp:Chapter 11|Bootcamp Chapter 11]]

[[Category:Authentication & Security Integration]]
[[Category:Integration]]
[[Category:Intermediate-Friendly]]
[[Category:OAuth2 & OpenID Connect (SSO)]]
[[Category:Priority 50]]