Frequent How-To Questions for Application Developers

How to get the name of another application(s)

Use the Public API of "Read applications"

https://<service root path>/iam/application-management/v1/tenants/{tenantId}/applications

or "Read application"

https://<service root path>/iam/application-management/v1/tenants/{tenantId}/applications/{applicationId}

to retrieve the detailed application information, including application name.

In order to call these endpoints, you need "Read" privilege on the Multitenant Access Control resource "Modules", which are contained in those roles like "User Reader", "Module Manager", "Access Manager", "Access Configuration Manager/Reader" roles.
These two endpoints will deliver information of those application(s) back, who is/are either owned by the tenant or shared by contract(with both type "Provision" and "Access" and is therefore accessible for the tenant).

How to retrieve the list of tenants, who have access to my application

Use the REST endpoint of "Read Application ACL"

https://<service root path>/iam/access-management/v1/application/acl

to retrieve the ACL of your application, then filter the resource owning tenants from the response payload.

This endpoint contains those tenants, who are either the providing tenant of the application, or consumer tenants who gained access to the application by contract(with type "Provision").

How to determine who is calling an endpoint

For some usecases it is important to track which user or what application is calling an endpoint of your application. Applications should not trust information given by the caller (e.g. in the request body). Therefore, this information should be taken from the introspection result OpenID Connect Token Introspect Endpoint

For the following examples Multitenant Access Control is abbreviated as MACMA.

response excerpt

{
  // ... additional claims left out for clarity
  "aud": "1hyusm8b15new1vlcwg7ehhnmm",(1)
  "azp": "string", (2)
  "client_id": "string", // use this instead of azp (3)
  "sub": "860aefa0-388a-444e-8b8b-d561a7406f74" (4)
}

1	usually (but not guaranteed to be) a single string in Industrial Application System (or array in accordance to Section 4.1.3 of rfc7519). For MACMA single-audience tokens, this is a simple string containing the applicationId of the application introspecting the token (i.e. 'your' application).
2	defined for authorization token (but still delivered by MACMA introspection endpoint). Use client_id instead. The authorized party to which the ID Token was issued. See Section 2.2 of rfc7662 and Learn more The client that requested the token for the user (so for a user-token usually frontend- (or rarely backend-) client of your application)
3	defined for introspection result section 4.3 of rfc8693: The client that requested the token for the user. For a user-token this is usually the frontend- or more rarely the backend-client of the introspecting application. For a service2service token, this is the clientId of the calling application.
4	an identifier (not guaranteed to be uuid) of the logged-in user, which may be used in MACMA’s getUser API. Valid but not relevant for service2service tokens. See also Section 2.2 of rfc7662 and Section 4.1.2 of rfc7519

Sample response service2service token, Application "Caller" using APIs of MyApplication

{
  // ... additional claims left out for clarity
  "aud": "MyApplicationClientId", (1)
  "azp": "CallerClientId",  (2)
  "client_id": "CallerClientId", (2)
  "sub": "7cfd2d73-4adf-4ef1-94d8-3ff4ce55f866" (3)
}

1	when introspected by MyApplication, this is always "MyApplicationClientId" since otherwise it cannot be successfully introspected and the endpoint will return active=false.
2	Since service2service tokens are requested by the calling service ('Caller' in this example), this id is found in azp and client_id.
3	is a valid userId related to the technical user account linked to the application. Those users are not offered by MACMA’s APIs to list users. Therefore, you should not use this value in the service2service case.

Sample response user token, MyApplication logged-in the user using its public client

{
  // ... additional claims left out for clarity
  "aud": "MyApplicationClientId", (1)
  "azp": "MyApplicationClientId-frontend",  (2)
  "client_id": "MyApplicationClientId-frontend", (2)
  "sub": "e98358e7-ea75-496f-81ad-0b3d9d5723ee" (3)
}

1	when introspected by MyApplication, this is always 'MyApplicationClientId' since otherwise it cannot be successfully introspected and the endpoint will return active=false.
2	Since the user was logged-in using MyApplication’s public client, its Id is found in azp and client_id.
3	is a valid userId and is safe to store as e.g., last-editor or creator. Hint: MACMA UserIds are only valid in combination with a tenantId.

Sample response user token, MyApplication logged-in the user using its confidential client

{
  // ... additional claims left out for clarity
  "aud": "MyApplicationClientId", (1)
  "azp": "MyApplicationClientId",  (2)
  "client_id": "MyApplicationClientId", (2)
  "sub": "e98358e7-ea75-496f-81ad-0b3d9d5723ee" (3)
}

1	when introspected by MyApplication, this is always "MyApplicationClientId" since otherwise it cannot be successfully introspected and the endpoint will return active=false.
2	Since the user was logged-in using MyApplication’s confidential client, its Id is found in azp and client_id.
3	is a valid userId and is safe to store as e.g., last-editor or creator. Hint: MACMA UserIds are only valid in combination with a tenantId.

So in summary the logic can be simplified to:

How to know whether another application is available for a specific tenants

Calling another application

When requesting a token to communicate to the other application for a specific tenant, if that application is not available for the tenant, Multitenant Access Control will decline the getting token request with http status code 400 (Bad request), and additional information like:

{"KC-5: No client match found. Invalid scopes: [...]"}

The caller application can decide based on this information whether the request should be retried.

Serving another application

If there is such business requirement as "Data of the callee’s application should only be accessible when the related caller application is available for specific tenant", the REST endpoint of "Read applications" can be used

https://<service root path>/iam/application-management/v1/tenants/{tenantId}/applications

This endpoint returns also applications shared by "Access". To exclude them, only take those applications whose owningTenantId (from the response) <> tenantId (from the path).

While there is no "application available/unavailable integration event", this request can be performed in scheduled interval to keep the information as up-to-date as possible.