Managing users

Exporting all users

Before you can import your profiles to your new instance, you need to export them from your original instance of the service.

If you are exporting many users (16,000 or more), you can use the export/all API endpoint.

1. Export all the users from your original instance of the service.

   curl -X POST 'https://<region>.appid.cloud.ibm.com/management/v4/<tenantID>/cloud_directory/export/all' \
      --header 'Content-Type: application/json' \
      --header 'Authorization: Bearer <IAMToken>' \
      --data-raw '{"encryptionSecret" : "<encryptionSecret>",  
   "emailAddress" : "jdoe@example.com"}'
   

2. Get the status of your request, as needed.

   curl -X GET 'https://<region>.appid.cloud.ibm.com/management/v4/<tenantID>/cloud_directory/export/status?id=<id>' --header 'Accept: application/json' \
      --header 'Content-Type: application/json' \
      --header 'Authorization: Bearer <IAMToken>'
   

3. When the export is ready or if the request fails, an email is sent to the email address provided. To download the export, use the export/download API.

   curl -X GET 'https://<region>.appid.cloud.ibm.com/management/v4/<tenantID>/cloud_directory/export/download?id=<id>' \
      --header 'Content-Type: application/json' \
      --header 'Authorization: Bearer <IAMToken>'
   

   An export file is created only when the export request is successful. If the request fails, to reduce your vulnerability risk, the data that is gathered is deleted. The export is automatically deleted after 7 days or the number of days that you specify in the body of the request (in the range of 1 - 30 days). You can choose to manually delete the export by sending a request to the delete API.

   Table 3. Descriptions of the parameters that need to be provided in the export/all request

   Parameters	Description
   encryptionSecret	A custom string that is used to encrypt and decrypt a user's hashed password. Retain the encryption secret as you need it to use the import/all API. IBM does not store the secret so if the secret is lost, you can't access the exported data.
   emailAddress	An email address to which an email is sent when the export is ready or if the request fails.
   expires	An integer that you can set (1 ≤ value ≤ 30) to specify the number of days after which the export must be deleted. The default value is 7.
   tenantID	The service tenant ID can be found in your service credentials. You can find or create your service credentials in the App ID dashboard.

Exporting users in smaller batches

The export endpoint is reserved for smaller exports of approximately less than 16,000 users. To export all your Cloud Directory users who are associated with a specific tenant ID, use the export/all API endpoint.

1. Export the users from your original instance of the service.

   curl -X GET 'https://<region>.appid.cloud.ibm.com/management/v4/<tenantID>/cloud_directory/export?encryption_secret=mySecret' \
   -H 'Accept: application/json' \
   -H 'Authorization: Bearer <IAMToken>'
   

   Table 2. Descriptions of the parameters that need to be provided in the export request

   Parameters	Description
   encryptionSecret	A custom string that is used to encrypt and decrypt a user's hashed password.
   tenantID	The service tenant ID can be found in your service credentials. You can find your service credentials in the App ID dashboard.

   Only your Cloud Directory users and their profiles are returned. Users from other identity providers are not.

Importing all users

Now that you have a list of exported Cloud Directory users, you can import them into the new instance. You can use the import-all API endpoint to import a large number of users (16,000 or more) with a single request.

1. Import the list of exported users that you downloaded.

   curl -X POST 'https://<region>.appid.cloud.ibm.com/management/v4/<tenantID>/cloud_directory/import/all' \
   --header 'Content-Type: multipart/form-data' \
   --header 'Authorization: Bearer <IAMToken>' \
   --form 'file=@<User/desktop/myfolder/user_list.json>' \
   --form 'encryptionSecret=mySecret' \
   --form 'emailAddress=jdoe@example.com'
   

2. Get the status of your request, as needed.

   curl -X GET 'https://<region>.appid.cloud.ibm.com/management/v4/<tenantID>/cloud_directory/import/status?id=<id>' \
   --header 'Accept: application/json' \
   --header 'Content-Type: application/json' \
   --header 'Authorization: Bearer <IAMToken>'
   

   Table 4. Descriptions of the parameters that need to be provided in the import/all request

   Parameters	Description
   encryptionSecret	A custom string that is used to encrypt and decrypt a user's hashed password. The encryption secret is the same secret that you attached to the export/all API. IBM does not store the secret so if the secret is lost, you can't access the exported data.
   emailAddress	An email address to which an email is sent when the export is ready or if the request fails.
   tenantID	The service tenant ID can be found in your service credentials. You can find or create your service credentials in the App ID dashboard.
   file	The output from the export/download endpoint.

Importing users in smaller batches

You can use the import API endpoint to import small groups of users. You can add up to only 50 users per request with the import API endpoint. To add all your users through a single request, use the import/all API endpoint.

1. If your users are assigned roles, be sure to create the roles and scopes in your new instance of App ID.

   The roles and scopes must be created exactly as they were in the previous instance with the same spellings.

