Fence

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:

1. Act as an auth broker to integrate with one or more IdPs and provide downstream authentication and authorization for Gen3 services.
2. Manage tokens.
3. Act as an OIDC provider to support external applications to use Gen3 services.
4. Issue short-lived, cloud native credentials to access data in various cloud storage services

Overview

Identity Providers

Fence can be configured to support different Identity Providers (IdPs) for AuthN. At the moment, supported IDPs include:

• Google
• Shibboleth
  • NIH iTrust
  • InCommon
  • eduGAIN
• CILogon
• Cognito
• Synapse
• Microsoft
• ORCID
• RAS

API Documentation

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.

OIDC & OAuth2

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.

Fence as RP

Example:

• Google IAM is the OpenID Provider (OP)
• Fence is the Relying Party (RP)
• Google Calendar API is the resource provider

Fence as OP

• Fence is the OpenID Provider (OP)
• A third-party application is the Relying Party (RP)
• Gen3 microservices (e.g. sheepdog) are resource providers

Example Flows

Note that the 3rd Party App acts as the RP in these examples.

Flow: Client Registration

Flow: OpenID Connect

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 .

Flow: Using Tokens for Access

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.

Flow: Refresh Token Use

Flow: Refresh Token Use (Token is Expired)

Flow: Multi-Tenant 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).

Notes

See the OIDC specification for more details. Additionally, see the OAuth2 specification.

Google Cloud Storage

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.

Setup

See detailed explanation here

Additional documentation

1. Terminologies
2. Accessing Data
3. user.yaml guide
4. Token management
5. fence-create
6. Default expiration times