Add and manage user accounts

You're viewing Apigee Edge documentation.
Go to the Apigee X documentation. info

Before users can start working with your Developer Services portal, they need to be added to the system. By default, any user can register on the developer portal by selecting the Register link in the portal menu. The user's account is then automatically authenticated and they are assigned to the authenticated user role.

You can customize your developer portal such that only users with admin privilege can add user accounts. In that case, an administrator needs to add user accounts manually. An administrator might also need to add user accounts manually for internal developers or to add developers on behalf of a customer.

After a user account is added, an administrator can assign a role to the user account, which associates the privileges for that role to the account. In addition, an administrator can manage an existing user account, including editing the user profile for the account, deleting the account, blocking or unblocking the account, or assigning a new role to the account. An administrator can also specify what happens to the user account and its associated content (for example, blog entries and forum posts) when the account is canceled.

The developer portal can automatically send emails to users when events occur. For example, the portal can send an email when a user is added, an account is blocked, or an account is canceled. As part of managing users, you can control the content and format of these emails. See Configuring email for more.

To learn how to manage registration workflows; customize registration emails; block IP addresses from registering; and create, manage, and block user accounts, watch this video.

Controlling who can register accounts

By default, any user can create an account from the developer portal by clicking on the Register link.

To control who can register accounts:

  1. Log in to your portal as a user with admin or content creation privileges.
  2. Select Configuration > People > Account settings in the Drupal administration menu. This opens the Account settings page.
  3. Click the appropriate registration option under "Who Can Register Accounts" in the Registration and cancelation section. The choices are:
    • Administrators only: Only administrators can register user accounts.
    • Visitors: Anyone can register. This is the default.
    • Visitors, but administrator approval is required: Anyone can register, but an administrator needs to authorize the account.
  4. Select or clear the checkbox for Require e-mail verification when a visitor creates an account. When unchecked, the developer is immediately logged in to the portal after registering. When checked, the user receives an email that they use to validate their email address before they can log in.
  5. Click Save configuration.

Adding a user account

Depending on your portal configuration, administrators must add users manually, or users can add themselves by selecting the Register link on the developer portal.

Adding a user account manually

To add a user account manually:

  1. Log in to your portal as a user with admin or content creation privileges.
  2. Select People > Add User in the Drupal administration menu.
  3. Enter content for the user in the First Name, Last Name, Username, Email address, and Password fields, and indicate acceptance of the user agreement.
  4. Optionally set the Status and Roles for the user.
  5. Select Notify user of new account to generate an automated email sent to the user.
  6. Click Create Account.

Registering a user from the developer portal

To register a user from the developer portal:

  1. The user selects Register on the developer portal home page.
  2. The registration page appears.
  3. The user enters the required information and selects Create new account.
    Depending on the new account registration settings, when the new account is created, the user is sent an automated welcome email.

Automating administrator notification when a new user registers

By default, when a new user registers on the portal, they receive an email. For more, see Configuring email.

However, portal administrators are not notified by default when a new user registers. For example, if you configure the portal so that new users need administrative approval to activate their account, you want to ensure that administrators are notified when the new account is created. Otherwise, the user account remains inactive.

To notify administrators when a new user registers an account:

  1. Log in to your portal as a user with admin or content creation privileges.
  2. Select Configuration > People > Admin Notification in the Drupal administration menu.
  3. Under User Alerts, specify who receives the email. You can direct it to:
    • Send to a custom email address
    • Send to a specific role. If you choose this option, you might want to create a new role. Otherwise, if you choose a role such as Administrator, then all administrators receive the email and it might not be applicable to all administrators.
    • Both
  4. Edit the message subject and body.
  5. Select to send the email when:
    • Receive Email upon user creation.
    • Receive Email upon user creation and update.
  6. Click Save configuration.

Managing a user account

Administrators can manage user accounts to set user information, reset passwords, activate accounts, cancel or suspend accounts, and to perform other tasks.

To edit the user profile for a user account:

  1. Log in to your portal as a user with admin or content creation privileges.
  2. Select People in the Drupal administration menu.
  3. Use the filter area at the top of the page to filter the display of users based on a specific username, email address, status, or permission. By default, "any" is selected for these filters, in which case, all users are listed on the page.

  4. Click Edit in the Username row for the user account. This opens an editable view of the user's profile.
  5. Change the user profile data as appropriate.
  6. Click Save.

Adding CAPTCHA

