The CIAM Domain Model is a collection of entities that describe the current state of Topcon's dealer and customer network. It’s uniquely tailored to Topcon, capturing the data necessary to model how we do business—particularly how our dealers support end consumers.

This model provides Topcon web services with a unified dataset that represents our dealer network, customer base, their respective employees, and the roles those employees hold within each organization.

If you are familiar with Role-Based Access Control (RBAC), much of this section will feel familiar. However, we've added certain entities to better reflect Topcon’s business model.

This section covers many commonly used terms and entities, some of which will need to map to corresponding objects in your Topcon web services. All entities discussed below have a set of documented API endpoints available here. Please take the time to familiarize yourself with each entity.

Business Partner

A Business Partner can be one of the following: Direct Customer (Dealer), Indirect Customer (End Consumer), Technical Partner, OEM, Topcon group (such as Sales Europe or Engineering Brisbane), or any other business entity that works with Topcon.

Key Point: A Business Partner is the primary security grouping within CIAM, representing the "C" in Customer Identity Access Management (CIAM). All access to Topcon's products or services is always viewed through the lens of a single Business Partner. When a user signs in, they can only sign in and access data for a single Business Partner at a time. Topcon considers customers as organizations, not as individual persons. A Business Partner represents a tenancy in a SaaS application, and all resource data belongs to one Business Partner.

At Topcon, the source of truth for Business Partner data resides in our Master Data (SAP MDM/MDG). A middleware integration replicates the Business Partner hierarchy from Master Data into CIAM.

Technical Points:

Topcon Web Services should organize their data to ensure it is segregated by Business Partner.
At sign-in, an Identity must select a single Business Partner during the authentication step of the OAuth flow. CIAM enforces this Business Partner selection during authentication, ensuring tokens are scoped to a single Business Partner.
Each CIAM access token is a JWT containing a tcbp claim that maps to the current Business Partner being accessed.
The Business Partner entity is uniquely identified by the ext_id field from Master Data.
Business Partners have a Topcon Resource Name (TRN), which Topcon Web Services may use to reference the Business Partner.
Product designers should design Topcon Web Services so that the user interface operates within the context of a single Business Partner. While it's possible to present information across Business Partners (e.g., a dealer viewing subscriptions for all customer devices), it's better to treat this as an aggregate view that belongs to the dealer rather than as a collection of resources across different customer Business Partners.
Business Partners have an owner Identity, representing the root user or principal contact for the Business Partner. The owner is granted certain access rights, such as creating Users.

Business Partners Hierarchy

Business Partners are organized into a hierarchy within both Master Data and CIAM. CIAM recognizes two types of hierarchies:

Divisional Hierarchy: A parent-child structure expressing ownership, such as a parent dealer (sold-to) with child divisions (ship-to).
Support Relationships: This hierarchy expresses relationships where, for example, Dealer-X can support Customer-Y. These relationships are defined through Support Agreements, discussed below.

Key Point: This dual hierarchy enables us to delegate support responsibilities to the entities best equipped to handle them—the dealers and customers themselves. It facilitates self-service for each Business Partner, both within their own divisional hierarchy and across support relationships defined by Support Agreements.

Business Partner Management

Business Partners cannot be created directly within the CIAM PAP. CIAM contains a shadow copy of Business Partner Master Data, and Business Partners can only be created in Master Data by the data governance team (for Direct Customers/Dealers) or through the Partnership Management API (for Indirect Customers/End Consumers).

Identities

The Identity entity refers to an individual end-user (a person) who has an email address. The source of truth for Identities in Topcon's CIAM is our PingONE Identity Provider (IdP) and any Identity Providers that our Business Partners register using the Identity Provider entity discussed below.

All Personal Identity Data (PID) such as name, email, and password is primarily stored in these source-of-truth Identity Providers and replicated (except for the password) into CIAM as end-users sign in to our services.

Key Point: An Identity represents an individual person and should NOT be thought of as a user, an account, or a Business Partner. The Identity entity models only the PID of an individual person, nothing more.

In Topcon's CIAM, a person can sign in as their Identity to perform self-service tasks such as accepting invites to join Business Partners, updating their PID, managing signed-in devices, etc.

Identities are associated with Business Partners through the User entity, which is discussed next.

Technical Points:

The Identity entity is uniquely identified by the realm and subject fields, which come from the upstream Identity Provider.
- The realm represents the upstream Identity Provider, and the subject is the subject claim from that provider.
Each CIAM access token is a JWT containing a tcid claim that maps to the currently signed-in Identity.
Identities have a Topcon Resource Name (TRN), which Topcon Web Services can use to reference the Identity.
Topcon Web Services should never persist PID from the Identity entity for security reasons.
- For example, transactional or audit data tracking "who-did-what" in a web service should use the TRN of the Identity, not the email address.

Users

Key Point: The User entity connects an Identity entity to a Business Partner entity and have one ore more Profiles.

