Support for Multi-Instance Apps

[dlozlla]

Summary
This proposal considers a protocol-level solution for scenarios where a user needs to connect to a specific instance (e.g., tenant, organziation, workspace) of a Resource App, particularly when these multiple instances share a common issuer URL. The goal is to create a mechanism that allows a Requesting App to specify the target instance and ensures this choice is communicated end-to-end, so it can be correctly interpreted by both the IdP and the Resource App's authorization server.

Problem
In many enterprise environments, a single application may offer multiple distinct instances. For example, consider an observability platform with separate instances for development and production logs. Often, these instances share a single audience (i.e., issuer URL) and resource identifier for their APIs. In these cases, access to the Resource App's API is managed by a custom claim injected into the access_token after the user authenticates with a specific instance.

The current Identity Assertion Authorization Grant does not define a standard way for a Requesting App to specify a target instance under these conditions. This ambiguity prevents a seamless user experience, which should ideally mirror selecting an application from an SSO dashboard and being directed to the correct instance.

This overall challenge can be broken down into two parts:

1. The Discovery Problem
Before a user can make a choice, the Requesting App must first know what choices are available. How can the Requesting App learn which Resource Apps, and their specific instances, the logged-in user is permitted to connect to?

While solving discovery is critical for the end-to-end experience, it is handled separately in issue #52. For this issue, we will assume the Requesting App has a method to determine which instance the user wants to access.

2. The Request Problem
This is the focus of the proposal. Once the user has selected an instance, how does the Requesting App communicate this choice to the IdP? The current protocol lacks a standard parameter to differentiate the target instance when it shares an audience/issuer URL with others.

Proposal
We propose using the client_id of the target Resource App instance within the IdP as the unique identifier. This client_id would be included in the initial Token Exchange request and the resulting Identity Assertion (ID-JAG).

Rationale:

• Uniqueness & Existing Trust: Each Resource App instance registered with the IdP for SSO already has a unique client_id. This identifier is known and trusted by both the IdP and the Resource App.
• IdP Policy Enforcement: The IdP can use the provided client_id to locate and apply the specific authorization policies associated with that instance.
• Resource App Tenant Mapping: The Resource App's Authorization Server already relies on this client_id for its OIDC federation with the IdP. It can therefore use the client_id from the assertion to unambiguously map the request to the correct internal tenant, organization, or workspace.

[mcguinness]

For clarification issuer, resource, and client_id are identical across instances but only tenant is different?

[dlozlla]

issuer and resource are identical across (resource app) instances
client_id and tenant are different

[dlozlla]

client_id is different per instance on the IdP, and it maps to different tenant/workspace/org on the Resource App side

[mcguinness]

Would it make sense the requesting app client to create a client assertion actor JWT for the Resource App client and pass as actor_token to token exchange?

[dlozlla]

The resource app is actually the one exposing the resources and not consuming them, so I think it wouldn’t make sense to do that. IMO it would make more sense to somehow provide additional details on the target audience or the resource to access. We were debating about using the tenant claim, but that seems to really refer to a concept on the IdP rather than on the target audience or resource.

[mcguinness]

Clarifying some assumptions and relationships to open issues first

• There are multi-tenant (e.g. Google) and single-tenant IdPs (e.g Okta) that are the ID-JAG issuer
• There are multi-tenant and single-tenant RPs that are the ID-JAG audience
• Both the ID-JAG issuer and audience could support per-tenant clients or global (cross-tenant) clients.

Tenancy is relevant from both an issuer and audience perspective

I opened #39 with intention to adopt tenant claim to describe the issuer's tenant for a multi-tenant IdP. The ID-JAG acts as a cross-domain Identity Assertion so it should assert an identity similar to an id token issued by the IdP for the resource app

Resource, Audience, and Scope are linked as you need all 3 to uniquely identify an authorization delegation for an AS and ensure there isn't a mix-up attack with an ambiguous scope name for example. These have existing foundation in the security properties of the token request and I don't think we should be trying to overload. These values should be consistent across OAuth specs and may be discovered with Protected Resource Metadata or Authorization Server metadata for example.

The ID-JAG audience (the one processing the ID-JAG) is the Resource App's Authorization Server identifier and must be unique within the IdP tenant as it functions as the cross-domain identifier to give the IdP context of the cross-domain request while resource+scope is relative to the Resource App's Authorization Server and may not be unique within the IdP tenant. I think you may be identifying a gap here as that AS may be multi-tenant but the identifier isn't and when used a key there isn't a way to have multiple instances for different tenants. This would be something like aud_tenant similar to aud_sub in https://openid.net/specs/openid-connect-enterprise-extensions-1_0.html#name-aud_sub. Its not clear how the IdP obtains this value and how its bound.

The ID-JAG presenter is a client that is registered in the Resource App's Authorization Server. There is currently undefined behavior on how the IdP selects what client in the Resource App Authorization Server the ID-JAG should be used by and can act as the user. This IdP can assert any client it wants and the Resource App Authorization Server needs to determine what it trusts. We currently don't require client authentication is required for the ID-JAG token request to the Resource App Authorization Server (its vague). Providing some security considerations and optionally some processing instructions was the goal of #45. There is also an open issue to define how to bind the ID-JAG to a key so that the presenter must demonstrate proof of possession #28 . If we require client authentication or DPOP for the ID-JAG than only a client that knows the secret/key/etc can use the the ID-JAG. This should help with mix-up attacks/etc.