You can add a CAPTCHA challenge to the login page and other pages by enabling the Drupal CAPTCHA and reCAPTCHA modules. The reCAPTCHA module adds support for the free Google reCAPTCHA service.

Drupal supports other CAPTCHA modules, such as image CAPTCHA, that you can also use on the portal.

Video: Watch a short video about enabling CAPTCHA in the developer portal.

To enable reCAPTCHA:

  1. Log in to your portal as a user with admin or content creation privileges.
  2. Select Modules from the Drupal menu.
  3. Enable both the CAPTCHA and reCAPTCHA modules.
  4. Register for reCAPTCHA keys from Google at https://www.google.com/recaptcha/intro/index.html.
  5. Select Configuration > People > CAPTCHA > reCAPTCHA in the Drupal menu.
  6. Enter the Public Key (Google Site Key) and Private Key (Google Secret key). You can leave the rest of the settings with the default values.
  7. Select Configuration > People > CAPTCHA to set where you want the reCAPTCHA form to be presented. By default, it appears on the login and user registration forms.
  8. From that page, set the Challenge Type for each form.
  9. Save your changes.

Adding a Terms & Conditions page

You can add a Terms & Conditions page to the developer portal that users must accept when they log in before they are allowed to access the portal. If you later change the Terms & Conditions page, users will be required to accept the updated terms and conditions the next time that they log in.

The implementation of the Terms & Conditions page uses the Drupal Legal module. That module provides a flexible way to create a Terms & Conditions page, tracks revision history of the terms and conditions, and tracks users who have accepted the terms and conditions.

Once created, the Terms & Conditions page has the URL <siteURL>/legal.

To enable the Legal module:

  1. Log in to your portal as a user with admin privileges.
  2. Select Modules in the Drupal administration menu. The list of all installed Drupal modules appears.
  3. Scroll down the page and select the checkbox next to the Legal module.
  4. Click Save configuration.

To create a Terms & Conditions page:

  1. Log in to your portal as a user with admin privileges.
  2. Select Configuration > People > Legal in the Drupal administration menu.
    This menu item appears only when the Legal module is enabled. The top box on the page, under Most Recent Version/Revision, displays the current terms and conditions. If have not defined terms and conditions, this area is balnk. You create a new version in the Terms & Conditions area under Create New Version/Translation.
  3. Enter your terms of service in the Terms & Conditions area.
  4. Choose how you want to display the terms and conditions on the page: Scroll Box, Scroll Box (CSS), HTML Text, or Page Link.
  5. Optionally add additional checkboxes and a text area describing your latest changes.
  6. Select Preview to preview your terms and conditions in the Terms and Conditions of Use area under Most Recent Version/Revision, or Save to save them.

To monitor Terms & Conditions changes and acceptance:

  1. Log in to your portal as a user with admin privileges.
  2. Select Configuration > People > Legal in the Drupal administration menu.
  3. Select the T&C History tab to see the revision history of the terms and conditions.
  4. Select the Accepted tab to see the list of users who have accepted each version of the terms and conditions.

Redirecting a user on log in

By default, when a user logs in to the portal, they are directed to a page that displays their information, such as first and last name. Alternatively, you can use the Drupal Rules module to add a rule to automatically redirect the user to a different page. For example, you can redirect the user to the page that lists all of their apps or to the portal home page.

Before you can create a redirection rule, you must ensure that all the necessary Drupal modules are enabled.

Enable the necessary Drupal modules:

  1. Log in to your portal as a user with admin privileges.
  2. Select Modules in the Drupal administration menu.
  3. Enable the following modules if they are not already enabled:
    • 'me' Aliases (appears at the top of the modules list, not in its alphabetical location as do all other modules)
    • LoginToboggan
    • Rules
    • Rules UI
  4. Click Save configuration.
    You might see other required modules being enabled automatically.

Create a log in redirection rule:

  1. Log in to your portal as a user with admin privileges.
  2. Select Configuration > Workflow > Rules in the Drupal administration menu.
  3. Select + Add new rule on the Rules page.
  4. Specify the name of the rule: Login redirect.
  5. Optionally specify a tag as login.
  6. In the React on event dropdown box, select User > User has logged in.
  7. Select Save
    The Editing reaction rule page appears. You already set the event in the previous step, so it should say "User has logged" in under Event. Leave Conditions blank for this rule.
  8. Under Actions, select + Add action.
  9. Select System > Page Redirect in the dropdown.
    The Add a new action page changes its layout to let you specify the redirect URL.
  10. Under Value, specify user/[account:uid]/apps.
    [account:uid] is a replacement pattern that corresponds to the user's portal ID. To see the full list of replacement patterns, select Replacement patterns under the Value input box.
  11. Click Save to return to the Editing reaction rule page. That page should appear as shown below:
  12. Click Save changes.
    To later edit the rule, select Rules from the Configuration page, and then select Login redirect from the list of rules.

