1. Introduction

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:

1. Summary of Requirements and Use Cases for a Campus IdP platform

2. Functionality to be provided to clients connecting to the platform server

3. Campus IdP administrator usage workflow

4. Federation operator usage workflow

5. Integration mechanisms to existing components (Metadata registry, FaaS)

6. Specific architectural components, their role and interplay overall

1. Client

2. Server

3. Docker container layer and repository

4. Openstack platform integration

1.2. Scope

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

1. Create/Store all required IdP configuration including metadata certificates

2. Display and update of IdP metadata via GUI (e.g.: Jagger)

3. Provide easy configuration options for relevant IdP config features (e.g: Attribute Release Policy as in Jagger).

IdP Configuration

1. Provide IdP configuration required to spawn a new instance

2. Generation of IdP metadata files, to be shipped to the IdP instance on the Cloud for its configuration

3. Management of IdP configuration via  API service

4. Management of configuration changes to update the running config on managed IdP instances

Spawning of new Campus IdP instances

1. Spawning/Managing new IdP instances on a Virtual Machine accessed via ssh

2. Spawning/Managing new IdP instances on Docker containers on a Docker-Engine node

Monitoring

1. Deploy on the IdP instances plugins towards Monitoring tools to track the status of the instances

Statistics

1. 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:

1. Request the creation or removal of a new IdP for her/his Home Organization

2. Provide all required configuration via GUI (Web Client) to allow the spawning of a customized(branded) IdP for her/his HO :

1. FQDN ( our domain / her domain )

2. Metadata Provider

3. Attribute Release Policy/Attribute Filter   [ “Jagger” ]

1. Entity Category checkbox   [ “Jagger” ]

4. Attribute Resolver   

5. Host certificates (https/ssl)

6. Key rollover

7. Data Connectors  ( IdM )

8. LDAP

9. Basic customization (logo,  IdP login page)

3. 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

1. Metadata Provider

2. Attribute Release Policy/Attribute Filter   [ “Jagger” ]

3. Entity Category checkbox   [ “Jagger” ]

4. Attribute Resolver   

5. Host certificates (https/ssl)

6. Key rollover

7. Data Connectors  ( IdM )

4. Manage the IdM directory - if included in the deployment of the IdP - (e.g.: LDAPAdmin)

1. With access control based on source IP address

5. Access usage statistics for the IdP  (e.g.: top peering SPs, ..)

6. Access the IdP log files [ e.g.: access to an external SP providing ]

7. Request the delegation of administrative rights to other users identified via their federated credentials

8. 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

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.

1. The web client provides an easy to use GUI to HO Admins, who provide all information necessary to configure an IdP.

2. The configuration is send to the API server, which converts them and stores it into the IdP configuration database.

3. 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.

4. 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.

        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

1. Home Organization Administrator

1. HO Admin opens the web client and fills out the user registration form

2. ...

3. HO waits until his user account is approved by an federation administrator

2. Federation Administrator

1. Fed Admin is notified about a new request

2. …

3. The request domain is added to the list of known organizations

Use Case: spawning of a new IdP on hosted VM

1. HO Site Admin  wants to create a new IdP - Contacts the Federation

2. “Paper interaction’ :  Paperwork / Use Policy / Data Request from Federation

3. She/He gathers all required information

1. Domain Name  → hostname → EntityID  etc (scope)

1. If it is our domain - no need for Site admin to provide certificates

2. If the IdP will be on HO’s domain, they (HO) need to get certificates

2. HO logos / Homepage / Description / Privacy Policy / Tech contacts

3. Display Name (optional)

4. 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, ...  )

4. Creation of the bare OpSys VM - for example  manually by NREN/Federation operators ( IP, DNS…)

1. [anything on the Cloud side]

2. Including ensuring SSH keys for Ansible are there

5. Federation operators give authorization to HO Admin to the API Client Web Application ( configured as a federation SP)

1. Via email with a token

2. Last resort IdP  [..]

3. Manual creation of local credentials..

6. 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 ]

1. “Spawn  your new IdP”     

2. “List your IdPs”        

3. “Remove your IdP” [?]

7.  - fills all required information (3)

8. [ 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

4.2 Virtualization

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

• Fast deployment

• Simplified maintenance

Disadvantages

• Containers cannot be migrated while executing

• Containers cannot replace VMs in some cases

4.1.2 Using VM instances

Image Added

5. Implementation

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.

5.1 Ansible

The core component is Ansible which should provide all required functionalities regardless of other components like an API service or translator.

https://github.com/GEANT/ansible-shibboleth

5.1.1 Code Validation

5.1.2 API Interface

Describe:

1. How we spawn the VM

2. How we fetch configuration information via the API server

3. How we execute the Ansible playbook from the API Server

4. How we test and validate the new instance

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.

https://github.com/GEANT/APICampusIdP

5.2.1 Schema

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.

5.2.2 Converter

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.

5.2.3 Interfaces

The API provides the following interfaces to client applications.

API_I01: Create IdP

Endpoint: BASE_URL/idp

Request:

Call: POST

Content: JSON

Content type: application/json

Payload:

Response:

API_I02: Update IdP

API_I03: Delete IdP

API_I04: Fetch IdP

Retrieve the configuration data of one particular IdP.

5.3 Docker

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

5.4 OpenStack

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.

5.5.1 Authentication

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

tbd

6. References

[R1]   https://goo.gl/mHY6CB   Initial Survey for NRENs on Cloud based IdP/Campus IdP: Results