Using the user commands

You can use the user commands to complete some Drupal user management tasks on your Developer Portal, such as adding and removing roles, blocking and unblocking users, and retrieving user information.

About

In the Developer Portal, user management tasks can be completed by using the Developer Portal UI (see People), or by using the toolkit CLI as described in the following instructions. You can use these toolkit CLI commands to help you facilitate the user management process. For example, you could integrate these commands into your CI/CD processes, to find out information about inactive users that need to be notified of account deletion.

Procedure

Log in as Provider org:
```
apic login --server management_server --realm provider/identity_provider --username provider_username --password provider_password
```
You can determine which identity provider to use in the --realm parameter by entering the following command to see a list of all available identity providers (you do not need to be logged in to use this command):
```
apic identity-providers:list --scope provider --server platform_api_endpoint_url --fields title,realm
```
For example,
```
apic identity-providers:list --scope provider --server platform_api_endpoint_url --fields title,realm 
total_results: 2
results:
  - title: API Manager User Registry
    realm: provider/default-idp-2
  - title: Corporate LDAP user registry
    realm: provider/corporate-ldap
```
The title value should enable you to determine which identity provider to use; you can then copy the corresponding --realm parameter directly from the displayed realm value. For any identity providers that were created by your administrator after API Connect was installed, the names will have been determined at creation time. The default API Manager Local User Registry for login as a member of a provider organization is default-idp-2.
For full details of the apic login command, see Logging in to a management server.
Retrieve information about your Developer Portal users by using the user:information command. Due to the large number of users that might exist in your Developer Portal site, this command includes a default pagination limit of 50 users, with an offset of 0, but these defaults can be changed by using the optional flags. You can also use the optional flags to filter what user information is returned.
```
apic --mode portaladmin user:information --server management_server --org orgid/name --catalog catalogid/name
```
Where:
- management_server is the endpoint URL of the management server (required).
- orgid/name is the ID or name of the provider organization that the catalog belongs to (required).
- catalogid/name is the ID or name of the catalog that the site belongs to (required).
For example:
```
apic --mode portaladmin user:information --server my.management.server.com --org ibm --catalog portal-test
total: 2
offset: 0
limit: 2
users:
  - uid: '9'
    name: 'portal1'
    mail: 'corg-email+1@ibm.com'
    roles:
      - 'authenticated'
    status: 'active'
    apic_state: 'enabled'
    last_login: '01/11/2024 12:25:40'
    user_registry: '/consumer-api/user-registries/349aa966-a081-4f10-a104-084c353bd08e (portal-ci Catalog 1 Catalog User Registry)'
    consumer_orgs:
      - '/consumer-api/orgs/d22714f4-89e0-48a2-b5a3-94e7f1043eaf (portal-ci Grant - Stokes - Practical Rustic Metal Chair Consumer Organization)'
      - '/consumer-api/orgs/b6251379-5b43-433f-a64e-c93cdae6e085 (portal-ci Krajcik, Jacobson and Kihn - Tasty Sleek Metal Mouse Consumer Organization)'
  - uid: '10'
    name: 'portal2'
    mail: 'corg-email+2@ibm.com'
    roles:
      - 'authenticated'
    status: 'active'
    apic_state: 'enabled'
    last_login: '01/01/1970 00:00:00'
    user_registry: '/consumer-api/user-registries/349aa966-a081-4f10-a104-084c353bd08e (portal-ci Catalog 1 Catalog User Registry)'
    consumer_orgs:
      - '/consumer-api/orgs/d22714f4-89e0-48a2-b5a3-94e7f1043eaf (portal-ci Grant - Stokes - Practical Rustic Metal Chair Consumer Organization)'
      - '/consumer-api/orgs/b6251379-5b43-433f-a64e-c93cdae6e085 (portal-ci Krajcik, Jacobson and Kihn - Tasty Sleek Metal Mouse Consumer Organization)'
```
The following user information is returned by default:
- uid- The unique Drupal ID that identifies the user entity.
- name - The name of the user.
- mail - The email address of the user.
- roles - The current active Drupal user roles that the user has assigned to them.
- status - The Drupal status of the user. Valid values are active or blocked.
- apic_state - The current status of the user account. Valid values are:
  - enabled - The account is activated.
  - pending - The account is created, but not activated.
  - pending_approval - The account is created, but is waiting for approval before it can be activated.
