Managing profiles

With IBM Cloud® App ID, you can compile information about the individual users of your application into a profile. The information in the profile can be learned about your users by the way that they interact with your app or added by you on their behalf. By storing the information, you can access it to help create personalized experiences of your app for your users.

Looking for information about your Cloud Directory users? Check out managing users.

Viewing user profiles with the UI

To see the data that is available for your app users, you can use the App ID UI.

Navigate to the User Profiles > Profiles tab of your App ID instance.
Look through the table or search by using an email address to find the user that you want to see the information for. The search term must be exact.

In the overflow menu of the user's row, click View user profile. A page opens that contains the user's information. Check out the following table to see what information you can see.

Table 1. User details as shown in the App ID dashboard
Detail	Description
IdP identifier	The IdP identifier is issued by the provider that your user chose to sign in to your application with.
Email	The primary email address that is attached to the user.
Name	Your user's first and surname as issued by the identity provider.
Identity provider	The provider that your user chose to sign in with.
ID	The ID that is assigned to the user by App ID.
Custom attributes	Custom attributes are additional information that is added to their profile or that is learned about the user's as they interact with your application.
Summary	All the information that is associated with that user shown as a JSON object.

Viewing user profiles with the API

You can use the App ID API to view details about your app users.

Obtain your tenant ID from your instance of the service. You can find the ID in your service or application credentials.

Search your App ID users with an identifying query, such as an email address, to find the user ID.

curl -X GET "https://<region>.appid.cloud.ibm.com/management/v4/<tenantID>/Users?query=<identifyingSearchQuery>" \
-H "accept: application/json" \
-H "authorization: Bearer <token>"

Example:

curl -X GET https://us-south.appid.cloud.ibm.com/management/v4/e19a2778-3262-4986-8875-8khjafsdkhjsdafkjh/cloud_directory/Users?query=example@domain.com -H "accept: application/json" -H "authorization: Bearer eyJraWQiOiIyMDE3MTEyOSIsImFsZ...."

By using the ID that you obtained in the previous step, make a GET request to the /users endpoint to see their full user profile.

curl -X GET "https://<region>.appid.cloud.ibm.com/management/v4/<tenantID>/users/<userID>/profile" \
-H "accept: application/json" \
-H "authorization: Bearer <token>"

Example response:

{
   "id": "a0791903-ed4c-41cf-bd0e-a37957dad820",
   "name": "David Test-user",
   "email": "dave.test@domain.com",
   "picture": "https://platform-lookaside.fbsbx.com/platform/profilepic/?asid=11122233344455566&height=50&width=50&ext=1569429199&hash=AaAaAAAAAaAAAaaA",
   "identities": [
      {
      "provider": "facebook",
      "id": "11122233344455566",
      "idpUserInfo": {
            "id": "11122233344455566",
            "name": "David Test-user",
            "picture": {
            "data": {
               "height": 50,
               "is_silhouette": false,
               "url": "https://platform-lookaside.fbsbx.com/platform/profilepic/?asid=11122233344455566&height=50&width=50&ext=1569429199&hash=AaAaAAAAAaAAAaaA",
               "width": 50
            }
            },
            "first_name": "David",
            "last_name": "Test-user",
            "email": "dave.test@domain.com",
            "idpType": "facebook"
      }
      }
   ],
   "attributes": {
      "role": "admin"
   }
}

To see the full user data set that App ID supports, check out the SCIM core schema.

Setting custom attributes with the UI

You can add custom information about your users to their profile such a role that they hold or preference that they have by setting a custom attribute. To set an attribute, you can use the App ID UI.

By default, custom attributes are modifiable and can be updated by using an App ID access token from a client application. Without taking proper precautions, either the user or the application can update custom attributes immediately following the first user sign-in, if they have an access token. This can potentially lead to unintended consequences. For example, a user might change their role from user to admin, which might expose administrative privileges to malicious users.

Go to the User profiles > Settings tab of the App ID dashboard.
Toggle custom attributes to Enabled.
Click View profile in the overflow menu of the row for the user that you want set the attribute for.
In the Custom attributes section, click Edit.
Enter the attributes that you want to add as a JSON object. For example, {"role":"admin"}.

Setting custom attributes with the API

As an administrator, you can add custom information about your users to their profile such a role that they hold or preference that they have by setting a custom attribute. To set an attribute, you can use the App ID API to call the /users endpoint. To set custom attributes before a user signs in to your application for the first time, see preregistering future users.

By default, custom attributes are modifiable and can be updated by using an App ID access token from a client application. This means that without taking proper precautions either the user or the application can update custom attributes immediately following the first user sign-in, if they have an access token. This can potentially lead to unintended consequences. For example, a user might change their role from user to admin, which might expose administrative privileges to malicious users.

Go to the User profiles > Settings tab of the App ID dashboard.
Toggle custom attributes to Enabled.
Obtain an IAM token.
1. In the IBM Cloud dashboard, click Manage > Access (IAM).
2. Select IBM Cloud API keys.
3. Click Create an IBM Cloud API key.
4. Give your key a name and describe it. Click Create. A screen displays with your key.
5. Click Copy or Download your key. When you close the screen, you can no longer access the key.
6. Make the following cURL request with the API key that you created.
```
curl -k -X POST \
--header "Content-Type: application/x-www-form-urlencoded" \
--header "Accept: application/json" \
--data-urlencode "grant_type=urn:ibm:params:oauth:grant-type:apikey" \
--data-urlencode "apikey=<apikey>" \
"https://iam.cloud.ibm.com/identity/token"
```

Make a PUT request to either the /users endpoint.