My reading of this issue is the following

• The Resource App Authorization Server identifier is multi-tenant (e.g doesn't have tenant in the identifier such http://as.example.com)
• The Resource App Authorization Server has a per-tenant client registration and the client identifier is unique across tenants
• The protected resource that the client wants to obtain cross-domain access to isn't tenant specific (e.g https://rs.example.com)

Not sure if the subject that the ID-JAG asserts resolves to an account in a specific Resource App tenant or not. Would each environment (e.g development vs production) have a different subject identifier for the user? What does the IdP put into an ID Token for SSO to these instances?

I think the issue of selecting the client for the ID-JAG might be similar to user as well if there is one to many relationship between the IdP the Resource App tenants and accounts. An ID-JAG currently doesn't identify a Resource App tenant but rather this handled by processing the Resource App processing the iss, sub, tenant of the identity assertion and the client_id.

[mcguinness]

Since audience is a logical name in Token Exchange and doesn't need to be 1:1 to the ID-JAG aud claim AFAIK which must be the AS identifier then the cheat code here may be that we just relax the constraint that it must be the AS identifier and if the IdP provides a mechanism to discover other logical names (e.g #52) or a requesting app has a priori knowledge than they can just pass this value for audience in the token exchange request which IdP can use to map a sub and client_id for the Resource App tenant

[dlozlla]

Thanks for the context and the explanation, @mcguinness !

I think your reading of the issue is accurate. The Resource App AS is multi-tenant while the audience, resource and client_id - used by the Requesting App - are unique across tenants. To make things a bit more complex, the same IdP user sub can map to multiple of these tenants, but I think you’re spot on in saying that determining the tenant may follow the same procedures that are used to do the same for SSO flows. In those cases, we either:

1. ask the end user <- this is not an option in this case
2. receive the id of the tenant in the login request, or
3. infer it from sort of the “account” being used on the Resource App AS - we really call them connections and they represent a specific integration with a federated upstream IdP. Several of these accounts may map to the same IdP user but they define a local difference, let’s say a different local user, we can work with.

Focussing on option 3: for normal SSO, each of these “accounts”/connections map to a specific client_id on the IdP, that is used to start the login flow from the Resource App AS tenant. It is the client_id that would be used to sign in if the user clicks on that specific “Resource App instance” (e.g the datadog-dev app instance in our example) on the IdP SSO dashboard. This is precisely the piece of information I think we’re missing and we need to receive in the ID-JAG. It is actually better than configuring the tenant_id along with the Resource App instance -that would be equivalent to option 2 - as the IdP naturally knows its own client_ids, so we avoid having to configure any additional attribute on the IdP and instead we encapsulate the logic to determine the tenant within the Resource App AS itself. In summary, the idea would be to determine the Resource App tenant from the audience + resource-app-instance-client-id@IdP coming in the ID-JAG. If this makes sense, we “just” have to find the proper element for this client_id to travel within the assertion.

[mcguinness]

We made the assumption that iss + tenant + sub was enough for the resource app to perform account resolution and identify its local tenant context and account with the ID-JAG just like it would for an ID Token. If multiple tenants in the resource app trust the same iss and tenant and sub isn't a pair-wise identifier for the ID Token but rather a public identifier (https://openid.net/specs/openid-connect-core-1_0.html#SubjectIDTypes) then I could see the need for an additional claim in the ID-JAG.

The simplest name I can think of is sub_client_id. Would love to get @aaronpk thoughts on this.

Might be good to also recommend use of pair-wise identifiers!

-Karl

[meghnadubey]

I think we may be overloading client_id too many times. There is the original or primary client_id(client_id/client_secret), if used for client authentication@Resource, then there is the proposed client_id in the act claim to convey the requesting app client_id@IdP, and now the sub_client_id for user identification in RS deduced through resource app client_id@IdP.
My question is, will the prefix be enough to distinguish between the non-primary client_ids, act_client_id and sub_client_id, or should we come up with enturely different names to identify the purpose of the two non-primary ids. act claim is an object so it is a little more clear, so one option is to adopt similar metadata object style for sub_client_id.

[mcguinness]

The sub_client_id isn't part of the actor chain. Its just part of a complex subject identifier similar to iss_sub or something in https://www.rfc-editor.org/rfc/rfc9493 & https://openid.net/specs/openid-sharedsignals-framework-1_0-ID3.html#section-3.3 and needed to resolve a global subject identifier type such as

  "sub_id": {
    "format": "iss_client_sub",
    "iss": "https://issuer.example.com",
    "sub": "public_identifier"
    "client_id": "123"
  }

Since this wasn't a Security Event that can describe multiple types of subjects, my suggestion was just to flatten the complex type as iss and sub are already required claims with existing semantics. '

The actor chain and the client_id in the ID-JWT should describe who is acting as the user.

[dlozlla]

Considering the concept we want to capture (the client_id of the target resource app on the IdP) seems to be very specific to cross-app/domain scenarios, rather than using a more generic term, I I wonder if it would be better to be more specific and name the new param resoruce_app_client_id?

[mcguinness]

that’s what the client_id is. What is unique here is that we need to the SSO client id and not the requesting app client for the resource app which is what folks are used to. It’s tied to the subject and not the requesting app.