How to enable cross realm trust sharing

Introduction

HERE IAM enables complex organizational setups by allowing a trust establishment between multiple organizations. If your organization has multiple HERE platform accounts, and you would like to share resources and data across accounts, you need to establish cross organization trust. Once trust is established, you can then link a resource from another organization.

📘
Note
Cross organization/realm trusts can only be created for Project resources.

Trust can be established between projects, organizations, or a combination of both.

By default, any project's linkable resource can be made available for sharing to the target organization/project once cross-realm trust is established. Specific resource sharing can also be limited to a specific project in the target organization.

Terminology

Organization or realm: A grouping that scopes all IAM entities, HERE services, and resources within the same security namespace. For more information, see Concepts.
Project: An access-controlled collection of resources, such as catalogs, pipelines, schemas, and services. Any identity, regardless of Role, can create new projects. Both organization admins and project admins can manage projects. For more information, see Manage projects.
Resource: A HERE resource, like a pipeline or schema, identified by a unique HERE Resource Name (HRN).
Linkable Resource: A project-based resource that can be linked to another project. A resource can be made linkable to a specific project or any project in your own organization. However, you must first establish cross-realm trust before you can link a resource to a specific project, or a project outside of your organization.
Cross-Realm Trust: Trust established between two organizations/realms to share resources between source realm or project and target realm or project.
Source realm: The source HERE Platform account which contains resources to be made available to Target Realm via Cross Realm Trust sharing.
Source project: The project in which a resource(or resources) was created, which subsequently will be made available for Cross Realm sharing. This project now becomes the "home project" for those resources. A resource can only have one home project, but resources can be shared to other projects or organizations/realms in your organization so that they can be reused in multiple use cases. Storage for a resource is logged to the home project, and data I/O for using the resource is logged to the project using it.
Target realm: The recipient HERE Platform account which, after Cross Realm Trust has been established, will be able to link to resource(s) made available in source Realm or Project.
Target project: The project in the target realm where a resource (or resources) can be linked after being made available for Cross Realm sharing. This project can use the shared resources based on the permissions granted during the sharing process.

Tutorial—Cross Realm Trust and Resource Sharing

Cross Realm trust can be established either between two realms or two projects to allow Linkable Resources to be received from the source of the resource. The source HRN is defined by either the home project or the realm of the resource. The CrossRealmTrust is established with a target specified in the path, which could either be a specific project or the entire realm. An access token from an identity with appropriate privileges in the target realm should be used to create/update the CrossRealmTrust.

Step 1—Create a source and target realm

In this guide, we will assume that this is already done. For more information, see Realm APIs.

Step 2—Create a source and target project

In this guide, we will assume that this is already done using the platform portal Projects Manager or the Project CLI.

Step 3—Create an application in target realm

Create an app in the target realm. In this guide, we will assume that this is already done using the platform portal App Manager or the App CLI.

Step 4—Enable establishing organization trust

Only an identity with OrgAdmin or CrossRealmTrustManager role are allowed to manage cross-realm trust between the source and target. Hence, org_trust_app should have either of these roles.

Follow these steps:

Log in to the HERE platform in the target realm.
Go to App Manager and search for app created in step 3.
Select the application and click on More dropdown and select Enable establishing organization trust.
You should see a pop-up: Establish organization trust rights granted. Changes may take up to 5 minutes to be applied.
Roles information for the app should say: Can establish organization trust.

Role assignment can also be done using Roles API or Roles CLI.

The same steps are used to revoke privileges/role as well.

Step 5—Manage Cross-Realm Trust

Managing (create/update/delete/show) a cross-realm trust between source and target realm now can be done either using the Manage Cross-Realm Trust API or Manage Cross Realm Trust CLI.

The following features are supported:

An identity with a CrossRealmTrustManager or OrgAdmin role in a realm can create or update cross-realm trust with another realm, which establishes that their realm (the "target" realm) will accept linkable resources from a specified, trusted "source" realm.
An identity with a "CrossRealmTrustManager" or "OrgAdmin" role in a realm can revoke "cross-realm trust" with another realm, which means it will not accept linkable resources from the specified "source" realm any longer. If such trust is revoked, no new links can be created, and any links based on it will continue to exist, but they stop working and return a 403 unless/until the trust gets re-established. To remove existing links, a project member with appropriate rights in the target realm will need to unlink the resources from the project.
An identity in a realm can list cross-realm trusts to view both a) which source realms are trusted by their realm, and b) which target realms have their realm as a trusted source.

