Update SCIM FAQ on user provisioning errors (#13378)

content/docs/pulumi-cloud/access-management/scim/faq.md

@@ -24,33 +24,107 @@ This page contains information on how to resolve issues that may occur when conf
 
 ### A failure occurred when attempting to provision a user.
 
-This failure occurred because there is a conflict with an existing user account in the Pulumi Cloud application. When this occurs our service returns a 409 HTTP response code, indicating a conflict, which you should be able to see in your identity provider's (e.g. Okta, Azure AD) console logs. This means that there is a conflict with an existing account that already contains either that user's username or email. These attributes must be unique for each user in our system which is why the provisioning failed. The steps below describe the process needed to resolve the conflict.
+These errors can occur when attempting to create (POST), replace (PUT), or update (PATCH) a user. If you encounter difficulties resolving these issues, please contact our [customer support](https://support.pulumi.com/) for assistance.
+
+#### Email already in use
+
+```json
+{
+    "status": 409,
+    "response": {
+        "schemas": ["urn:ietf:params:scim:api:messages:2.0:Error"],
+        "status": 409,
+        "scimType": "uniqueness",
+        "detail": "Email {email} already in use by another Pulumi account."
+    }
+}
+```
 
-**Resolving an email conflict** - This occurs when the user being provisioned has already created a Pulumi account with the same email address. The conflict must be resolved by changing the email associated with their Pulumi account and releasing it from our system or connecting the existing account to the new account being provisioned. If you encounter this issue, please contact our [customer support](https://support.pulumi.com/) for assistance.
+Cause: The user being provisioned has already created a Pulumi account with the same email address. The email needs to be released from our system before it can be used to provision a new user, or the existing account needs to be connected to the new account being provisioned.
 
-**Resolving a username conflict** - This occurs when the user being provisioned has the same username as an existing account in the Pulumi Cloud. This does not guarantee that the usernames in conflict both belong to the same individual since a username is not something guaranteed to be unique across multiple applications. Therefore connecting to the existing account is not an option in this case since we do not know for sure they are owned by the same individual. The suggested way to resolve this conflict would be to update the username attribute in your identity provider’s console if your identity provider allows. _This action must be done by an admin on the identity provider side (e.g. Okta)_.
+Suggested Resolution: There are three possible solutions. The user can either:
 
-1. Navigate to the user's profile settings in your identity provider's console.
-2. Next change the username attribute to a different value.
-3. Retry provisioning that user. This should now succeed if the username is now unique in the Pulumi Cloud.
+1. Delete their existing Pulumi account
+1. Change the email associated with their existing Pulumi account
+1. Connect their SAML credentials to their existing Pulumi account by navigating to Account Settings > Connect SAML SSO.
 
-If your identity provider doesn't allow you to control the username attribute's value, please contact our [customer support](https://support.pulumi.com/) for assistance.
+#### UserName already exists
 
-### Can I manage Pulumi-local teams if using SCIM?
+```json
+{
+    "status": 409,
+    "response": {
+        "schemas": ["urn:ietf:params:scim:api:messages:2.0:Error"],
+        "status": 409,
+        "scimType": "uniqueness",
+        "detail": "User with userName {userName} already exists."
+    }
+}
+```
 
-Yes. In addition to the SCIM-managed teams, one can also configure and manage Pulumi-local teams in the Pulumi Cloud. See [Teams](/docs/pulumi-cloud/access-management/teams/) for how to configure teams in the Pulumi Cloud.
+Cause: The user being provisioned has the same username as an existing account in the Pulumi Cloud.
+
+Suggested Resolution: Update the username attribute in your identity provider’s console if your identity provider allows, then try reprovisioning the user. _This action must be done by an admin on the identity provider side (e.g. Okta)_.
+
+#### UserName is immutable
+
+```json
+{
+    "status": 400,
+    "response": {
+        "schemas": ["urn:ietf:params:scim:api:messages:2.0:Error"],
+        "status": 400,
+        "scimType": "immutability",
+        "detail": "Attribute 'userName' is immutable."
+    }
+}
+```
+
+Cause: Pulumi usernames are immutable and cannot be updated.
+
+Suggested Resolution: Update the attribute mapping in the identity provider so that `userName` is updated only during creation, not creation and update. _This action must be done by an admin on the identity provider side (e.g. Okta)_.
+
+#### Unknown path
+
+```json
+{
+    "status": 400,
+    "response": {
+        "schemas": ["urn:ietf:params:scim:api:messages:2.0:Error"],
+        "status": 400,
+        "scimType": "invalidPath",
+        "detail": "Unknown path: {path}."
+    }
+}
+```
+
+Cause: Pulumi only supports adding or updating the following user attributes:
+
+- `userName`
+- `displayName`
+- `givenName`
+- `familyName`
+- `active`
+
+Provisioning jobs that try to add or update any other attribute will fail.
+
+Suggested Resolution: Update the attribute mappings in the identity provider and delete all unsupported attributes. _This action must be done by an admin on the identity provider side (e.g. Okta)_.
 
 ### A failure occurred when attempting to provision group members.
 
 The creation (POST), update (PATCH) or replacement (PUT) of a group performs member validation prior running the operation. If any of the members provided are not provisioned into your Pulumi organization or is not active, the request will fail with the following response:
 
 ```
 Status: 400 BAD REQUEST
-Bad Request: invalid member ids: [comma separated list of invalid member ids]
+Bad Request: Cannot add invalid members to team. Invalid member ids: [comma separated list of invalid member ids]
 ```
 
 The suggested way to resolve this conflict would be to synchronize all the group members to guarantee every member is successfully provisioned and update the user's status. _This action must be done by an admin on the identity provider side (e.g. Okta)_.
 
+### Can I manage Pulumi-local teams if using SCIM?
+
+Yes. In addition to the SCIM-managed teams, one can also configure and manage Pulumi-local teams in the Pulumi Cloud. See [Teams](/docs/pulumi-cloud/access-management/teams/) for how to configure teams in the Pulumi Cloud.
+
 ## More FAQ
 
 - [Pulumi IaC FAQ](/docs/iac/support/faq/)