[[Identity_Propagation]]
== Identity Propagation

When securing an application with {auth-method}, a virtual security domain
will be created automatically for you. If your application invokes an EJB, additional configuration
might be required to propagate the security identity from the virtual security domain depending on how
the EJB is being secured.

=== Securing an EJB using a different security domain

If your application secured with {auth-method} invokes an EJB within the
same deployment (e.g., within the same WAR or EAR) or invokes an EJB in a separate deployment
(e.g., across EARs) and you'd like to secure the EJB using a different security domain from
your web component, additional configuration will be needed to outflow the security identities
established by the virtual security domain to another security domain.

The `virtual-security-domain` resource allows you to specify that security identities
established by a virtual security domain should automatically be outflowed to other
security domains. A `virtual-security-domain` resource has a few attributes, as
described below:

* `name` - This is the runtime name of a deployment associated with a virtual security domain (e.g.,
`DEPLOYMENT_NAME.ear`, a deployment that has a subdeployment that is secured using {auth-method}).

ifeval::["{auth-method}" == "MicroProfile JWT"]
* `auth-method` - The authentication mechanism that will be used with the virtual security domain.
If your application is secured with MicroProfile JWT, the `auth-method` should be set to `MP-JWT`.
endif::[]

* `outflow-security-domains` - This is the list of `security-domains` that security identities from
the virtual security domain should be automatically outflowed to.

* `outflow-anonymous` - When outflowing to a security domain, if outflow is not possible, should the
anonymous identity be used? Outflow to a security domain might not be possible if the domain does
not trust this domain or if the identity being outflowed to a domain does not exist in that domain.
Outflowing anonymous has the effect of clearing any identity already established for that domain.
This attribute defaults to `false`.

In addition to configuring a `virtual-security-domain` resource, you'll also need to update the
`security-domain` configuration for your EJB to indicate that it should trust security identities established
by the `virtual-security-domain`. This can be specified by configuring the `trusted-virtual-security-domains`
attribute for a `security-domain` (e.g., setting the `trusted-virtual-security-domains` attribute to
`DEPLOYMENT_NAME.ear` for a `security-domain` would indicate that this `security-domain`
should trust the virtual security domain associated with the `DEPLOYMENT_NAME.ear` deployment).

The `virtual-security-domain` configuration and `trusted-virtual-security-domains` configuration
will allow security identities established by a virtual security domain to be successfully
outflowed to a `security-domain` being used to secure the EJB.

=== Securing an EJB using the same virtual security domain

==== Within the same deployment

If your application secured with {auth-method} invokes an EJB within the same deployment (e.g.,
within the same WAR or EAR), and you'd like to secure the EJB using the same virtual security
domain as your web component, no additional configuration is required. This means that if no security
domain configuration has been explicitly specified for the EJB, the virtual security domain will
automatically be used to secure the EJB.

==== Across deployments

If your application secured with {auth-method} invokes an EJB in a separate deployment (e.g., across EARs)
and you'd like to secure the EJB using the same virtual security domain as your web component,
additional configuration will be needed. In particular, the EJB will need to reference the virtual
security domain explicitly.

The `virtual-security-domain` resource allows you to reference the virtual security domain
from the security domain configuration for the EJB. As an example, a `virtual-security-domain`
resource could be added as follows:

`/subsystem=elytron/virtual-security-domain=DEPLOYMENT_NAME.ear:add()`

An annotation like `@SecurityDomain(DEPLOYMENT_NAME.ear)` can then be added to the EJB,
where `DEPLOYMENT_NAME.ear` is a reference to the `virtual-security-domain` defined above.

This configuration indicates that the virtual security domain associated with `DEPLOYMENT_NAME.ear`
should be used to secure the EJB.