curl -X PUT "https://<region>.appid.cloud.ibm.com/management/v4/<tenantID>/users/<userID>/profile" \
-H "accept: application/json" \
-H "Content-Type: application/json" \
-H "authorization: Bearer <token>"
-d "{ \"attributes\": { \"points\": \"150\" } { \"role\": \"admin\" }}"

Deleting a profile with the UI

As an administrator, you can remove someone as a user of your application by deleting their profile.

Navigate to the User Profiles > Profiles tab of your App ID instance.
Look through the table or search by using an email address to find the user that you want to see the information for. The search term must be exact.
In the overflow menu of the user's row, click Delete. A confirmation screen opens.
Verify that you're deleting the correct user by checking their email against the one displayed. If it is the correct user, click Delete. This action cannot be undone. The user can be re-added but their profile shows that they are a new user as of the date that they're re-added.

Deleting a profile with the API

As an administrator, you can remove someone as a user of your application by deleting their profile.

Obtain your tenant ID from your instance of the service. You can find the ID in your service or application credentials.

Search your App ID users with an identifying query, such as an email address, to find the user ID.

curl -X GET "https://<region>.appid.cloud.ibm.com/management/v4/<tenantID>/Users?query=<identifyingSearchQuery>" \
-H "accept: application/json" \
-H "authorization: Bearer <token>"

Example:

curl -X GET https://us-south.appid.cloud.ibm.com/management/v4/e19a2778-3262-4986-8875-8khjafsdkhjsdafkjh/cloud_directory/Users?query=example@domain.com -H "accept: application/json" -H "authorization: Bearer eyJraWQiOiIyMDE3MTEyOSIsImFsZ...."

By using the ID that you obtained in the previous step, make a DELETE request to the /users endpoint to delete the profile.

curl -X DELETE "https://<region>.appid.cloud.ibm.com/management/v4/<tenantID>/users/<userID>/profile" \
-H "accept: application/json" \
-H "authorization: Bearer <token>"

Migrating user profiles

Occasionally, you might need to add an instance of App ID to your account to help ensure high availability or disaster recovery. Or, you might need to deprecate an instance of the service all together. To migrate the user information, you can export the user profiles from one instance of App ID and import them into another.

This action can be done through the API only. To see the steps, switch to the API instructions.

Exporting user profiles

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

Be sure that you are assigned the Manager IAM role for both the instance of App ID.

Export the profiles from your original instance of the service.

curl -X GET https://us-south.appid.cloud.ibm.com/management/v4/<tenantID>/users/export \
--header "Accept: application/json" \
--header "Authorization: Bearer <IAMToken>"

User import command variables
Variable	Description
`tenantID`	The service tenant ID can be found in your service credentials. You can find your service or application credentials in the App ID dashboard.
`iam-token`	Your IAM token.

Example response:

{
   "itemsPerPage": 2,
   "totalResults": 2,
   "requestOptions": {},
   "users": [
   {
      "id": "7ae804f3-0ed3-45f0-bc6b-1c6af868e6d6",
      "name": "{{site.data.keyword.appid_short_notm}} Google User profile",
      "email": "your@mail.com",
      "identities": [
         {
         "provider": "google",
         "id": "105646725068605084546",
         "idpUserInfo": {
            "id": "105646725068605084546",
            "email": "your@mail.com",
            "picture": "profilePic.jpg"
         }
         }
      ],
      "attributes": {
         "points": 150
      },
      "roles": ["admin"]
   {
      "id": "1439d777-185d-4be1-8f4a-c4e8142b87ea",
      "name": "{{site.data.keyword.appid_short_notm}} Facebook User profile",
      "email": "mail@mail.com",
      "identities": [
         {
         "provider": "facebook",
         "id": "100195207128541",
         "picture": {
            "data": {
               "height": 50,
               "width": 50,
               "url": "https://url-to-idp-profile-picture.com"
            }
         },
         "first_name": "AppID",
         "last_name": "Development"
         }
      ],
      "attributes": {
         "points": 250
      },
      "roles": ["admin"]
   }
}

Importing user profiles

Now that you have a list of exported user profiles, you can import them into the new instance.

Be sure that you are assigned the Manager IAM role for both the instance of App ID.
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.

Import the users to your new instance of the service.

curl -X POST "https://<region>.appid.cloud.ibm.com/management/v4/<tenantID>/users/import" \
-H "accept: application/json" \
-H "Authorization: Bearer <bearerToken>" \
-H "Content-Type: application/json" \
-d "{ \"itemsPerPage\": 2, \"totalResults\": 2, \"requestOptions\": {}, \"users\": [ { \"id\": \"7ae804f3-0ed3-45f0-bc6b-1c6af868e6d6\", \"name\": \"{{site.data.keyword.appid_short_notm}} Google User profile\", \"email\": \"your@mail.com\", \"identities\": [ { \"provider\": \"google\", \"id\": \"105646725068605084546\", \"idpUserInfo\": { \"id\": \"{ID}\", \"email\": \"your@mail.com\", \"picture\": \"{profile.jpg}\" } } ], \"attributes\": { \"points\": 150 } { \"role\": admin } }, { \"id\": \"{userinfo}\", \"name\": \"{{site.data.keyword.appid_short_notm}} Facebook User profile\", \"email\": \"mail@mail.com\", \"identities\": [ { \"provider\": \"facebook\", \"id\": \"{id}\", \"picture\": { \"data\": { \"height\": 50, \"width\": 50, \"url\": \"https://{url}.com\" } }, \"first_name\": \"AppID\", \"last_name\": \"Development\" } ], \"attributes\": { \"points\": 250 } { \"role\": admin } } ]}"

When you import users to an instance of App ID, their Identity Provider identifier remains the same.