An **Actor** is a concept within the new Authentication subsystem to represent a unique identity / principal that is initiating actions (e.g. read & write requests)
on the platform.
An actor can be characterized by 2 attributes:
1.**Type**: The "type" of the actor making a request. The purpose is to for example distinguish between a "user" & "service" actor. Currently, the "user" actor type is the only one
formally supported.
2.**Id**: A unique identifier for the actor within DataHub. This is commonly known as a "principal" in other systems. In the case of users, this
represents a unique "username". This username is in turn used when converting from the "Actor" concept into a Metadata Entity Urn (e.g. CorpUserUrn).
For example, the root "datahub" super user would have the following attributes:
```
{
"type": "USER",
"id": "datahub"
}
```
Which is mapped to the CorpUser urn:
```
urn:li:corpuser:datahub
```
for Metadata retrieval.
## What is an Authenticator?
An **Authenticator** is a pluggable component inside the Metadata Service that is responsible for authenticating an inbound request provided context about the request (currently, the request headers).
Authentication boils down to successfully resolving an **Actor** to associate with the inbound request.
There can be many types of Authenticator. For example, there can be Authenticators that
- Verify the authenticity of access tokens (ie. issued by either DataHub itself or a 3rd-party IdP)
- Authenticate username / password credentials against a remote database (ie. LDAP)
- **DataHubSystemAuthenticator**: Verifies that inbound requests have originated from inside DataHub itself using a shared system identifier
and secret. This authenticator is always present.
- **DataHubTokenAuthenticator**: Verifies that inbound requests contain a DataHub-issued Access Token (discussed further in the "DataHub Access Token" section below) in their
'Authorization' header. This authenticator is required if Metadata Service Authentication is enabled.
- **DataHubGuestAuthenticator**: Verifies if guest authentication is enabled with a guest user configured and allows unauthenticated users to perform operations as the designated
guest user. By default, this Authenticator is disabled. If this is required, it needs to be explicitly enabled and requires a restart of the datahub GMS service.
The **AuthenticationExtractionFilter** is the foundation [servlet filter](http://tutorials.jenkov.com/java-servlets/servlet-filters.html) that runs for **every request** to the Metadata Service. Its single responsibility:
- **Extract Authentication Information**: Constructs and invokes an **AuthenticatorChain** to process credentials
- **Set Universal Context**: Always establishes an **AuthenticationContext** (see below) for every request
- **Never Enforce**: Never blocks requests - if authentication fails, it sets an anonymous context and continues
### Tier 2: Authentication Enforcement
The second tier consists of **enforcement mechanisms** that can be implemented in multiple ways:
#### AuthenticationEnforcementFilter
The default enforcement filter that:
- **Selective Processing**: Only processes endpoints requiring authentication (excludes paths like `/health`, `/config`)
- **Context-Based Decisions**: Reads the **AuthenticationContext** set by the extraction tier
- **Request Blocking**: Returns 401 unauthorized when authentication is required but not present
#### Additional Enforcement Options
The decoupled design enables flexible enforcement strategies:
- **Multiple Enforcement Filters**: Different areas can have specialized filters (e.g., admin area filter with additional privilege checks)
- **Controller-Level Enforcement**: Individual controllers can examine the **AuthenticationContext** and enforce their own rules
- **Custom Authorization Logic**: Business logic can make authentication decisions based on the established context
### Benefits of Two-Tier Architecture
This separation of concerns provides several advantages:
1.**Decoupled Responsibilities**: Authentication extraction is separate from enforcement decisions
2.**Performance**: Authentication processing happens once per request, regardless of enforcement complexity
3.**Flexibility**: Multiple enforcement strategies can coexist (filters, controllers, custom logic)
4.**Extensibility**: New enforcement mechanisms can be added without changing authentication extraction
5.**Consistency**: All parts of the system have access to the same authentication context
6.**Progressive Disclosure**: As a side benefit, endpoints can provide different responses based on user authentication status
## What is AuthenticationContext?
The **AuthenticationContext** is a thread-local storage mechanism that bridges the extraction and enforcement tiers. It serves as the **universal authentication state** for the entire request lifecycle:
- **Authentication Object**: Contains the result of the authentication extraction process (Actor + credentials)
- **Anonymous Support**: Set to anonymous actor when authentication extraction yields no valid credentials
- **Request Lifecycle**: Automatically established by the extraction tier and cleaned up after each request
- **Universal Access**: Available to all enforcement mechanisms - filters, controllers, or custom business logic
This context enables **consistent authentication decisions** across all parts of the system. Whether enforcement happens in a servlet filter, a controller method, or custom business logic, they all work with the same authentication information established during the extraction phase.
request to the Metadata Service to generate a SESSION token _on behalf of_ of the user logging in. (\*Only the frontend service is authorized to perform this action).