An Identity can belong to multiple Business Partners by having multiple Users, though this number should generally remain small. For example, if the Identity "Sally Ann" works for Business Partner "Dealer-X", then a User entity represents this "works for" relationship.

Note: In the past, dealer users have added themselves to hundreds of customer organizations to offer them support. This is no longer required, and won't be supported due to limits on the number of Users which can relate to an Identity. Dealers can now support hundreds of Customers through the Support Agreement entity.

Users are managed by the owners and managers of Business Partners. Owners and managers invite Users and assign them Profiles, which are high-level roles across all Topcon Web Services.

Profiles

Key Point: Think of Profiles as high-level roles. A Profile maps to certain roles within a given Topcon Web Service.

Why do we call them profiles and not roles? Good question. Since CIAM is used across many different Topcon Web Services—some of which already have their own roles—we wanted a term that indicates a higher level than service-specific roles.

Topcon has developed a set of Profiles tailored to different types of Business Partners and specific focus industries. This can be best understood through some examples:

Business Partner: Dealer
- Focus Industry: Sales
  - Profile: Sales Manager
  - Profile: Sales Person
- Focus Industry: Technical Support
  - Profile: Technical Installer
- Focus Industry: Company
  - Profile: Information Technology
  - Profile: User Manager
Business Partner: End-Consumer
- Focus Industry: GNSS
  - Profile: Network User
- Focus Industry: Earthworks
  - Profile: Site Manager

This is just a small subset of the available profiles. For the complete list, refer to the profile data in the OPA bundle here. Note that we have more profiles than just Admin/Not Admin, but not so many that users will become frustrated and need to switch profiles often. Profiles are designed to align closely with job descriptions.

The advantage of using a common set of Profiles across all Topcon Web Services is that end-users only need to manage user lifecycles once. For example, "Sally-Anne" only needs to invite "Bob" to "Customer-Y" as a "Site Manager" one time, and that profile will map to all Topcon Web Services.

Key Point: To simplify our products, as well as to reduce testing complexity, only one Profile can be selected for a User at sign-in.

As you integrate with CIAM, you’ll need to choose the profiles relevant to your application and decide how to map them, either directly (if you are developing a new application) or to your existing roles.

Technical Points:

Each CIAM access token is a JWT containing a tcpf claim that maps to the Profile selected at sign-in.
At sign-in, a user can only see the Topcon Web Services they have an appropriate Profile for. This is defined in the app_policy of the Topcon Web Service, as discussed below.
At sign-in, if a user has more than one Profile for the target web service, they must select the desired Profile.
If a signed-in user navigates to an application for which they do not have the proper Profile, they are redirected to My Topcon (the self-service dashboard).

Domains

Each Business Partner can register one or more domain names using the Domain entity, allowing them to prove ownership of the domain name.

Key Point: Once a Business Partner proves ownership of a domain name, any Identity signing in with an email address from that domain will be able to select the associated Business Partner by virtue of the fact that they are from that domain.

For example, when "bob@customer-y.com" signs in for the first time, Bob can choose the Customer-Y Business Partner. This helps reduce the problem of account duplication, where different employees from the same Business Partner accidentally create duplicate versions of the Business Partner. Bob won't be a User of the Business Partner, but he can see it and Request-to-Join.

It's beneficial for a Business Partner to register a Domain, even if they don’t register an Identity Provider (discussed next), to prevent account duplication.

Identity Providers

Each Business Partner can register one or more OAuth 2.0 OIDC or SAML Identity Providers. We refer to this as Bring Your Own Single Sign-On (BYO SSO).

A Domain must be registered before creating an Identity Provider entity.

Key Point: When a Business Partner registers their own Identity Provider, their employees can use their company’s email and password to sign in to Topcon Web Services.

Clients

Each Business Partner can register OAuth 2.0 Clients.

Key Point: The Client entity allows Business Partners to self-service the creation of OAuth 2.0 clients for accessing Topcon Web Service APIs.

To create an OAuth 2.0 client, you’ll need to know an app_policy that your Business Partner type supports. App policies determine which Resource Servers and scopes (i.e., which Web Services) your OAuth 2.0 client can access. You will only have access to the parts of the Topcon Web Service APIs that are granted by the selected App Policy.

Information about the available App Policies for your Business Partner can be found here.

It's important to note that:

Dealer Business Partners can register OAuth 2.0 clients (Web Services) that are available to the customers they support.
Customer Business Partners can register OAuth 2.0 clients (Web Services) that are available to all of their users.
Topcon, OEMs, and Technical Partners can register OAuth 2.0 clients that are available to all Dealers and Customers, as determined by Topcon.

These Web Services are visible to end-users through the Brand Bar application menu and the My Topcon self-service dashboard.

Support Agreements

Coming with phase 3

Groups

Coming with phase 3

Permissions

Coming with phase 3