Table of Contents
The following chapter describes the purpose and scope of this document.
1.1. Purpose of the Document
This Document provides the architectural outline of the Campus IdP platform. Different architectural view are used to illustrate different aspects of the system. The main goal is to describe the architecture of the GEANT Campus IdP platform highlighting:
Summary of Requirements and Use Cases for a Campus IdP platform
Functionality to be provided to clients connecting to the platform server
Campus IdP administrator usage workflow
Federation operator usage workflow
Integration mechanisms to existing components (Metadata registry, FaaS)
Specific architectural components, their role and interplay overall
Docker container layer and repository
Openstack platform integration
The scope of this document is the listing of the provided functionality and the definition of the architecture for a community Campus IdP platform developed by the Supporting Service for Campus Identity providers activity of Gn4.2 .
1.3. Definitions and Acronyms
Ansible API (API): The API handles client requests, stores configuration data and provides them to the Ansible backed using the config translator.
Translator (config translator) - responsible for converting information stored in API schema format to ansible variables
Web Application (WebApp) : The WebApp consists of all components needed for a working web based application, i.e. web client and server, API and database, IdP.
Web Client (Client): The web client describes the GUI application provided online to end users.
2. Requirements and Use Cases
The requirements from the GEANT community which are addressed by the Campus IdP platform emerged through a dedicated survey [R1] that was held at the beginning of the project activities, targeting European Home Organizations through their NRENs.
Among others, one of the noticeable outcomes of the survey is that many Home Organization lacking of manpower or skills to locally set up their own Identity Provider have high trust and confidence in their reference NREN to provide a Cloud based IdP for them.
In fact, half of the respondent Home Organizations answered they are interested in outsourcing the provisioning of the local IdP to a managed Service Provider, provided it is the National Identity Federation providing a solution within a compatible data protection environment.
This justifies the development of a Campus IdP platform aiming at supporting federations to be providers of cloud based offer on the Identity Provider.
Task 1 of JRA3 focused therefore its efforts in designing and implementing such a platform and this document describes the main features of the corresponding architecture and the provided functionality.
The platform aims at supporting both Federation Operators in their task of Cloud providers of the Shibboleth IdP, and Home Organization IdP administrators willing to spawn and manage the identity management features of their IdP.
Typical use cases for the Campus IdP platform are the following ones:
Spawn and manage new IdPs
Different use approaches: scripts stand-alone, integration on Cloud
3. Functionality provided by the Campus IdP Platform
The Campus IdP Platform aims at supporting both
National Identity Federations Operators, and
Individual Identity Provider Administrators from single Home Organizations
The provided functionality in the two cases is necessarily different, given this implies targeting Cloud providers (in the case of NRENs) and individual administrative users (in the case of IDP administrators from Home Organizations).
3.1 Functionality Provided to Federation (NREN) Operators
The Campus IdP Platform aims to providing Federation Operators (FedOps) a way to easily deploy and manage cloud-based Campus IdP for their Home Organizations: It integrates tools currently related to the operational workflow of federation operators, but belonging however to different functional domains (Metadata Management and Archiving, Cloud infrastructure, eased IdP configuration, Host Certificates, Software Repositories). The overall goal of GEANT providing a Campus IdP platform is to ease the daily life of FedOps by integrating in a unique system the Management and Archiving of Metadata, installation and configuration tools to spawn IdP instances on the Cloud, Monitoring probes, in a scalable and convenient fashion.
We deal here with the listing of the functionality which will be provided by the system to NREN operators to support their role of Campus IdP Cloud providers to Home Organizations, splitting it into 5 main categories: IdP Metadata Management, IdP Configuration, Spawning of new Campus IdP instances, Monitoring, Statistics (Campus IdP platform + Jagger).
IdP Metadata Management
Create/Store all required IdP configuration including metadata certificates
Display and update of IdP metadata via GUI (e.g.: Jagger)
Provide easy configuration options for relevant IdP config features (e.g: Attribute Release Policy as in Jagger).
Provide IdP configuration required to spawn a new instance
Generation of IdP metadata files, to be shipped to the IdP instance on the Cloud for its configuration
Management of IdP configuration via API service
Management of configuration changes to update the running config on managed IdP instances
Spawning of new Campus IdP instances
Spawning/Managing new IdP instances on a Virtual Machine accessed via ssh
Spawning/Managing new IdP instances on Docker containers on a Docker-Engine node
Deploy on the IdP instances plugins towards Monitoring tools to track the status of the instances
Provide statistics on session-related information: set of top peering Service Providers, Support
3.2 Functionality Provided to individual Identity Provider Administrators
Via the Campus IdP platform, administrators of individual Campus IdP at the Home Organization will be able to:
Request the creation or removal of a new IdP for her/his Home Organization
Provide all required configuration via GUI (Web Client) to allow the spawning of a customized(branded) IdP for her/his HO :
FQDN ( our domain / her domain )
Attribute Release Policy/Attribute Filter [ “Jagger” ]
Entity Category checkbox [ “Jagger” ]
Host certificates (https/ssl)
Data Connectors ( IdM )
Basic customization (logo, IdP login page)
Update the configuration of her/his IdP (e.g.: change the Attribute Filter, change the Metadata Provider…) via GUI and push it (apply it) to the IdP instance
Attribute Release Policy/Attribute Filter [ “Jagger” ]
Entity Category checkbox [ “Jagger” ]
Host certificates (https/ssl)
Data Connectors ( IdM )
Manage the IdM directory - if included in the deployment of the IdP - (e.g.: LDAPAdmin)
With access control based on source IP address
Access usage statistics for the IdP (e.g.: top peering SPs, ..)
Access the IdP log files [ e.g.: access to an external SP providing ]
Request the delegation of administrative rights to other users identified via their federated credentials
Roadmap: High Availability deployment option
4. Architecture of the Campus IdP platform
The Campus IdP platform is composed by a set of services acting in a complementary way to the Resource Registry, which is mainly devoted to metadata Management for the Federation managers and the IdP. Additional components are required to ensure the functionality mentioned in the above section 3.
The overall system architecture for the Campus IdP platform is shown by figure 1. It consists of the following high level elements, whose implementation is described in chapter 5.
Web Client: A web based GUI shown to end users
API: Middleware between client, data storage and IdP Factory.
Ressource Registry: Allows IdP metadata management and distribution
IdP Database: Stores IdP configuration in an abstract format
IdP Factory: Spawns and configures new IdP instances on a server
IdP Cloud: Environment that provides virtual servers to host an IdP
Figure 1: Architecture Overview Diagram
Figure 2: System Data Flow Diagram
The web client allows home organization administrators and federation operators to request the creation of a new IdP instance and input all required configuration information to let the Campus IdP platform spawn it in a virtual environment, as shown in figure 2.
The web client provides an easy to use GUI to HO Admins, who provide all information necessary to configure an IdP.
The configuration is send to the API server, which converts them and stores it into the IdP configuration database.
The Ansible server queries the API, fetches the configuration data for new or updated IdPs and spawns a new IdP in the cloud environment chosen.
The GUI shows information about the newly created IdP and provided management functionalities.
In order to use the Campus IdP platform, a user account is required. This account is initially created via the web application and stored within a dedicated IdP, because users don’t own a federated identity before they create their first IdP. Once a HO Admin has created his first own IdP, he is able to create a user account for himself there. Afterward he may link his newly created federated identity to the Campus IdP identity, which allows federated login via eduGAIN.
There are multiple reasons to keep this two user accounts separate:
It is easier to manage user accounts and approvals in the long term.
Campus IdP has control over its IdP it's easy to block malicious users.
In case of an configuration issue or deletion of the IdP, the HO Admin is still able to access the application to revert changes or create a new IdP.
If the IdP gets compromised, the HO Admin is still able to manage the configuration using the Campus IdP identity.
There can be multiple Admins for one organization without having permission issues
New HO Admins must be approved by a Federation Admin before their user account is activated, as shown in figure 3. The approval concept is not user driven, but organization based. An HO Admin proves that he belongs to an organization by having access to the web domain of this organization. This is validated by the web application by creating a challenge secret that has to be stored into the root directory of this domain. Once validated, the user request is forwarded to a federation administrator. He can decide if he directly approves the request because he trusts the domain or contacts the organisation first. Alternatively, the federation admin might pre-approve organizations by adding their trusted domain to the list of known HOs. This procedure is very flexible so that each federation may inject their own approval process where necessary. For example, a federation admin could add a trusted domain after receiving a signed contract from the corresponding organization. Doing this approves the user account of the HO Admin without the need to share some kind of temporary credentials or secrets to ensure that the registered user is really part of the organization that has just signed the contract. This concept is not only privacy preserving, it also shifts the responsibility of identity vetting to the organization itself.
Figure 3: User registration, approval and IdP creation schema
Add a DB on the server side - to store configuration - user ePPN
Need information flow also from Server to Client (Post Response) to
GET not needed (?)
Get status updates on outcome of Ansible deployments
One or many Ansible playbooks - for more organizations
Running Ansible in parallel - issue ( concurrent “Save” button pushings by different people)
If inventory changes while Ansible running ---> issues : to be prevented → Cron/Lock on server side (?) : solvable with 1 inventory per IDP instance : 1 inventory ←→ 1 IdP host
MetaData are created after Ansible is run the first time. Then MD travel back from Server to client [
API server will write the definitive MD or need more interactions
You prepare VM, come with default MD, [A7 35’]
4.1 Operational workflows
This section describes the used cases for the Campus IdP Platform.
Modelling Flows for
Registering a new user account
Spawning a new IdP
Updating an IdP configuration
Use Case: registering a new user account
Figure 4: User registration flow
Home Organization Administrator
HO Admin opens the web client and fills out the user registration form
HO waits until his user account is approved by an federation administrator
Fed Admin is notified about a new request
The request domain is added to the list of known organizations
Use Case: spawning of a new IdP on hosted VM
Figure 5: Create new IdP on spawned VM
HO Site Admin wants to create a new IdP - Contacts the Federation
“Paper interaction’ : Paperwork / Use Policy / Data Request from Federation
She/He gathers all required information
Domain Name → hostname → EntityID etc (scope)
If it is our domain - no need for Site admin to provide certificates
If the IdP will be on HO’s domain, they (HO) need to get certificates
Display Name (optional)
IdM system details ( LDAP: URI, protocol (TLS..), filter to search for users, principle attribute name, principal user (uid, email, ….) , returned attributes, bind DN, password, schema enforcement options eduPerson, SCHAC, EC R&S, EC CoCo, ... )
Creation of the bare OpSys VM - for example manually by NREN/Federation operators ( IP, DNS…)
[anything on the Cloud side]
Including ensuring SSH keys for Ansible are there
Federation operators give authorization to HO Admin to the API Client Web Application ( configured as a federation SP)
Via email with a token
Last resort IdP [..]
Manual creation of local credentials..
HO Site admins access WA client : Available options (“buttons”) [ After your first IdP is spawned you can link your Client WebApp account to your ePPN ]
“Spawn your new IdP”
“List your IdPs”
“Remove your IdP” [?]
- fills all required information (3)
[ First time you log in to the SP-protected side [IdP management Web Application form] of the Client WebApplication you link your token to your current eppN ---> enable option 6.b
Use Case: Updating an IdP configuration
TODO: Describe use case
TODO: Describe the overall concept of virtualization. Explain the technical details in the corresponding (Docker, OpenStack, VM)) section in chapter 5 Implementation.
4.1.1 Using docker containers
The main advantages using docker containers are:
Portability across machines
Containers cannot be migrated while executing
Containers cannot replace VMs in some cases
Figure 6: Docker Architecture Overview
4.1.2 Using VM instances
In this section we describe into more detail the functionality which will be provided by the individual components of the GEANT Campus IdP platform and how they are implemented.
The core component is Ansible which should provide all required functionalities regardless of other components like an API service or translator.
5.1.1 Code Validation
5.1.2 API Interface
How we spawn the VM
How we fetch configuration information via the API server
How we execute the Ansible playbook from the API Server
How we test and validate the new instance
Figure X: Fetch configuration files from API server
5.2 API Service
It’s an optional component. The api service will be responsible for providing and receiving IdP configuration in an abstract form from and to an API client.
The API is a server application able to communicate with additional applications in the Campus IdP environment. From the perspective of the web client, the API is just a web service providing a stateless REST API.
The goal is to describe IdP configuration in more abstract way independently from IdP version and ansible. If IdP software changes then in most cases only changes in Ansible playbook and Translator.
It's responsible for transforming data between ansible variables and json and schema. The tool can either be a part of ansible, an API service or a standalone script. As an input it will accept string, local file or remote location. It allows greater flexibility in chosen scenario.
The API provides the following interfaces to client applications.
API_I01: Create IdP
Content type: application/json
No (leave empty)
Yes, may be empty
$RSA_PUB + $RSA
The request was successful and will be processed.
message: "request received"
The provided hostname is already in use.
message: “host already exist”
API_I02: Update IdP
API_I03: Delete IdP
API_I04: Fetch IdP
Retrieve the configuration data of one particular IdP.
TODO: Explain the docker approach
5.3.1 Creation of Docker Image for Shib IdP 3.3.0+ and Container
5.3.2 Integration of Docker and Openstack environments
TODO: Describe the OpenStack environment
5.5 Web Client
The web client provides a graphical user interface via a users web browser to access the backend functionalities of Campus IdP. It provides an interface to the API and facilitates federated login via eduGAIN.
Technically the web client is just a Single-Page-Application (SPA), meaning that the user has always access to the entire application. For this reason, authentication and authorization is handled completely on the server side.
5.5.2 User registration
The API functionalities are only accessible by authorized users. Therefore, each user needs an Campus IdP account and has to authenticate first. User that are not yet registered may access only the public section of the web client, which provides a form to create a new user account.
5.5.3 IdP Creation
The client provides an easy to use web form to create an IdP.
This functionality requires the API interface API_I01.
5.5.4 IdP Management
HO Admins are able to manage their formerly requested IdPs via the web client. The following functionalities are provided:
Alter IdP configuration [API_I02]
Change cryptographic keys [API_I02]
Delete an IdP [API_I03]
Clone an IdP [API_I01]
For security reasons, it is not possible to retrieve stored private keys from the configuration database.
This functionality requires the API interface API_I04.
5.5.5 Federation Management
[R1] https://goo.gl/mHY6CB Initial Survey for NRENs on Cloud based IdP/Campus IdP: Results