Now when a user logs in, they will be redirected to the page that lists all of their apps. If instead you wanted to redirect them to the home page of the portal, edit the Value you set above in step 11 to specify the URL of your portal's home page. For example, http://dev-myCompany.devportal.apigee.io/.

Setting user roles and permissions

A role defines a specific set of permissions that allow a user to perform certain activities. You grant privileges to a user or group of users by assigning the user to a role that has the necessary permissions. Administrators manage roles, including setting permissions for roles, on the developer portal.

By default, Drupal creates two roles:

  • anonymous user - The role for any user who has not logged in. Anonymous users are prevented from performing most actions.
  • authenticated user - The default role assigned to all users. You can assign a user to additional roles, but they are always assigned to this role.

In addition, Apigee has added the role of administrator. Assign users to the administrator role to give them administration rights to the portal.

Typically, you add roles to your portal so that you can differentiate permissions based on different user types. A user can be in a single role or in multiple roles. All users are assigned to the authenticated user role, but if you want to assign a user to additional roles you must add logic to your portal or perform the role assignment manually.

To see all roles and permissions:

  1. Log in to your portal as a user with admin or content creation privileges.
  2. Select People > Permissions > Roles in the Drupal administration menu.

To add a new role:

  1. Select People > Permissions > Roles.
  2. Enter a new role name in the text box above the Add role button on the People page.
  3. Click Add role.

To edit a role:

  1. Select People > Permissions > Roles.
  2. Click edit role in the row of the pertinent role on the People page.
  3. Change the role name, as appropriate.
  4. Click Save.

To delete a role:

  1. Select People > Permissions > Roles.
  2. Click edit role in the row of the pertinent role on the People page.
  3. Click Delete role.

To add a user to a role:

  1. Log in to your portal as a user with admin or content creation privileges.
  2. Select People in the Drupal administration menu.
  3. Click Edit in the Username row for the user account. This opens an editable view of the user's profile.
  4. Select all roles for the user as appropriate.
  5. Click Save.

To change the permissions for a role:

  1. Select People > Permissions > Roles.
  2. Click the Permission tab on the People page.
    A table of roles and permissions is displayed. Checkmarks in the table indicate which permissions are assigned to which roles.

  3. Check or uncheck a checkbox to grant or revoke the associated permission to that role, respectively.
    For example, to prevent authenticate users from being able to create or delete apps, scroll down to the DevConnet Developer Apps section of the permissions table and uncheck the boxes for Create Developer Apps and Delete Developer Apps under authenticated users.
  4. Click Save permissions.

Customizing the form fields used to register a user

When the user registers for an account on the portal, the portal displays the default registration page with fields for First Name, Last Name, Username, Email address, and Password. As an API provider, you might want to modify this form to prompt the user to provide additional information such as a company name, mailing address, or other information. The portal provides you with a the ability to add new fields to this form. These fields can be:

  • Required or optional
  • Displayed by different HTML elements, such as text boxes, radio buttons, check boxes, and more
  • Can be set to appear anywhere on the form

To learn how to customize the user registration form available from the developer portal, watch this video.

For example, you might add a required field for Company Name, or an optional field for Phone Number. Or, you might add several fields, both optional and required.

The following image shows a required field for Company Name added to the form:

As a portal administrator, you can view and edit the user's information, including any custom fields, by:

  1. Selecting People in the Drupal administration menu on the portal.
  2. Selecting Edit in the row corresponding to the user's name.

This is the primary way that you, as an administrator, access user information.

By default, when you add new fields to the form, the field values are not uploaded to Edge. However, you can configure the portal to upload those values when the user submits the form. That means you can view those fields on Edge, or use the Edge management API to access those fields from a script.

For example, view the new form fields In the Edge management UI by going to Publish > Developers, and then selecting the user name. The new field values appear under the Custom Attributes area of the page with a name that corresponds to the field's internal name:

