User Management Blocks

Stable version 1.0.2 (Compatible with OutSystems 11)
Published on 26 Feb by 
0.0
 (0 ratings)

User Management Blocks

Documentation

Interface


RequestPasswordReset


Inputs

LookupByEmail: (Boolean) Specifies if the account should be looked up email address.  Default value is false and will lookup by username.

Events

ResetRequested: Fires on the button click and returns the list of user ids associated with the username or email address

PasswordResetRequestIds: A list of PasswordResetRequest Ids associated with the username or email address submitted. This list can be used to generate tokens to send to the users.  Only accounts with valid email addresses will successfully generate a PasswordResetRequest Id.

Usage

Drop this block on screen that you can redirect to from the “Forgot Password” link on your login screen.  It helps if the screen is anonymous since the user most likely isn’t logged in if they forgot their password.  Handle the ResetRequested event with a new client action.  In this client action you need to have a call to something that will handle the list of request ids passed into the event.  A server action that generates a token for each id and then sends an email to the requestor is recommended, but how you communicate with the user is up to you.  Ultimately you’ll want to supply the user with a tokenized URL to the password reset screen in your application. 

Security Note: when handling the event, if the list of ids is empty then no user was found for the username or email address the user entered.  It is best practice to indicate that an email will be sent, but that if they don’t receive an email then double check if they entered the correct username or email address.  You should not indicate to the user that a user wasn’t found since the absence of that message will inform a would-be attacker that they’ve stumbled upon a valid username or email address.


ResetPassword


Inputs

Token: (Text) Security token to authenticate anonymous users. Generated by calling GenerateResetPasswordToken

Events

Failure: Fires if the password reset fails after the token is validated.

Messages: (List of text) Error messages indicating the cause of the failure.

InvalidToken: Fired if the token is invalid for any reason.

Messages: (List of text) Information related to the invalid token.

Success: Fires if the password reset succeeds

Usage

Place this block on a screen.  The screen should be anonymous and take an optional Token input parameter which you can pass through to the block.  The token is optional since this block will validate differently depending on if a current logged in user exists.  During validation of the token the block handles the validation as such:

Token value

GetUserId() value

Validation result

Empty

Null Identifier

Validation fails

Empty

Valid Identifier

Validation succeeds.  Password reset is for current user.

Not empty

Anything

Validation depends on token validation.  Password reset is for the user specified in the token.


Handle the events for Failure, InvalidToken, and Success as you see fit.


Onboard


Inputs

Token: (Text) Security token to authenticate anonymous users.  Generated by calling GenerateOnboardToken

Events

Failure: Fires if the onboarding fails to create a user after the token is validated.

Messages: (List of text) Error messages indicating the cause of the failure.

InvalidToken: Fired if the token is invalid for any reason.

Messages: (List of text) Information related to the invalid token.

Success: Fires after creating the new user.

UserId: (User Identifier) User Id of the new user.

UserExists: Fires if the user already exists.

UserId: (User Identifier) User Id of the existing user.

Usage

I like to put this block on my login screen, and then control its visibility with an If block.  If the token is present I display the Onboard block, and if the token is empty I show the regular login form instead.  You can place it on any anonymous screen you want.  The screen should have a Token input parameter that you can pass into the Onboard block.  Once the token is validated by the block, the form fields are pre-populated to the values set in the token.  The token will also dictate which fields are mandatory, visible, and enabled.  The block has a special validation in the case where username is editable.  If the username entered by the user is in use they will receive a form validation message and the UserExists event will not be fired.  You can handle the events as you see fit.

Note: Normally we use this block to control access to our applications through invitation.  We have some administration screen where we fill out the user details, create the token, and then send an email to the user with a link to the Onboarding screen where this block would validate the token and create the user. If your use case is to allow wide-open access for anybody to create self-serve accounts you could generate the token when the screen loads, with the rules indicating that all fields are editable. 


Logic


GenerateOnboardToken


Inputs

OnboardRules: (OnboardRules structure) A set of rules for the onboarding process.

ExpiresOn: (DateTime) Token expiry date.

Outputs

Token: (Text) The new security token.  Use this to pass into the Onboard block.

Usage

Call this action to generate a token which can be passed to the Onboard block to allow an anonymous user to create an account.  The OnboardRules parameter is a structure which will control the way the Onboard block renders the form inputs, and their values.  The OnboardRules structure contains five attributes, one for each of the settable attributes on the User entity.  It also contains an AdditionalClaims attribute, which is a list of Name/Value pairs.  AdditionalClaims can contain any information you wish to pass along with the token for use in the Success handler:

Each of the attributes is of type ClaimField, which is another structure in the module:

Value will dictate the initial value of the field.  IsOptional will make the field optional when true, and mandatory when false.  IsEditable will make the field editable when true, and read-only when false.  IsHidden will make the field invisible when true, and visible when false.  All the Boolean attributes are false by default.  This means if you don’t set any values for the default structure, your Onboard block will show all fields as mandatory, read-only, and visible.  The Onboard block also has logic that will cause the token to be invalid if you have mandatory fields that are hidden or disabled, and have no initial value.


GenerateResetRequestToken


Inputs

PasswordResetRequestId: (PasswordResetRequestIdentifier) The PasswordResetRequest id to place in the token claims.

ExpiresOn: (DateTime) Token expiry date.

Outputs

Token: (Text) The new security token.  Use this to pass into the ResetPassword block.

Usage

Once the user has used the ResetPasswordRequest block, the logic in your ResetRequested event handler can use the ids from the event parameter to pass into GenerateResetRequestToken.  Once the token is generated it can be communicated to the user however you see fit.


GetPasswordResetRequestDetails


Inputs

PasswordResetRequestId: (PasswordResetRequestIdentifier) The PasswordResetRequest id to get details for.

Outputs

PasswordResetRequestDetail: (PasswordResetRequestDetail structure)

Usage:

As you are handling the ResetRequested event, you may want to convey some of the details of the request to the user in the email, or whichever communication method you choose.  The PasswordResetRequestDetail structure is as follows:

Id: The PasswordResetRequestId

UserId: The user id of the account the reset was requested for.

RequestedOn: The date and time the request to reset the password was made.

IPAddress: The IP address of the requestor.

UserAgent: The User Agent string of the requestor.

Requested Using: The search term used to discover the account. (Either the username or the email address associated with the account)

ResetOn: If the token has been used, the ResetOn field will have a value.  (A password reset token is only valid for a single use)


CSS


The styling of the blocks should follow closely to your application’s theme, but there are some classes that can be overridden in the event you need to customize the CSS.

Module level


.user-management-invalid-token {

    text-align: center;

    color: var(--color-red-darker);

}


.user-management-messages {

    text-align: left;

    color: var(--color-red-darkest);

}


Onboard block


.user-management-field .form-control[data-input][disabled] {

    background-color: var(--color-neutral-0);

    color: var(--color-neutral-10);

    border: none;

    margin-bottom: var(--space-base);

}


ResetPasswordRequest block


.password-reset-request {} This class is set on the form, but is not defined in CSS.

.search-term {}  This class is set on the container, but is not defined in CSS.

.button-container {}  This class is set on the container, but is not defined in CSS.