Adding Users to Your DSP | Dreamfactory
by Terence Bennett • July 6, 2018
Whether its adding consumers, collaborators, or customers, DreamFactory DSP provides several ways to add users to your DSP. Once added, you control what they can do by provisioning their role-based accesses.
The following is a quick summary of the supported ways in which you can get more users on your DSP. You can utilize the user interfaces that we have built into your DSP, or build your own using the convenient API calls right from your application itself. For more information on user and role-based configuration, see our documentation.
For The Control Freak In All Of Us
The administrator account on your DSP has complete control over how users are added to the system. By default, only those with system administrator privileges can add users to the system. This is the most restrictive case. A system administrator logs into the DSP, goes to the admin view by selecting the gear icon in the upper right, selects the User section from the menu at left, and clicks Create New User.
Select the system administrator checkbox or the desired role, select whether or not you want to activate this user for access via login, and finally, to assign the password directly, select "Skip email confirmation..." and set the desired password. You can return to this user to change the password directly later if needed.
Similarly, an admin, or a user that has been given create user role permissions (see our Role documentation), can send a request to the REST API to create a user by posting similar user data to /rest/system/user as follows.
curl -X POST https://dsp-mydsp.cloud.dreamfactory.com/rest/system/user/
-H 'X-DreamFactory-Application-Name: admin'
-d '
{
"display_name":"Joe Smith",
"first_name":"Joe",
"last_name":"Smith",
"email":"joe.smith@acme.com",
"phone":"555-666-7777",
"is_active":true,
"is_sys_admin":false,
"role_id":1,
"password":"password"
}'
This is useful for creating consumer accounts for things like opening up services for other web servers or test account access, or for creating specific users with default passwords, which they can change later. Note that using this part of the REST API requires a valid session, i.e. the admin must be logged in. Also note that the password can only be set and never retrieved via the API for security reasons.
Invite Only the Friends You Really Like
In the aforementioned example of adding a user, for "real person" user accounts, the system admin is usually not concerned with directly managing user's passwords. A more popular way to add users would be to invite them and let them manage their own passwords. In this case, the admin still creates the user with email address, role, etc, but does not set a password. This user is created in a suspended state until a password is set.
If a default email service is setup, the email service can be used to notify the user via their email address that they are invited to the system. This can be accomplished in the previous Create User screen by not selecting the "Skip email confirmation..." checkbox. Likewise, in the API request mentioned earlier, just leave off the "password" in the posted data. Utilizing the email service to invite the user is as follows.
curl -X POST https://dsp-mydsp.cloud.dreamfactory.com/rest/email/
-H 'X-DreamFactory-Application-Name: admin'
-d '
{
"to": "joe.smith@acme.com",
"subject": "Welcome to DreamFactory",
"body_html": "Hi {first_name},You have been invited to become a DreamFactory user. Click the confirmation link below to set your password and log in.
{_invite_url_}
Enjoy!
DreamFactory",
"from_name": "DreamFactory",
"from_email": "no-reply@dreamfactory.com",
"reply_to_name": "DreamFactory",
"reply_to_email": "no-reply@dreamfactory.com",
"first_name": "Joe"
}'
That user can then follow the link in the email and complete the password requirement. Keep reading for more on the email service and password reset capabilities of the DSP.
Sign Me Up
So maybe you have developed an app and want more of an open approach to adding users, no individual invites or manual data entry, but you still want to know who they are and control their access via roles, etc. Well, that is what we call Open Registration. This feature, once enabled, gives visitors to your DSP the opportunity to sign up to be a user and access your app and services.
To enable Open Registration, a system administrator logs into the DSP, goes to the admin view by selecting the gear icon in the upper right, selects the Config section from the bottom of the menu at left, and checks the "Allow open registration" checkbox.
Once selected, you will see the option to assign every new user who comes in through the registration process a default role. Obviously you will want to limit what the users can do at first and then possibly upgrade them later to a different role that allows for more permissions. To do the same thing through the API, you would issue the following command.
curl -X PUT https://dsp-mydsp.cloud.dreamfactory.com/rest/system/config/
-H 'X-DreamFactory-Application-Name: admin'
-d '{ "allow_open_registration": true, "open_reg_role_id": 1 }'
Refresh the Launchpad view and you will see a new button called Create Account. Clicking this button will take you to a page to sign up for an account.
By default, when Open Registration is enabled, email validation for registration is disabled. This means that the user that wants to sign up gives their email address, etc. and password all in one shot without any kind of verification.
curl -X POST https://dsp-mydsp.cloud.dreamfactory.com/rest/user/register/
-H 'X-DreamFactory-Application-Name: admin'
-d '
{
"display_name": "Joe Smith",
"first_name": "Joe",
"last_name": "Smith",
"email": "joe.smith@acme.com",
"password": "password"
}'
This is useful when you don't really care if the email/username is a valid email or not. In most cases, especially where the email address is used for other contact purposes, you will want to validate the email address given. To do this, go back to the Open Registration configuration and see the "Select an email service..." section. Select an email service from the drop down list. Note that a default email service comes with your DSP, but you may wish to add or change its configuration to meet your needs. See our documentation for Services options. The system comes with a default email template internally. To customize, create your own template at the bottom of this configuration screen and select it here. More on email templates can be found in our documentation.
With this configuration, no password is required initially. Once registered, an email is sent, if following our template guidelines, with a confirmation code and a link to a confirmation page where that code will be entered along with the desired password for the account.
The link in the email will take the user to a confirmation page where the code and password are applied.
curl -X POST https://dsp-mydsp.cloud.dreamfactory.com/rest/user/register/
-H 'X-DreamFactory-Application-Name: admin'
-d '
{
"email": "joe.smith@acme.com",
"code": "08dda8621c8fc3434646432dbbab51a6",
"password": "password"
}'
Once confirmed, this new user will automatically be logged in with the role given for open registration.
A word about passwords...
On the Config screen mentioned early, you may have seen a Password Reset section. By default, password resets are performed using a security question and answer setup that can be provisioned via a user's profile (see the user icon on the LaunchPad bar once logged in). However, very much like Open Registration, if you would like a more secure way to handle password resets, you can enable email confirmation by selecting an email service and optionally a template.
In the sign in dialog, to initiate a password reset, type in your email address and click the Forgot Password button.
To do this from the API, similarly post a reset request to the user password resource.
curl -X POST https://dsp-mydsp.cloud.dreamfactory.com/rest/user/password/
-H 'X-DreamFactory-Application-Name: admin'
-d '{ "email": "joe.smith@acme.com", "reset": true }'
Like registration, an email is sent with a link and a confirmation code. Enter the code, and a new password to reset the existing password.
A confirmation request is sent to the API as follows.
curl -X POST https://dsp-mydsp.cloud.dreamfactory.com/rest/user/password/
-H 'X-DreamFactory-Application-Name: admin'
-d '
{
"email": "joe.smith@acme.com",
"code": "08dda8621c8fc3434646432dbbab51a6",
"password": "password"
}'
Once confirmed, this user will automatically be logged in with the new password.
Ticket Please
As with many websites today, sometimes it is easier if someone else handles the user confirmation and password maintenance, like the most popular social or enterprise websites. For these cases, DreamFactory can be configured to allow access via an OAuth service. This is currently tied to Open Registration being activated. Once provisioned, your allowed OAuth services will show up on the login screen. For more information on OAuth provisioning, see this blog.
The Door's Open, Come On In
There may be some functionality in your app that you want everyone to see or be able to use. If that is the case, we have a configuration for that as well. It is called Guest Users. Again, on the config screen in the admin view, there is a place to allow guest access and assign them a specific restrictive access role.
curl -X PUT https://dsp-mydsp.cloud.dreamfactory.com/rest/system/config/
-H 'X-DreamFactory-Application-Name: admin'
-d '{ "allow_guest_user": true, "guest_role_id": 1 }'
Once enabled, you will see that when accessing your DSP, you are not immediately met with a login prompt, but the Sign In button (and optionally a Create Account button) are also there allowing returning users to gain access as their assigned role.
Check out our video tutorials and documentation for more information on these topics. As always, we welcome your comments.
Terence Bennett, CEO of DreamFactory, has a wealth of experience in government IT systems and Google Cloud. His impressive background includes being a former U.S. Navy Intelligence Officer and a former member of Google's Red Team. Prior to becoming CEO, he served as COO at DreamFactory Software.
