A fence separates protected resources from the outside world and allows
only trusted entities to enter.
Fence is a core service of the Gen3 stack that has multiple capabilities:
- Act as an auth broker to integrate with one or more IdPs and provide downstream authentication and authorization for Gen3 services.
- Manage tokens.
- Act as an OIDC provider to support external applications to use Gen3 services.
- Issue short-lived, cloud native credentials to access data in various cloud storage services
Fence can be configured to support different Identity Providers (IdPs) for AuthN. At the moment, supported IDPs include:
- Shibboleth
- NIH iTrust
- InCommon
- eduGAIN
- CILogon
- Cognito
- Synapse
- Microsoft
- ORCID
- RAS
OpenAPI documentation available here.
YAML file for the OpenAPI documentation is found in the openapis folder (in
the root directory); see the README in that folder for more details.
Fence acts as a central broker that supports multiple IdPs.
At the same time, it acts as an IdP itself.
In that sense, fence is both an RP and an OP.
Example:
- Google IAM is the OpenID Provider (OP)
- Fence is the Relying Party (RP)
- Google Calendar API is the resource provider
- Fence is the OpenID Provider (OP)
- A third-party application is the Relying Party (RP)
- Gen3 microservices (e.g.
sheepdog) are resource providers
Note that the 3rd Party App acts as the RP in these examples.
In the following flow, Fence and the IdP together constitute an OP.
Fence, by itself, acts as an OAuth 2.0 Auth Server; the IdP enables the additional implementation of OIDC (by providing AuthN). From an OIDC viewpoint, therefore, Fence and the IdP can be abstracted into one OP.
If the third-party application doesn't need to use any Gen3 resources (and just
wants to authenticate the user), they can just get
needed information in the ID token after the handshake is finished .
If a third-party application wants to use Gen3 resources like
fence/sheepdog/peregrine, they call those services with an Access Token
passed in an Authorization header.
In the following flow, 3rd Party App is the RP; Protected Endpoint is an endpoint of a Gen3 Resource (the microservice), and both of these are part of a resource server; and Fence is the OP. Here, importantly, Fence may be interfacing with another IdP or with another Fence instance in order to implement the OIDC layer. Either way, note that the Fence blob in this diagram actually abstracts Fence in concert with some IdP, which may or may not also be (a different instance of) Fence.
The following diagram illustrates the case in which one fence instance uses another fence instance as its identity provider.
A use case for this is when we set up a fence instance that uses NIH login as the IdP. Here, we go through a detailed approval process in NIH. Therefore, we would like to do it only once for a single lead Fence instance, and then allow other fence instances to simply redirect to use the lead Fence as an IdP for logging in via NIH.
In the following flow, Fence (Client Instance) is an OP relative to OAuth Client, but an RP relative to Fence (IDP).
See the OIDC specification for more details. Additionally, see the OAuth2 specification.
Whereas pre-signed URL is a cloud-agnostic solution, services and tools on Google Cloud Platform prefer to use Google's concept of a "Service Account". Because of that, Fence provides a few more methods to access data in Google.
See Fence and Google for more details on data access methods specific to Google.
See detailed explanation here