Remove User Attribute Process

Content

• Overview
• About AuthN IDs
• AuthN IDs are User Entity Attributes
• Process Flow
• App Settings
• Remove Attribute (Email/Mobile) User Journey
• API Walkthroughs
• Error Codes
• Revision History

Overview

This process defines how the user removes an existing attribute (e.g., email, mobile, alias) from their User ID.

About AuthN IDs

Here are a few basic things to remember about how authentication identifiers (authN IDs) work in ULM:

• AuthN IDs are commonly referred to as usernames. AuthN IDs include emails and mobile numbers.
• When a user registers an authN ID to their User ID, it is stored on the ULM User entity in ULM Cloud.
• Every ULM User ID requires at least one verified authN ID for the User ID to be activated.
• ULM supports the ability for a user to register, verify, and use multiple authN IDs for their User ID.
• ULM also supports the ability for users to add non-verifiable aliases to their User ID as authN IDs.
• AuthN IDs are stored on the ULM User entity as attributes. Specifically, each authN ID type is grouped under the attributes array. See the next section for a visual aid.

AuthN IDs are User Entity Attributes

ULM CLoud is built on top of a user-centric and entitlement-specific data model comprised of ULM data entities. Each entity type is defined by a set of default and extensible attributes. Some attributes are simple name/value pairs, and others are more complex arrays (i.e., an array objects that make up a single attribute value).

A user's authN IDs are stored as attributes on the ULM User entity, under the attributes array.

The Remove User Attribute Process removes a single email, mobile number, or alias from the User entity.

Process Flow

This table describes the Process functionality at a high level.

App Settings

This Process currently has no relevant app settings to configure the Process behaviour.

Remove Attribute (Email/Mobile) User Journey

This flow diagram illustrates a standard Remove Email user journey using the Remove Attribute Process.

API Walkthroughs

This section provides guided walkthroughs of the Add/Update Email, Mobile, or Alias Process process, including demonstrations of the various branching paths the Process can take during its execution.

Remove Email Address/Mobile Number Scenario

A user removes an e-mail address that was previously added as an authN ID to their User ID.

Initial Request

The Process Start API initializes the Process:

<no body>

Response: Prompt to Specify the Attribute (AuthN ID)

The API responds with a request to select which attribute to remove:

{
    "processId": "9d8a22f5-dee8-4661-95a0-51ac272d819e",
    "processName": "userManagement.RemoveUserAttribute.v1.0",
    "displayMessage": "Please provide the user attribute to be removed.",
    "parameters": {
        "attributeValue": "String",
        "attributeProperty": "String",
        "attributeName": "String"
    },
    "stepName": "RemoveUserAttributePrompt",
    "lastStep": false
}

Response Parameters

Note: A list of the available attributes on the user can be obtained by querying the GET /user REST API. The following sample excerpt from the API displays the attribute in question:

attributes": [
    {
        "name": "emails",
        "value": [
                "status": "activated",
                "id": 2,
                "email": "ryan@example.com"
        ]
    }
]

Final Request: User Specifies the AuthN ID

In order to determine the correct e-mail address to remove, the attribute name ("emails") must be provided, as well as qualifiers to derive the specific e-mail address, as the user may have multiple e-mail addresses registered to their ULM ID. In this example, we are searching for the attribute value "ryan@example.com" in the attribute's property "email". The client passes that info to the Process with the Process Step API:

{
    "processId": "9d8a22f5-dee8-4661-95a0-51ac272d819e",
    "parameters": {
        "attributeValue": "ryan@example.com",
        "attributeProperty": "email",
        "attributeName": "emails"
    }
}

Request Parameters

Response: Success

If the target authN ID is valid, the Process completes its task and returns a 200 HTTP status code:

{
    "processId": "9d8a22f5-dee8-4661-95a0-51ac272d819e",
    "processName": "userManagement.RemoveUserAttribute.v1.0",
    "lastStep": true
}

The user can no longer use this authN ID for authentication purposes. It is removed entirely from the ULM Cloud data store.

Response Parameters

Error Scenario: Cannot Remove Selected AuthN ID

Email addresses and phone numbers cannot be removed in cases where their removal would result in the user not having any remaining verified authN IDs. In these scenarios, the user must add and verify a second authentication identifier. Even if the user onboarded with their social account, that Process still involves the creation and verification of an authN ID attribute on the ULM User entity (i.e., either the user confirms the email/mobile returned by the social provider, or they change the email/mobile value and then verify it before they can complete their onboarding).

If the user does attempt to remove their only verified authN ID, the process returns the below error:

{
    "processId": "9d8a22f5-dee8-4661-95a0-51ac272d819e",
    "stepName": "RemoveUserAttributePrompt",
    "lastStep": false,
    "processName": "userManagement.RemoveUserAttribute.v1.0",
    "operationError": [
        {
            "code": "last-auth-identifier",
            "type": "com.uxpsystems.mint.framework.ulm.process.service.ServiceStep.GeneralFailure",
            "message": "The only authentication identifier cannot be removed",
            "authorities": [
                {
                    "authority": "ROLE_USER"
                }
            ]
        }
    ]
}

Error Scenario: Specified AuthN ID Does Not Exist

If the user/client UI attempts to specify an attribute that does not exist on the User entity, the process returns the below error:

{
    "processId": "9d8a22f5-dee8-4661-95a0-51ac272d819e",
    "stepName": "RemoveUserAttributePrompt",
    "lastStep": false,
    "processName": "userManagement.RemoveUserAttribute.v1.0",
    "operationError": [
        {
            "code": "invalid-attribute-value",
            "type": "com.uxpsystems.mint.framework.ulm.process.service.ServiceStep.GeneralFailure",
            "message": "Provided attribute value not found",
            "authorities": [
                {
                    "authority": "ROLE_USER"
                }
            ]
        }
    ]
}

Error Scenario: Cannot Remove User's Primacy Contact Channel

The user cannot remove an authN ID if it is currently their primary contact channel (for notifications). If the user attempts this, the Process responds with the following error:

{
    "processId": "9d8a22f5-dee8-4661-95a0-51ac272d819e",
    "lastStep": false,
    "processName": "userManagement.RemoveUserAttribute.v1.0",
    "operationError": [
        {
            "code": "attribute-attached-notification-channel",
            "type": "com.uxpsystems.mint.framework.ulm.process.service.ServiceStep.GeneralFailure",
            "message": "Provided attribute is used as preferred notification channel",
            "authorities": [
                {
                    "authority": "ROLE_USER"
                }
            ]
        }
    ],
    "stepName": "RemoveUserAttributePrompt"
}

The user must set a new primary contact channel before executing this Process.

Error Codes

Below is a comprehensive list of potential error codes that may be returned during the execution of this Process.

Common Error Codes

Common Process Error Codes

Process-Specific Error Codes

Revision History