1. Introduction

A typical requirement in federated research infrastructures is to provide access to shell-based services using the federated identity (OpenId Connect-based), with SSH being the most prominent such service. Provisioning and deprovisioning of local accounts is necessary.

2. Goals

Develop a set of server- and client-side tools that that work with standard SSH software to enable SSH access with OIDC.

Server-side requirements:

  • No modification of SSH server
  • Integration with existing local user management systems
  • Flexible authorisation concept
  • No need for OIDC client registration on the server

Client-side requirements:

  • No modification of SSH client
  • No additional service credentials to remember
  • No need to enter passwords more than once after reboot

3. Architecture and Components

The main components to enable SSH with OIDC are:

  • motley_cue: a service for mapping OIDC identities to local identities.
  • pam-ssh-oidc: a Pluggable Authentication Module (PAM) that accepts OIDC Access Tokens for authenticating users.
  • mccli: an SSH client wrapper for connecting to an OIDC-enabled SSH server


The architecture of motley_cue consists of:

  • LUM interface: a generic and extensible module that acts as an interface to the local user management and handles all the operations related to the life-cycle of the local accounts mapped to the federated identities. The plug-in architecture allows for the
    integration of any existing user management system, with the following being supported at the moment:
    • local UNIX accounts
    • LDAP
    • bwIDM.
  • Authorisation: an authorisation module for configuring access to resources based on federated authorisation models, such as membership in Virtual Organisations (VOs), levels of assurance, entitlements, or audience, with support for multiple identity providers.
  • REST API: a web-based interface for easy access to information about local accounts, as well as for performing operations on local accounts. Token-based authenticated APIs are available for federated users and admins.

4. Public Test Instance

KIT provides a public test instance for evaluation at https://ssh-oidc-demo.data.kit.edu/.

4.1. Client usage

On the client, two basic tools are needed:

  • oidc-agent: to obtain OIDC Access Tokens
  • mccli for:
    • getting Access Tokens
    • communicating with the remote motley-cue
    • calling SSH with an Access Token

For oidc-agent, follow installation instructions at https://indigo-dc.gitbook.io/oidc-agent/installation.


1. Generate an oidc-agent configuration

a) for example with EGI Checkin:

    oidc-gen --pub --iss https://aai.egi.eu/oidc \
        --scope "openid profile email offline_access \
        eduperson_entitlement eduperson_scoped_affiliation eduperson_unique_id" egi

b) or with google:

    oidc-gen --pub --issuer https://accounts.google.com/ --flow=device google


2. Install mccli:

pip install mccli

3. SSH into the public test instance with a simple command:

    mccli ssh ssh-oidc-demo.data.kit.edu --iss https://aai.egi.eu/oidc
    mccli ssh ssh-oidc-demo.data.kit.edu --iss https://accounts.google.com

This will create an account for you on the remote machine and log you into the remote host without any additional interaction.

More on configuring the source of the Access Token in mccli --help.


5. Server configuration

Packages are available at https://repo.data.kit.edu. Follow the instructions there to support the correct repository for apt or yum. Install the packages: motley-cue and pam-ssh-oidc-autoconfig.

You'll need to open a port for Nginx to listen on, and install host certificates.

You must configure who is allowed to use your service in /etc/motley_cue/motley_cue.conf.

You can support multiple OPs and configure authorisation for each OP separately. There are three options to authorise users from the supported OPs:

  • authorise all: allow all users from a trusted OP
  • individual: authorise single users via their unique identifier given by the OIDC sub claim
  • VO-based: authorise users that are members of a specific VO (or a set of VOs)

Local account creation is configured in `/etc/motley_cue/feudal_adapter.conf`. A default configuration is provided with the installed package. Pay close attention to the following options to change the default behaviour:

  • backend: how are the users managed locally (e.g. local UNIX accounts, LDAP, ...)
  • assurance: specifying minimum acceptable assurance (according to the REFEDS Assurance Framework)
  • username generator: how local usernames are generated for users (e.g. trying to honour incoming preferred username from the OP, or using pooled accounts with a custom prefix)

6. Resources

  • No labels