- last_login - The last time the user logged into the Developer Portal UI. If the user hasn't logged into the UI since creating their account, the time defaults to 01/01/1970 00:00:00, which is the start of UNIX time.
- user_registry - The user registry that the account is in. The entry contains both its unique identifier, and its human readable name.
- consumer_orgs - A list of the consumer organizations that the user is in. The list contains both the unique identifier, and the human readable name, of the organizations.
You can use the following optional command flags to filter what user information is returned, and control the pagination:
- --apic-state - A comma-separated list of the user account states (string).
- --consumer-org - A comma-separated list of consumer organization URLs (string). The users that are returned can be in one or more of the organizations listed, and you can find the consumer organization URLs by using the consumer-org:list command.
- --format - The output format of the return (string). Valid values are json, yaml, octet-stream, go-template=template_name, or go-template-file=file_name. Defaults to yaml.
- --limit - Limit the number of user results returned (int32). Default is 50 user results.
- --login-after - Filter the return to those users who last logged in after the provided date (string). The date must be in the format of MM-DD-YYY or MM-DD-YY HH:MM:SS.
- --login-before - Filter the return to those users who last logged in before the provided date (string). The date must be in the format of MM-DD-YYY or MM-DD-YY HH:MM:SS.
- --mail - A comma-separated list of user email addresses (string).
- --names - A comma-separated list of user names (string).
- --offset - Offset the user results that are returned (int32). For example, if there are 100 users in your Developer Portal site, and you want to return the user information for users 51 to 100, you can set the --offset option to 50.
- --role - A comma-separated list of Drupal user roles (string).
- --status - The Drupal status of the user. Valid values are 'active' or 'blocked'.
- --uid - A comma-separated list of unique Drupal user IDs.
Add one or more roles to one or more specified user accounts. You must provide one or more of the email address, user name, or unique Drupal ID of the user accounts that you want to update.
```
apic --mode portaladmin user:add-role --server management_server --org orgid/name --catalog catalogid/name --role role_name --names user_names
```
Where:
- role_name is a comma-separated list of the name of the Drupal user roles that you want to add (required). Note that the role must already exist in the Developer Portal.
- --names is a comma-separated list of user names.
- --mail is a comma-separated list of user email addresses.
- --uid is comma-separated list of unique Drupal IDs of users.
For example:
```
apic --mode portaladmin user:add-role --server my.management.server.com --org ibm --catalog portal-test --role administrator --names portal1
[success] Added administrator role to portal1
```
Remove one or more roles from one or more specified user accounts. You must provide one or more of the email address, user name, or unique Drupal ID of the user accounts that you want to update.
```
apic --mode portaladmin user:remove-role --server management_server --org orgid/name --catalog catalogid/name --role role_name --names user_names
```
Where:
- role_name is a comma-separated list of the name of the Drupal user roles that you want to remove (required).
- --names is a comma-separated list of user names.
- --mail is a comma-separated list of user email addresses.
- --uid is comma-separated list of unique Drupal IDs of users.
For example:
```
apic --mode portaladmin user:remove-role --server my.management.server.com --org ibm --catalog portal-test --role administrator --names portal1
[success] Removed administrator role from portal1
```
Block one or more Developer Portal users. You must provide the names of the users that you want to block.
```
apic --mode portaladmin user:block --server management_server --org orgid/name --catalog catalogid/name --names user_names
```
Where:
- --names is a comma-separated list of user names.
For example:
```
apic --mode portaladmin user:block --server my.management.server.com --org ibm --catalog portal-test --names portal1
[success] Blocked user(s): portal1
```
When a blocked user tries to log in to their Developer Portal account, an error message is displayed indicating that they are unable to sign in.

Unblock one or more Developer Portal users. You must provide the names of the users that you want to unblock.

apic --mode portaladmin user:unblock --server management_server --org orgid/name --catalog catalogid/name --names user_names

Where:

--names is a comma-separated list of user names.

For example:

apic --mode portaladmin user:unblock --server my.management.server.com --org ibm --catalog portal-test --names portal1
[success] Unblocked user(s): portal1