# CORTEX Architecture

CORTEX federates identity and access across independent
organizations so that researchers can sign in with their existing
campus credentials and reach the applications a collaboration shares
with them.  A *virtual organization* (VO) is that collaboration: a
group of people drawn from many home institutions who are granted a
common set of resources.

Rather than ask every application to integrate with every campus, and
every campus to trust every application, CORTEX places a single
**Federation Gateway** between them.  Each participant trusts only the
gateway, and the gateway brokers identity, discovery, and
authorization on their behalf.

The sections below describe each
component in the diagram above and the information it exchanges with the proxy.


```{image} _static/cortex-design.png
:width: 100%
:class: sd-m-auto
:name: cortex-architecture
```

## Federation Gateway (Proxy)

The Federation Gateway is the hub of the architecture.  It presents
itself as a service provider to campus identity providers and as an
identity provider to protected applications, standing in the middle as
a proxy.  Every login flows through it.

This indirection is what keeps the collaboration manageable.  Campuses
and applications each maintain exactly one trust relationship — with
the gateway — instead of one per counterparty.  The gateway is also
the single place where VO membership and entitlements are applied, so
authorization decisions stay consistent no matter which campus a
researcher comes from or which application they visit.

## Campus Identity Providers

Campus Identity Providers(IdPs) authenticate researchers against the
credentials they already hold at their home institutions.  When a user
signs into an application integrated with CORTEX, their campus IdP asserts a **campus identity** to the
proxy.


:::{admonition} Guidance

CORTEX does not manage these credentials or replace campus login systems.
:::

## Discovery Service

Because a Virtual Organisation (VO) spans many institutions, the proxy must first learn
which campus a given user belongs to during the authentication process.
The
[Discovery Service](https://shibboleth.atlassian.net/wiki/spaces/EDS10/overview?homepageId=2383446015) performs
this home realm discovery role where a user selects their home
institution to tell the proxy where to send the authentication
request.

## Collaboration Management Platform (Registry)

[Registry](https://spaces.at.internet2.edu/spaces/COmanage/pages/190360385/COmanage+Registry+PE+Technical+Manual)
is the system of record for the virtual organization. It
holds **VO registration data** of who has enrolled in the collaboration,
the groups and roles they belong to, and the lifecycle state of their
membership.

Registry answers the question of *who belongs to the
collaboration*, which is distinct from *who a person is at their
campus*. A researcher may be authenticated by their campus yet only be
authorized once they appear as an active member in Registry. Membership
managed in the Registry feeds the identity and authorization data the
proxy ultimately releases to SPs.

## Attribute Authority (LDAP)

The Attribute Authority, backed by an LDAP directory, supplies the
**VO identity and authorization** attributes for a user at login time —
their collaboration-scoped identifiers, group memberships, and
entitlements.  It is the read-optimized source the gateway queries
while a login is in progress, reflecting the membership curated in the
Registry.

Consolidating these attributes in one authority means every protected
application receives the same, current view of a user's standing in the
collaboration, rather than each maintaining its own copy.

## Protected Applications (Service Providers)

Protected applications are the resources the collaboration shares —
the service providers that researchers ultimately want to reach.  They
delegate authentication and authorization entirely to the gateway.

An application never sees campus credentials and does not implement VO
membership logic.  It receives the **VO identity and authorization**
attributes the gateway releases and enforces access using those
attributes alone, which lets new applications join the collaboration
without integrating with each campus individually.

## How a login flows through CORTEX

The components combine into a single sign-on path:

1. A researcher visits a **protected application**, which redirects the
   login to the **Federation Gateway**.
2. The **Discovery Service** helps the user pick their home
   institution, and the gateway forwards the request to the matching
   **campus identity provider**.
3. The campus IdP authenticates the user and returns a **campus
   identity** to the gateway.
4. The gateway resolves the user's collaboration membership — enrolled
   in the **Registry** and served through the **Attribute Authority** —
   into **VO identity and authorization** attributes.
5. The gateway releases those attributes to the protected application,
   which grants access accordingly.

:::{admonition} Guidance
:class: important

Protected applications **MUST** delegate authentication and
authorization to the Federation Gateway and **MUST NOT** trust campus
identity providers directly.

:::

Routing every login through the gateway is what preserves the proxy
model's guarantees.  It keeps trust relationships one-to-one, ensures
that VO membership and entitlements are applied uniformly, and prevents
an application from acting on a campus assertion that has not been
enriched with the collaboration's authorization context.