To add a field to the user registration form:

  1. Log in to your portal as a user with admin or content creation privileges.
  2. Select Configuration > People > Account Settings in the Drupal administration menu.
  3. Select the Manage fields button at the top of the page.
  4. Scroll down the page to the Add new field area:
  5. Configure the field. For example, for the Company Name field shown above, use the following settings:
  6. Select Save.
  7. Because this is a text field, you are prompted to specify the maximum length of the field.
  8. Enter the maximum length, and the select Save field settings.
  9. A new page appears that lets you specify additional information for the field, including:
    • A check box to set this as a required field.
    • A check box to specify to display the field.
    • Optional help text that appears a popup in the form.
    • Other settings.
  10. Make sure to select the check box to make this a required field.
  11. If you make any changes on this page, save your settings.
    You might have to clear your browser cache before the new field appears on the form.

To reorder the attributes on the form:

By default, new required fields appear in the form after the Last Name field. Optional fields appear at the bottom of the form, after the password fields.

  1. Log in to your portal as a user with admin or content creation privileges.
  2. Select Configuration > People > Account Settings in the Drupal administration menu.
  3. Select the Manage fields button at the top of the page.
  4. Select the plus, +, symbol under the Label column and drag the field to the location where you want to display it in the form.
  5. Save your changes.

Saving form field values as custom developer attributes in Edge

You can save form field values to custom developer attributes in Edge. You can view and manage custom attributes for a developer as described in Managing app developers.

After the custom developer attributes are saved, you can use the Access Entity policy, for example, to enable dynamic behavior based on the custom attribute values.

To learn how to save form field values as custom developer attributes, watch this video.

To save the field values as custom developer attributes in Edge:

  1. Log in to your portal as a user with admin or content creation privileges.
  2. Select Configuration > Dev Portal > Developer Attributes in the Drupal administration menu.
    A list of the available fields is displayed.
  3. Select the field that you want to persist as an attribute in Edge, such as Company Name.
  4. Set the checkbox for Persist this field as an attribute in Edge.
  5. Specify the Edge attribute name. This is the name that appears in the Name column of the Custom Attributes table for the user.
  6. Specify the behavior for an empty field/
  7. Select the Convert value to true|false string if you want to cast the value as a boolean and convert it to a true or false string before sending to Edge.
  8. Click Save configuration.
    Now the custom attribute will be uploaded to Edge when the user submits the form. If, as an administrator, you want to change the value of a custom field, do it from the portal, not from Edge.

Creating a default app when a user registers a new account

You can automatically create a default app when a user registers a new portal account. When the user logs in for the first time, the app appears on their My Apps page. Depending on the permissions assigned to the user's role, you may let the user add additional apps, or this can be the only app available to the user.

You have complete control over the properties of the default app, including:

  • The API products included by the app
  • The app state: pending or approved
  • The callback URL, if necessary
  • Custom parameters applied to the app

The way you control the creation of a default app is to create a rule by using the Drupal Rules module. A rule lets you define an action that occurs in response to an event on the portal. In this scenario, the event is a user registering for an account on the portal. The action is to create a default app for the user.

The section Customizing the form fields used to register an app describes how to add custom attributes that are used to configure an app. These attributes can be optional or required, depending on how you define them. If you have created any custom app attributes, then you have the ability to set them when defining a default app.

Enable the Drupal rules modules:

  1. Log in to your portal as a user with admin privileges.
  2. Select Modules in the Drupal administration menu
  3. Enable the following modules if they are not already enabled:
    • 'me' Aliases (appears at the top of the modules list, not in its alphabetical location as do all other modules)
    • LoginToboggan
    • Rules
    • Rules UI
  4. Click Save configuration.
    You might see other required modules being enabled automatically.

