feat: add support for nested attribute profile mapping

[devtekve]

Summary

This MR introduces support for nested properties in the OAuth connector for Logto, allowing users to map and retrieve nested attributes from social vendor profiles. This enhancement builds upon the existing functionality, enabling more flexible and comprehensive user profile mappings.

Key Changes:

• Updated the userProfileMapping function to handle nested properties.
• Modified the ProfileMap type to support nested attribute paths.
• Added unit tests to verify the correct mapping of nested properties.
• Updated the README to include documentation and examples for nested attribute mappings.

Why?

Imagine the social vendor user info returns something like

{
  "id": "123456",
  "contact": {
    "email": "octcat@github.com",
    "phone": "123-456-7890"
  },
  "details": {
    "name": "Oct Cat",
    "avatar": {
      "url": "avatar.png"
    }
  }
}

now we can map it without the need of creating a new connector like this

{
  "id": "id",
  "name": "details.name",
  "avatar": "details.avatar.url",
  "email": "contact.email",
  "phone": "contact.phone"
}

for the final result of

{
  "id": "123456",
  "name": "Oct Cat",
  "avatar": "avatar.png",
  "email": "octcat@github.com",
  "phone": "123-456-7890"
}

Testing

• Created unit tests to ensure the connector correctly handles nested attributes from social vendor profiles.
• Ran existing unit tests to validate that the existing behavior remains as expected.
• Manually tested the connector by authenticating with a real social vendor account, verifying that nested user
  details are retrieved correctly.

For my testing I connected with Patreon with the following config

• Authorization Endpoint: https://www.patreon.com/oauth2/authorize
• Token Endpoint: https://www.patreon.com/api/oauth2/token
• User Info Endpoint: https://www.patreon.com/api/oauth2/api/current_user
• Token Endpoint Auth Method: client_secret_basic
• Token Endpoint Response Type: json
• Scope: identity identity[email]
  And finally, the Profile Map:

{
  "id": "data.id",
  "name": "data.attributes.full_name",
  "email": "data.attributes.email",
  "avatar": "data.attributes.image_url"
}

Checklist

• .changeset - Added a changeset file to record the new feature introduction.
• unit tests - Developed unit tests for nested property mapping.
• necessary TSDoc comments - Added TSDoc comments to the new methods and classes introduced for documentation.
• integration tests - Ran integration tests to ensure proper interaction with nested attributes.

Footnote

This resolves #5580

[github-actions]

COMPARE TO master

Total Size Diff 📈 +1.8 KB

Diff by File

Name	Diff
.changeset/violet-beds-yawn.md	📈 +78 Bytes
packages/connectors/connector-oauth2/README.md	📈 +448 Bytes
packages/connectors/connector-oauth2/src/utils.test.ts	📈 +1.39 KB
packages/connectors/connector-oauth2/src/utils.ts	📈 +102 Bytes

[darcyYe]

LGTM, thanks for your contribution

[devtekve]

Changes made, we are now using the essentials and things work as expected. I did have to tweak the last test because now it throws an error if the key is not found rather than silently make it "undefined". (I prefer the error now that i think of it, so it's much better)

[darcyYe]

Hi @devtekve , I made changes and pushed a commit to your MR. If we use get() method in the code, with the existing profile mapping setup, values that can not be found by profile mapping setup could lead to errors, which is a breaking change. Hence I changed the get() method to getSafe() method to silently mark the unfound value as undefined.

[devtekve]

Hi @devtekve , I made changes and pushed a commit to your MR. If we use get() method in the code, with the existing profile mapping setup, values that can not be found by profile mapping setup could lead to errors, which is a breaking change. Hence I changed the get() method to getSafe() method to silently mark the unfound value as undefined.

Makes total sense!. I was under the wrong impression it used to fail as well if the key was not found before the nested attributes. But if that wasn't the case then yeah, good catch!