Follow these steps for CLI:

Credential Setup

Log in to the HERE platform in the target realm.
Go to App Manager and search for app created in step 3.
In the Credentials tab, go to the OAuth 2.0 tab and click Create credentials.
In the dialog box that opens, click Download to download the credentials.properties file. Once you click Close, you can no longer access your access key ID and access key secret.
To create a default profile and associate your credentials with it, run the following command olp credentials import default credentials.properties.
To verify that your credentials have been correctly configured, execute the command below in the directory that contains the OLP CLI JAR file olp api token get. A token is generated if your credentials have been configured properly.

Note: For more information on using credentials and profiles, see Credentials setup.

Create/update cross organization trust

Complete credential setup and generate OAuth2.0 token as mentioned in Step 5.A and ensure the app has been assigned "CrossRealmTrustManager" or "OrgAdmin" role as mentioned in step 4.
Create or update cross-organization trust can be done by the app using the CLI command which will allow linkable resources to be received from the home project or the realm of the resource.

olp org trust create <source HRN> <target HRN> [command options]

<source HRN>: The HRN identifying the source realm or project. This is required.
<target HRN>: The HRN identifying the target realm or project. This is required.
--target-project-required <true|false>: Indicates whether an actor in the source realm must always specify a project in the target realm when offering a linkable resource. When true, the user or app in the source realm cannot offer the linkable resource broadly in the target realm, to the point that it could be added to any project in the target realm. If the parameter is not specified, or set to false, the user or app in the source realm can create linkable resources that target the entire realm. These resources can then be added to any project in the target realm.

For more information, refer to Create/Update Org Trust CLI.

Step 6—Create resources in source realm for sharing to target realm

Once cross-realm trust is established between the two realms exchanging data, identity with "manage" access to a resource in the home project of that resource can make the resource available for linking in another project in another realm. Permissions can include “read” and/or "write."

Follow these steps to create resources inside or outside a project:

Log in to the HERE platform in the source realm.
Go to Project Manager.
Select the source project where resource needs to be created.
Click on "Add Catalog" dropdown and click on "create a new catalog."
Fill in the form with required information to create a resource. For the "Home Project," select "No Project" if resource needs to be created outside a project or select the specific project if resource needs to be created within a project.
Once resource is created, it will show up in the "Resources" section.

Step 7—Sharing: Make created resources linkable

Once resource is created, they can be made available for linking.

Note: This step can only be done via CLI for cross-organization.

Follow these steps:

Credential Setup

Log in to the HERE platform in the source realm.
Go to App Manager and search for app created in step 3.
In the Credentials tab, go to the OAuth 2.0 tab and click Create credentials.
In the dialog box that opens, click Download to download the credentials.properties file. Once you click Close, you can no longer access your access key ID and access key secret.
To create a default profile and associate your credentials with it, run the following command olp credentials import default credentials.properties.
To verify that your credentials have been correctly configured, execute the command below in the directory that contains the OLP CLI JAR file olp api token get. A token is generated if your credentials have been configured properly.

Note: For more information on using credentials and profiles, see Credentials setup.

Create link availability for the resource

Complete credential setup and generate OAuth2.0 token as mentioned in Step 7.A
A resource can be made available to be linked to a project or all projects in the organization, using the following CLI command:

olp resource link availability create <resource HRN> [command parameters] <resource HRN>: The HRN of the resource. This is required. --available-to <project HRN>|all-projects Either the that the resource is made available to a link or all-projects to make the resource available to link to all projects in the organization. This is required.

For more information, refer to Create resource link availability The following features are supported:

Assume that cross-realm trust is established between the two realms exchanging data.
Only identity with manage access to a resource in the home project of that resource can make the resource available for linking in another project in another realm.
Identity with manage access to a resource in the home project of that resource can choose to make resource(s) available for linking in another project in another realm with “read” and/or "write" permissions.
Identity with manage access to a resource in the home project can choose to make resource(s) available for linking in all projects in the specified organization or only specified project(s) in the organization.
Identity with manage access to a resource in the home project can view what realms and associated projects in each organization have access to a link to the resource and those that have linked to the resource.
An identity in one realm cannot get a list of projects in another realm. Therefore, to share a resource to all projects in another realm or a specific project in another realm, the identity will need to be provided with the project HRN and realm ID by an identity in the target realm. This process is not facilitated via HERE platform APIs or CLI.
Any member of a project to which a resource from outside their realm has been made available (shared) can link that resource to the project if they have the permissions to do so.
An app (and by extension, a pipeline via an app) or an identity in a project can read and/or write from a resource. They can also read from its associated schema(s) from outside its realm that's been linked to its project if they have the permissions to do so.
It is possible to restrict project members from having access to certain resource types. Therefore, it's possible that not all project members will be able to link a resource to a project, which is why specific permissions are needed to take this action.

Step 8—Listing resources available to be linked

Once cross-realm trust is established between source and target realm and resources have been made linkable, identities in the target realm can then list resources available to be linked (which should now show the resource they just made available for linking), and then link the resource from the source realm to a project in the target realm.

Follow these steps:

Credential Setup

Log in to the HERE platform in the target realm.
Go to App Manager and search for app created in step 3.
In the Credentials tab, go to the OAuth 2.0 tab and click Create credentials.
In the dialog box that opens, click Download to download the credentials.properties file. Once you click Close, you can no longer access your access key ID and access key secret.
To create a default profile and associate your credentials with it, run the following command olp credentials import default credentials.properties.
To verify that your credentials have been correctly configured, execute the command below in the directory that contains the OLP CLI JAR file olp api token get. A token is generated if your credentials have been configured properly.

Note: For more information on using credentials and profiles, see Credentials setup.

List project resource availability

Complete credential setup and generate OAuth2.0 token as mentioned in Step 8.A
To list the resources and sub-resources available for linking to the project identified by the provided HRN, run the CLI command:

olp project resource availability list <project HRN> [command parameters] <project HRN>: The HRN of the project. This is required. --type <resource type>: A type of resource for which link availability is listed for the specified <project HRN>. For example, catalog, pipeline, pipeline-template, schema, artifact, flow, flow-pattern, service.

For more information, refer project resource availability list

Step 9—Adding linkable resources to project

Finally, linkable resource can be added to projects where they are needed once the above steps are performed.

Follow these steps:

Credential Setup

Log in to the HERE platform.
Go to App Manager and search for app created in step 3.
In the Credentials tab, go to the OAuth 2.0 tab and click Create credentials.
In the dialog box that opens, click Download to download the credentials.properties file. Once you click Close, you can no longer access your access key ID and access key secret.
To create a default profile and associate your credentials with it, run the following command olp credentials import default credentials.properties.
To verify that your credentials have been correctly configured, execute the command below in the directory that contains the OLP CLI JAR file olp api token get. A token is generated if your credentials have been configured properly.

Note: For more information on using credentials and profiles, see Credentials setup.

Add resources to project

Complete credential setup and generate OAuth2.0 token as mentioned in Step 10.A
Add linkable resource to a project using the following CLI command: olp resource project add <resource HRN> <project HRN> [command parameters]

<resource HRN>: The HRN of the resource, where the resource is either a schema or a catalog. Schema HRN may or may not contain a version number which will not affect the command result. This is required.
<project HRN>: The HRN of the project to add as resource home. This is required.

For more information, see resource project add

Additional notes

Identities can refer to the documenation for the API or CLI to get additional information about the resources.

The following additional features are supported:

A resource can only be managed in its home project.
A member of a project can list resources in the context of a project and see relation and availability of resource, i.e. "home," "linked," "available for linking."
A member of a project can list resources in the context of a project and see if resources that are "linked" or "available for linking" are shared from inside or outside their realm.
Usage reporting: Storage continues to be billed to a home project of resource. Data I/O is tracked/billed based on project requesting data, i.e., if a project in another realm accesses the data it pays for it and sees associated usage reporting. No usage reporting for realm that owns the resource about use of the resource outside their realm.