Create a rule to add a default app:

  1. Log in to your portal as a user with admin privileges.
  2. Select Configuration > Workflow > Rules in the Drupal administration menu.
  3. Select the +Add new rule button.
  4. Specify the Name of the rule.
  5. Optionally specify login in the Tags field, or any other tag that you want to use to categorize the rule.
  6. In the React on event dropdown box, select User > After saving a new user account.
  7. Select Save.
    The rule editing page appears. You already set the event in the previous step, so it should say "After saving a new user account" under Event.
  8. Leave Conditions blank for this rule.
  9. Under Actions, select + Add action.
  10. Select Devconnect > Create a developer application in the dropdown.
    The Add a new action page changes its layout to let you configure the app.
  11. Under API Name, specify the name of the default app. For example, use [account:field_last_name] Application.
    The [account:field_last_name] value is a replacement pattern that corresponds to the user's last name. To see the full list of replacement patterns, select Replacement patterns under the Value input box.
  12. Set Developer UID to [account:uid]. This value is required to associate the user with the app.
  13. Set the app Status to pending or approved. Set it to pending if an administrator still as to approve the app before the user can use it to access your APIs.
  14. If required, set the Callback URL for the app. This field only appears if you configured apps to require a callback URL. For more information on configuring callback URLs, see Configuring callback URL handling.
  15. If you defined any custom app attributes, either optional or required, set them. For more information, see Customizing the form fields used to register an app.
  16. Specify the API Products included in the app.
    The Value text area must list each API product on a separate line, with no commas or other delimiters. The list of available API products is shown above the Value text area.
  17. Click Save to return to the Editing rule page.
  18. Click Save changes.
  19. To later edit the rule, select Configuration > Workflow > Rules in the Drupal administration menu, and then select the rule from the list of rules.

When a new user logs in to the portal for the first time and selects the My Apps link in the menu, they now see an app named lastName Application, where lastName is the last name used when the user registered the account.

Administrating user apps

As a portal administrator, you can use the Developer Apps report to manage user apps directly from the portal. From that report, an administrator can view information about a user's app, modify the app, or delete the app. For example, a portal administrator can modify the app to add or remove API products, change the callback URL, or make other changes.

To administrate a user app:

  1. Log in to your portal as a user with admin privileges.
  2. Select Reports > Developer Apps in the Drupal administration menu. A sortable list of user apps appears.
  3. For any app in the list:
    • Select the Edit link to edit the app properties.
    • Select the Delete link to delete the app.

Cancelling a user account

A portal administrator can cancel a user account. The admin can cancel an individual account, or can cancel multiple accounts in bulk.

To cancel an individual user accounts:

  1. Log in to your portal as a user with admin privileges.
  2. Select People in the Drupal administration menu.
  3. Under the Operations column of the table of users, select Cancel account.
  4. Click the appropriate cancelation option under "When cancelling a user account". The choices are:
    • Disable the account and keep its content: (Default) The user account and its related content are retained. However, the user account is blocked from accessing API resources. This is the default. An administrator can subsequently unblock the user account.
    • Disable the account and unpublish its content: The user account is retained. However, content associated with the user account is removed. The user account is blocked from accessing API resources. An administrator can subsequently unblock the user account.
    • Delete the account, but make its content belong to the Anonymous user: The user account is deleted. Content associated with the user account is retained, but is associated with the "Anonymous" user account, that is, an account that has not authenticated. The user account cannot be reenabled. The user needs to reregister and the user's account needs to be authenticated before accessing API resources.
    • Delete the account and its content: The user account and its related content are deleted. The user account cannot be reenabled. The user needs to reregister and the user's account needs to be authenticated before accessing API resources.
  5. If you want the user to receive an email asking them to confirm the cancellation, select "Require e-mail confirmation to cancel account".
    If you select this option, the user's account must have the correct permissions to allow the cancellation. Select People > Permissions and ensure that the "authenticated user" role has the "Cancel own user account" permission set.
  6. Click Cancel account.

To cancel multiple user accounts:

  1. Log in to your portal as a user with admin privileges.
  2. Select People in the Drupal administration menu.
  3. Under Operations, select Cancel user account in the dropdown.
  4. Select the checkbox next to each user whose account you want to cancel.
  5. Select the Execute button.
  6. Click the appropriate cancelation option under "When cancelling a user account". The choices are:
    • Disable the account and keep its content.
    • Disable the account and unpublish its content.
    • Delete the account, but make its content belong to the Anonymous user.
    • Delete the account and its content.
  7. Click Next.
  8. Click Confirm.

Setting the default action when an account is canceled

Administrators of the developer portal can set the default action of the portal when a user account is canceled.

To set the default action when an account is canceled:

  1. Log in to your portal as a user with admin or content creation privileges.
  2. Select Configuration in the Drupal administration menu.
  3. Select Account settings.
  4. Click the appropriate cancelation option under "When cancelling a user account" in the Registration and cancelation section. The choices are:
    • Disable the account and keep its content.
    • Disable the account and unpublish its content.
    • Delete the account, but make its content belong to the Anonymous user.
    • Delete the account and its content.
  5. Click Save configuration.