2. Users are imported with a new Cloud Directory identifier. If your app references the Cloud Directory identifier in any way, you can choose to create a custom attribute and adjust your application to call the attribute instead of the identifier directly.

3. Import the users to your new instance of the service.

   curl -X POST 'https://<region>.appid.cloud.ibm.com/management/v4/<tenantID>/cloud_directory/import?encryption_secret=mySecret'
   --header 'Content-Type: application/json' 
   --header 'Accept: application/json' 
   --header 'Authorization: Bearer <IAMToken>' 
   -d '{"users": [
      {
         "scimUser": {
            "originalId": "3f3f6779-7978-4383-926f-a43aef3b724b",
            "name": {
            "givenName": "John",
            "familyName": "Doe",
            "formatted": "John Doe"
            },
            "displayName": "John Doe",
            "emails": [
            {
               "value": "user@example.com",
               "primary": true
            }
            ],
            "status": "PENDING"
         },
         "displayName": "Jane-Doe",
         "emails": [
            {
            "value": "jdoe@example.com",
            "primary": true
            }
         ],
         "status": "PENDING"
      },
      "passwordHash": "<passwordHashHere>",
      "passwordHashAlg": <passwordHashAlgorithm>,
      "profile": {
         "attributes": {}
      },
      "roles": []
      }
   ]}' 
   

Migration script for smaller exports and imports

App ID provides a migration script that you can use through the CLI that can help speed up the migration process when you use the export or import API endpoints. Alternatively, to make the migration process even more efficient, you can use the export/all and import/all API endpoints.

1. Clone the repository.

git clone https://github.com/ibm-cloud-security/appid-sample-code-snippets/tree/master/export-import-cloud-directory-users.git

2. In terminal, change to the folder that you cloned the repo into.

3. Run the following command.

   npm install
   

4. With your parameters, run the following command.

   users_export_import 'sourceTenantId' 'destinationTenantId' 'region' 'iamToken'
   

   Table 3. Parameter descriptions

   Parameter	Description
   sourceTenantId	The tenant ID of the instance of App ID that you plan to export users from.
   destinationTenantId	The tenant ID of the instance of App ID that you plan to import users to.
   region	Learn more about the available regions.
   IAM token	For help with obtaining an IAM token, check out the docs.

   Example command:

   users_export_import e00a0366-53c5-4fcf-8fef-ab3e66b2ced8 73321c2b-d35a-497a-9845-15c580fdf58c ng eyJraWQiOiIyMDE3MTAyNS0xNjoyNzoxMCIsImFsZyI6IlJTMjU2In0.eyJpYW1faWQiOiJJQk1pZC0zMTAwMDBUNkZTIiwiaWQiOiJJQk1pZC0zMTAwMDBUNkZTIiwicmVhbG1pZCI6IklCTWlkIiwiaWRlbnRpZmllciI6IjMxMDAwIFQ2RlMiPCJnaXZlbl9uYW1lIjoiUm90ZW0iLCJmYW1pbHlfbmFtZSI6IkJyb3NoIiwibmFtZSI6IlJvdGVtIEJyb3NoIiwiZW1haWwiOiJyb3RlbWJyQGlsLmlibS5jb20iLCJzdWIiOiJyb3RlbWJyQGlsLmlibS5jb20iLCJhY2NvdW50Ijp7ImJzcyI6ImQ3OWM5YTk5NjJkYzc2Y2JkMDZlYTVhNzhjMjY0YzE5In0sImlhdCI6MTUzNrE3Mjg4NCwiZXhwIjoxNTM3MTc2NDg0LCJpc3MiOiJodHRwczovL2lhbS5zdGFnZTEuYmx1ZW1peC5uZXQvaWRlbnRpdHkiLCJncmFudF90eXBlIjoidXJuOmlibTpwYXJhbXM6b2F1dGg6Z3JhbnQtdHlwZTpwYXNzY29kZSIsInNjb3BlIjoiaWJtIG9wZW5pZCIsImNsaWVudF9pZCI6ImJ4IiwiYWNyIjoxLCJhbXIiOlsicHdkIl19.c4vLPzhvvNZLjaLy7znDa37qV4o-yuGmSKmJoQKrEQNZU8IC0NIjxwSo7W9kb0pDi3Yf_03_9ufTTGNfjtltzNWycSXjkNgoL-b9_nU61oHdgn0stY1KmNicqyBWfgUU--4xa904QN_QjRHBaUBeJf3XWEphPIMoF7mZeOxEZLnCMcQXSz9pImCMiP4SNT38cHLiI90Yx01rM7hpteepWULh5MYh-B2V03Gkgxfqvv951HF1LDg6eT4Q9in11laTQKtKuomripUju_4GIIjORVYw9NaAVKIJ9lKrPX0SKPhStsa59qGsC_7Uersms5EY1W1VbZVqOZPJbtp6tVf-Lw