First thoughts on Smart Link module

Forge Forge Platform and Tools
, ,
1

I just took a quick look at the new Smart Link module and have some thoughts I’d like to share here (I’m not sure where else we can provide feedback).

The current module docs are very minimal, and the function signature of the link resolver function is not defined (apart from some code in the tutorial).

Here are some assumptions I make based on the tutorial. If they are correct, can they please be added to the module documentation:

The function is always called with a parameter in the following format. Are there other types of requests with different payloads?

export interface ResolveSmartLinkRequest {
    type: 'resolve';
    payload: {
        urls: string[];
    }
}

The function should return a ResolveSmartLinkResponse response in the following format, where entity does not refer to any but a type defined in the object list:

export interface ResolveSmartLinkResponse {
    entities: ResolveUrlEntityResult[];
}

export type Identifier = { id: string; } | { url : string} | { id: string, url: string};

export interface ResolveUrlEntityResult  {
    identifier: Identifier
    meta: {
        access: string,
        visibility: string
    };
    entity?: any;
}

Open questions:

  • What are the other Identifier types for? Are those to respond to other types of ResolveSmartLinkRequest payloads?
  • What are accepted values for meta? string seems to be too generic, I am pretty sure there is a smaller subset that the API expects.
1 Like
2

I just had one more question. The introduction paragraph in the docs says:

Importantly, Smart Links operate in the context of the authenticated user, so information is only visible to users who have the necessary permissions in the remote system.

From the example tutorial, I don’t see any limitations to the invoked function on how information is resolved. The implementation of the function appears to be entirely within the app’s control. Is this merely a requirement for implementors, or is there anything more to this? How does Atlassian guarantee that information is only visible to users who have the necessary permissions in the remote system?

1 Like
3

Hi @tbinna,

Thank you for raising this. Apologies for the documentation not being sufficient.

Firstly, your assumptions are spot on.

Our team just updated the documentation with Request and Response detail including example payloads. They have also changed the wording to more accurately reflect the joint responsibility between Atlassian and the App Developer to ensure end user permissions are respected.

What are the other Identifier types for? Are those to respond to other types of ResolveSmartLinkRequest payloads?

This was added for future potential retrieval of data where we have the object reference and not just the URL. Currently, only url will be utilised.

What are accepted values for meta? string seems to be too generic, I am pretty sure there is a smaller subset that the API expects.

The documentation has been updated to show the fields within the Meta object as well as their possible values.

Please let me know if you have any additional questions.

1 Like
4

Hey @EugeneSmal,

Thank you for the quick improvements to the documents and the clarification. Those all make sense to me now.

Smart Link requests are executed in the context of the user. Both Atlassian and the app developer share responsibility for respecting user permissions, ensuring that users can only access data they are authorized to view.

This is still a point of contention for me. The problem with this is that it is a very narrow view on how an integration with a remote system works. The statement above contains the implicit assumption that every Jira user has an account in the remote system, which is typically true for integrations with Google Workspace, Google Drive, Slack, or Dropbox.
However, this is typically not true for use cases where, for example, a first-level support team on a remote system hands off a case to second-level support on JSM. In such scenarios, Jira users would not have an account in the remote system, yet they still need to view information from it.

This is what we solve with our integrations, and it is achieved through system-to-system integration, where information is retrieved by an “app user” - an OAuth connection to the remote system, authorized by a user who represents the remote system. On other platforms, such as Google Cloud, these accounts are referred to as service accounts. They can have permissions assigned just like a normal user, but they represent an application, not a individual user.

We have been discussing the service account scenario, or OAuth asApp use case with Atlassian since 2021, when Forge providers first launched, and I think it is something that Atlassian should embrace and actively think about when designing these features.

From what I can see from the Smart Link documentation, I believe there is nothing that hinders us from implementing Smart Link resolvers using the service account scenario. However, I wanted to highlight that there are alternative perspectives on this feature that may not fully align with the intended implementation described in the documentation.

1 Like
5

Hi @tbinna ,

Thank you for your insight into different Auth scenarios.

We have been discussing the service account scenario, or OAuth asApp use case with Atlassian since 2021, when Forge providers first launched, and I think it is something that Atlassian should embrace and actively think about when designing these features.

I agree there are use-cases where system-to-system authentication would be very beneficial and definitely something we consider often.

For the initial release of Smart Links, we wanted to follow the same principal as we do internally where the Forge Function is invoked as the end-user to allow the App to check permissions on user level. As you mentioned it is completely possible to still connect system-to-system to pull the information, but the User context is there if required.
If the user is not in the remote system, your app could pull the information and still return it.

Care should be taken to not accidently expose the data to user’s that should not see the data. I would therefore recommend clear communication when the Admin configures the connection.

2 Likes
6

Worth noting that service accounts are just being introduced as of August it seems (haven’t seen an announcement), see also New Atlassian Service Accounts. I hope the Admin experience team is coordinating with the Forge platform team regarding API/SPI implications in this regard?

2 Likes