Skip to content

OpenAthens Keystone Architecture

Overview

This document explains how OpenAthens Keystone integrates with Auth0 to provide multi-federation access for Statista users.

What is OpenAthens Keystone?

OpenAthens Keystone is a SAML-to-OIDC gateway. It allows service providers to connect to federated identity systems (like OpenAthens) using OIDC — a protocol that Auth0 supports natively.

With Keystone:

  • Only one connection is needed between Keystone and Auth0.
  • Supports many federated OpenAthens institutions without reconfiguration.
  • OpenAthens manages the federation metadata.
  • In our setup, Keystone acts as the bridge between various federated identity sources and our authentication layer, Auth0.

Architecture Overview

Users (from multiple federations)
       ↓
  OpenAthens Keystone
       ↓
     Auth0
       ↓
    Statista

The architecture follows a simple chain:

  1. Users from various institutions authenticate through their federated identity providers
  2. OpenAthens Keystone acts as a gateway, converting SAML assertions to OIDC tokens
  3. Auth0 receives the OIDC authentication and manages the user session
  4. Statista receives authenticated users with proper authorization

Identifying User Access by Domain

Since all federated users authenticate through a single SAML entry point in Auth0, we need a reliable way to determine which group or organization a user belongs to. This is essential for ensuring correct authorization and access control across our platform.

To solve this, we implemented a custom mechanism based on domain extraction.

How It Works

  1. OpenAthens Scope Parsing

    We rely on the eduPersonScopedAffiliation attribute provided by OpenAthens. This field typically contains values like:

    member@university.edu
student@university.edu

    These values represent the user's roles, scoped to their organization domain.

  2. Extracting the Domain

    In a post-login Action in Auth0 (maybe_insert_user_to_legacy_db.js), we parse the domain part from eduPersonScopedAffiliation value (e.g., university.edu) to identify the user's organization.

  3. User Lookup via Internal API

    We then call platform-sso-services using the endpoint: GET /users/get-by-domain which receives the parsed domain and returns user if it's found.

    The lookup is done against a JSON file that contains mappings of domains to user groups. There are three files depending on each environment. These are located here: https://github.com/CPE-Orga/platform-sso-services/tree/main/data

  4. Access Control Decision
    Based on the API response, we determine whether the user has access and associate them with the appropriate group account.

Why This Approach?

This domain-based logic allows centralized handling of users from many federations without requiring separate entry points or Auth0 applications. Multiple affiliations (e.g., member@..., staff@...) can be present; we use the domain from the first entry for consistency.

By extracting the domain and mapping it to known organizations, we can:

  • Maintain a single Auth0 connection for all OpenAthens federated users
  • Dynamically determine user permissions based on their institution
  • Scale to support many institutions without Auth0 configuration changes
  • Centralize the institution-to-account mapping in version-controlled JSON files

This architecture provides flexibility and maintainability while keeping the authentication flow simple for end users.

Last updated: March 24, 2026 at 10:39
By: Axel Tetzlaff