├── README.md
├── configuration.md
├── faq.md
├── installation.md
├── motley-cue.md
└── pam-ssh-oidc.md


/README.md:
--------------------------------------------------------------------------------
  1 | # What is ssh-oidc
  2 | 
  3 | It's a set of tools that allows (you guessed it) ssh with OIDC. What you
  4 | might not have guessed: We go for the difficult-to-implement but
  5 | simplest-to-use approach.
  6 | 
  7 | ## Usability
  8 | 
  9 | - No modification of ssh-client (except for Windows where we provide an extension to putty)
 10 | - No modification of ssh-server
 11 | - No need for OIDC client registration on the server
 12 | - No need to enter passwords more than once after reboot
 13 | 
 14 | The final usage is as simple as:
 15 | ```
 16 | mccli ssh <hostname>
 17 | ```
 18 | 
 19 | <!--## Features-->
 20 | <!--The tools the we use and describe in this context will offer many-->
 21 | <!--features.-->
 22 | <!---->
 23 | <!--- The PAM MODULE **pam-ssh-oidc** allows ssh to accept Access Tokens in-->
 24 | <!--    addition to passwords.-->
 25 | <!--- The Mapping Daemon **motley-cue** is an additional daemon on the ssh-->
 26 | <!--    server. It is in charge of "the magic behind the scenes" and deserves-->
 27 | <!--    special attention by the ssh server administrators! It is in charge of-->
 28 | <!--    several tasks:-->
 29 | <!--    - Authorisation Decision: Is an incoming user welcome on the system or-->
 30 | <!--        not. `motley-cue` offers **two dimensions** for making this decision:-->
 31 | <!--        - **Membership**: -->
 32 | <!--            - Memebership in a *Virtual Organisation* (a-->
 33 | <!--                group managed remotely, e.g. on an OIDC Provider). A system-->
 34 | <!--                administrator essentially delegates the decision which users-->
 35 | <!--                may log in to the system to the administrator of the Virtual-->
 36 | <!--                Organisation.-->
 37 | <!--            - *Individual Users*: Of course, it is also possible to authorise-->
 38 | <!--                individual users (just as before). However, now users are-->
 39 | <!--                identified by the OIDC `sub` and `iss` claims.-->
 40 | <!--        - **Assuranc**: The second dimension is based on **how well a user-->
 41 | <!--            is known**. We use the [Refeds Assurance-->
 42 | <!--            Framework](https://refeds.org/assurance) to describe a user.-->
 43 | <!--            -->
 44 | <!--        This allows to only give logins to users that are in a-->
 45 | <!--        specific group AND have a certain level of assurance.-->
 46 | <!--- A commandline tool **oidc-agent** that provides the functions for-->
 47 | <!--`ssh-agent` but for ssh.-->
 48 | <!--- A commandline wrapper **mcc-ssh** that -->
 49 | <!--    - gets you an AccessToken-->
 50 | <!--    - gets you an account on the remote (talks with `motley-cue`)-->
 51 | <!--    - calls ssh and passes the AccessToken-->
 52 | 
 53 | 
 54 | # Client Installation
 55 | 
 56 | **For testing the client, we provide a demonstration server at
 57 | [ssh-oidc-demo](https://ssh-oidc-demo.data.kit.edu) server**
 58 | 
 59 | 
 60 | On the client you will need two basic tools:
 61 | 
 62 | - oidc-agent: To obtain oidc AccessTokens
 63 | - motley-cue command-line tool (`mccli`) for
 64 |     - getting AccessTokens
 65 |     - communicating with the remote motley-cue
 66 |     - Calling SSH with an AccessToken
 67 | 
 68 | 
 69 | ## oidc-agent
 70 | Please follow installation instructions at
 71 | [https://indigo-dc.gitbook.io/oidc-agent/intro](https://indigo-dc.gitbook.io/oidc-agent/intro)
 72 | 
 73 | Useful commandlines for generating an oidc-agent configuration are listed
 74 | here. (You may add `--flow device` if you run oidc-agent on a remote
 75 | host.)
 76 | 
 77 | - **EGI Check-in**:
 78 |     ```
 79 |     oidc-gen --pub --iss https://aai.egi.eu/auth/realms/egi \
 80 |         --scope "openid profile email offline_access \
 81 |             eduperson_entitlement eduperson_scoped_affiliation eduperson_unique_id" egi
 82 |     ```
 83 | - **WLCG**: 
 84 |     ```
 85 |     oidc-gen --pub  --issuer https://wlcg.cloud.cnaf.infn.it/ \
 86 |         --scope "openid profile offline_access wlcg.groups wlcg \
 87 |             eduperson_entitlement eduperson_scoped_affiliation " wlcg
 88 |     ```
 89 | - **Helmholtz-AAI**: 
 90 |     ```
 91 |     oidc-gen --pub --iss https://login.helmholtz.de/oauth2/ \
 92 |         --scope "openid profile email offline_access \
 93 |             eduperson_entitlement eduperson_scoped_affiliation eduperson_unique_id" helmholtz
 94 |     ```
 95 | - **Google**: 
 96 |     ```
 97 |     oidc-gen --pub --iss https://accounts.google.com/ --flow device  --scope max google
 98 |     ```
 99 | 
100 | <!--
101 | oidc agent is available as packages via [https://repo.data.kit.edu](https://repo.data.kit.edu)
102 | 
103 | Follow the instructions there to support the correct repository for apt or yum.
104 | 
105 | The currently supported Linuxes are:
106 | - Debian (stable + testing)
107 | - Ubuntu (20.04 + 18.04)
108 | - Centos (7 + 8)
109 | 
110 | Install with either of:
111 | - `apt-get install oidc-agent`
112 | - `yum install oidc-agent`
113 | 
114 | For any other Linux distributions, you will have to [install from source](https://indigo-dc.gitbook.io/oidc-agent/installation/install#from-source).
115 | 
116 | For MacOS, follow the instructions at [https://indigo-dc.gitbook.io/oidc-agent/macos/installation](https://indigo-dc.gitbook.io/oidc-agent/macos/installation).
117 |     
118 | You will need to create an oidc-agent configuration. The shortest commandline for this is:
119 | ` oidc-gen --pub --issuer https://aai.egi.eu/oidc --scope "openid profile email offline_access eduperson_entitlement eduperson_scoped_affiliation eduperson_unique_id" egi`
120 | 
121 | For more information there is a [gitbook](https://indigo-dc.gitbooks.io/oidc-agent) and the
122 | [github](https://github.com/indigo-dc/oidc-agent) page.
123 | -->
124 | 
125 | ## mccli
126 | 
127 | Install with
128 | 
129 | - `pip install mccli`
130 | 
131 | Use either of:
132 | 
133 | - `mccli ssh ssh-oidc-demo.data.kit.edu --iss https://aai.egi.eu/oidc`
134 | - `mccli ssh ssh-oidc-demo.data.kit.edu --oidc egi`
135 | - `ACCESS_TOKEN=<access_token> mccli ssh ssh-oidc-demo.data.kit.edu`
136 | 
137 | It is as simple as this!
138 | 
139 | 
140 | # Server Installation
141 | 
142 | Installation is mostly a matter of installing the packages:
143 | - `motley-cue` and `pam-ssh-oidc` (or `pam-ssh-oidc-autoconfig`)
144 | 
145 | Packages are available at [https://repo.data.kit.edu](https://repo.data.kit.edu)
146 | 
147 | Follow the instructions there to support the correct repository for apt or yum.
148 | 
149 | The currently supported Linuxes are:
150 | - Debian (testing + stable + oldstable)
151 | - Ubuntu (22.04 + 20.04 + 18.04)
152 | - Centos (7 + 8 + Stream)
153 | - Rockylinux (8.5)
154 | - OpenSuse (15.4, 15.5)
155 | 
156 | 
157 | Details are described in the linked chapters
158 | [pam-ssh-oidc](pam-ssh-oidc.md) and [motley-cue](motley-cue.md)
159 | 
160 | # Frequently Asked Questions
161 | 
162 | Are collected in our [FAQ](faq.md).
163 | 
164 | # More Material
165 | 
166 | The public demo instance runs at ssh-oidc-demo.data.kit.edu. Further
167 | documentation is available there (<https://ssh-oidc-demo.data.kit.edu>)
168 | 
169 | - [Installation overview](installation.md)
170 | - [Configuration overview](configuration.md)
171 | 
172 | We have two presentations:
173 | - The (short) overview: [https://docs.google.com/presentation/d/18GVVwuf3Ham0PBdnVf2MJm96PUPGBU_zzglfskG9LtY](https://docs.google.com/presentation/d/18GVVwuf3Ham0PBdnVf2MJm96PUPGBU_zzglfskG9LtY)
174 | - The detailed one: [https://docs.google.com/presentation/d/17HM11YjafC5VA4_o2EjNrtbRqJGgQP0q92C_uqFAM6A/edit?usp=sharing](https://docs.google.com/presentation/d/17HM11YjafC5VA4_o2EjNrtbRqJGgQP0q92C_uqFAM6A/edit?usp=sharing)
175 | 
176 | # Acknowledgements
177 | 
178 | This page documents a set of tools that have been developed in a joint
179 | effort of:
180 | - Karlsruhe Institute of Technology (KIT)
181 | - Poznan Supercomputing and Networking Centre (PSNC)
182 | - EOSC-Synergy
183 | - Praceclab PL
184 | - Helmholtz Federated IT Services (HIFIS)
185 | - Helmholtz Data Federation
186 | 


--------------------------------------------------------------------------------
/configuration.md:
--------------------------------------------------------------------------------
 1 | ## Configuration
 2 | 
 3 | Configuration is only required on the server side.
 4 | The system is configured via the following configuration files.
 5 | (`oidc-agent` is considered out of scope for this documentation.)
 6 | 
 7 | ### `/etc/pam.d/sshd`
 8 | 
 9 | A single line in the beginning of `/etc/pam.d/sshd` is sufficient to
10 | enable `pam-ssh-oidc`:
11 | ```config
12 | auth   sufficient pam_oidc_token.so config=/etc/pam.d/pam-ssh-oidc-config.ini
13 | ```
14 | This line is automatically added when using the `pam-ssh-oidc-autoconfig`
15 | package.
16 | 
17 | ### `/etc/ssh/sshd_config`
18 | 
19 | SSHD should be configured to accept `KbdInteractiveAuthentication`
20 | (previously `ChallengeResponseAuthentication`):
21 | 
22 | ```config
23 | ChallengeResponseAuthentication yes
24 | KbdInteractiveAuthentication yes
25 | ```
26 | 
27 | ### `/etc/motley-cue/motley-cue.conf`
28 | 
29 | Here we configure several different aspects:
30 | 
31 | - Which OPs do we trust
32 | - Authorisation:
33 |     - Which Virtual Organisations do we support
34 |     - Which individual users do we support
35 | - The privacy statement to display
36 | - Auhorised security staff
37 | 
38 | The default self-documenting configuration file is shipped with the
39 | `motley-cue` installation.
40 | 
41 | ### `/etc/motley-cue/feudal.conf`
42 | 
43 | Feudal adapter is the plugin-based tool that implements user provisioning.
44 | Aspects that are configured here include:
45 | 
46 | - Minimally required levels of assurances
47 | - How to map remote users to local unix accounts
48 | - How to map VO-memberships to local unix groups
49 | - Which backend to use
50 | 
51 | Again, the configuration file shipped with the `motley-cue` installation
52 | is self explanatory.
53 | 


--------------------------------------------------------------------------------
/faq.md:
--------------------------------------------------------------------------------
 1 | # Frequently Asked Questions
 2 | 
 3 | ## Client
 4 | 
 5 | 1. My login does not work / I'm prompted with `Password: `
 6 |     - This is probably due to your Access Token being too long.  Access
 7 |         Tokens that exceed a length of 1023 characters cannot be processed
 8 |         by ssh.  To find out about the length of your Access Token, run:
 9 | 
10 |     `oidc-token | wc -c`
11 | 
12 | 1. `oidc-agent` seems to hang.
13 |     - This is due to a bug in libcjson, and should not appear any longer.
14 |         It was fixed in oidc-agent 4.1.0-4 (and 4.1.0-5 for ubuntu 20). 
15 |     - Contact [oidc-agent-contact@lists.kit.edu](oidc-agent-contact@lists.kit.edu)
16 | 
17 | 1. I cannot run `mccli` after installing it via `pip` (or `pip3`).
18 |     - This may be due to `$HOME/.local/bin` not being in your `$PATH`.
19 |     - Try `export PATH=$PATH:$HOME/.local/bin` to fix it.
20 | 
21 | 1. After running first time I get: 
22 |     `error: Could not infer motley_cue endpoint from command`
23 |     - Try updating mccli with: `pip install -U mccli`
24 |     - Try adding `--mc-endpoint https://<hostname>:8443` to the mccli command
25 |     - Try adding `--mc-endpoint http://<hostname>:8080` to the mccli command
26 |     - Ask a service administrator whether `motley_cue` runs on a non-standard port
27 | 
28 | 1. I get an error that I am not authorised:
29 |     `error: Failed on get_status: [HTTP 403] "Forbidden: you are not authorised to access this service"`
30 |     - Check if your token issuer is supported on the service:
31 |     
32 |         `mccli --oidc <oidc-agent account name> info <hostname>`
33 |     - In the command output, check that the issuer URL appears in the list of `supported OPs`.
34 |     - Look at the information in the section: `Authorisation on service for provided token issuer (OP)`.
35 |         - If the authorisation is VO-based, make sure you are a member of an authorised VO: the section `Information retrieved from userinfo endpoint` in the output of the command above.
36 |         - In the case of individual user authorisation, contact the service administrator. 
37 | 
38 | ## Server
39 | 
40 | 1. No matter which token I use, I get an error that I am not authorised:
41 |     `error: Failed on get_status: [HTTP 403] "Forbidden: you are not authorised to access this service"`
42 |     - no users are authorised by default, you first have to configure the authorisation in `/etc/motley_cue/motley_cue.conf`
43 |     - the config file is quite verbose and lists all the available features with examples; or check out the docs on authorisation [here](motley-cue.md#authorisation-configuration).
44 | 
45 | 1. I configured authorisation for my preferred issuer but I'm still not authorised.
46 |     - make sure that you don't have any leading spaces for any options configured in `motley_cue.conf` (e.g. `authorised_vos`) 
47 |     - the .ini file format used by `motley_cue.conf` interprets leading spaces as a line continuation of the previous option. 
48 | 
49 | 1. Is it mandatory to use host certificates and run `motley-cue` on port 443?
50 |     - no, by default `motley-cue` actually runs on port 8080
51 |     - it is RECOMMENDED to use a host certificate, but `mccli` will work without it as well and only issue a warning that your connection is insecure
52 |     - you can configure `motley_cue` to run on any port you'd like in the nginx configuration:
53 |         - `/etc/nginx/sites-available/nginx.motley_cue` (on debian-based systems) or
54 |         - `/etc/nginx/conf.d/nginx.motley_cue.conf` (on RPM-based systems)
55 |     - the recommended ports are 443 or 8443 for HTTPS and 8080 for HTTP; otherwise, inform the users if you use non-standard ports so that they can pass `--mc-endpoint <motley_cue URL>` to `mccli`.
56 | 
57 | 1. Can I use self-signed certificates?
58 |     - Please don't. Obtaining a certificate via [Let's Encrypt](https://letsencrypt.org/) is really easy to set up.
59 |     - If you still want to do this, for testing purposes, you can tell `mccli` to ignore the certificate verification via `--insecure`.
60 | 
61 | 1. I get this error message: `error: Failed on deploy: [HTTP 403] [state=rejected] Your assurance level is insufficient to access this resource`
62 |     - assurance is controlled in `/etc/motley_cue/feudal_adapter.conf`
63 |     - you can disable it by adding (in the `[assurance]` section): `skip = Yes, do as I say!`
64 |     - more details on how to configure it [here](motley-cue.md#assurance-configuration).
65 | 


--------------------------------------------------------------------------------
/installation.md:
--------------------------------------------------------------------------------
 1 | ## Installation
 2 | 
 3 | We provide packages for a large set of linux distribution (Debian, Ubuntu,
 4 | Centos, Rockylinux, OpenSuSE, Archlinux, ...) for client and server packages.
 5 | 
 6 | MacOS and Windows are additionally supported with client packages.
 7 | 
 8 | All packages (except MacOS currently) are available via
 9 | <https://repo.data.kit.edu>
10 | 
11 | The (optional) client-side packages (`oidc-agent` and `mccli`) are
12 | additionally part of most Debian-, and Arch- based distributions
13 | (`oidc-agent`) or easily installable via `pip install` (`mccli`).
14 | 


--------------------------------------------------------------------------------
/motley-cue.md:
--------------------------------------------------------------------------------
 1 | # Mapper (`motley-cue`)
 2 | 
 3 | Depending on your distribution, install with either:
 4 | - `apt-get install motley-cue`
 5 | - `yum install motley-cue`
 6 | - `zypper install motley-cue`
 7 | 
 8 | This will pull a couple of dependencies, most notably `nginx` (for which
 9 | epel-release is required on centos7). You SHOULD
10 | get a host-certificate for your server and enable https in nginx. This is
11 | not part of this documentation. 
12 | 
13 | ## Host Configuration
14 | 
15 | - Open your firewall on port 8080
16 | - **OR** install a host certificate with `nginx` and open your firewall on port 443
17 | 
18 | - Notes on selinux (for centos7 and centos8):
19 |     - We tested `pam-ssh-oidc` and `motley-cue` in permissive mode only.
20 |     - We succeeded in running in enforced mode, by using these commands:
21 |         ```config
22 |         semodule -i /usr/share/motley-cue/selinux/motley-cue-gunicorn.pp
23 |         semodule -i /usr/share/motley-cue/selinux/motley-cue-sshd.pp
24 |         semodule -i /usr/share/motley-cue/selinux/motley-cue-nginx.pp
25 |         setsebool -P nis_enabled 1
26 |         ```
27 |     - Feedback is appreciated
28 | 
29 | ## motley-cue configuration
30 | 
31 | Configuration of `motley-cue` takes place in `/etc/motley-cue`:
32 | - **`motley_cue.conf`: Authorisation configuration**: Allows definition of the Virtual Organisation (or groups) that are allowed to use the service.
33 | - **`feudal_adapter.conf`: Account creation configuration**: Allows among others to configure the account creation, including the levels of assurance.
34 | 
35 | Additional configuration:
36 | - **`/etc/nginx/sites-enabled/nginx.motley_cue`: NGINX configuration**: web-server specific configurations, such as ports or host certificates.
37 | 
38 | ## Assurance Configuration
39 | The config file is self documenting. Even more information
40 | may be found [here](https://git.scc.kit.edu/feudal/feudalAdapterLdf).
41 | By default from the motley-cue package, the following defaults are
42 | set:
43 | - Username creation: 
44 |     - Try to respect incoming `preferred_username`
45 |     - If not iterate over combinations of first and last name
46 | - Assurance:
47 | ```
48 | require = profile/espresso |
49 |     IAP/medium & ID/eppn-unique-no-reassign |
50 |     IAP/low & ID/eppn-unique-no-reassign |
51 |     https://aai.egi.eu/LoA#Substantial |
52 |     profile/cappuccino
53 | ```
54 | - This allows the following users:
55 |     - users of university IdPs (IAP/medium or profile/cappuccino)
56 |     - users of university IdPs according to an older spec (https://aai.egi.eu/LoA#Substantial)
57 |     - users of social IdPs (IAP/low)
58 |     - And requires a unique, non-rassignable identifier
59 | - Assurance definition is used from the `eduperson_assurance` claim
60 | and follows these specifications:
61 |     - [Refeds Assurance Framework (RAF)](https://refeds.org/assurance)
62 |     - [AARC-G021 Exchange of specific assurance information between Infrastructures](https://aarc-community.org/guidelines/aarc-g021)
63 | - You can find out your own assurance information with:
64 |     ```
65 |     mccli info --oidc <oidc-agent account name>
66 |     ```
67 | 
68 | 
69 | ## Authorisation Configuration
70 | You can support multiple OPs and configure authorisation for each OP separately.
71 | There are three options to authorise users:
72 | - authorise all: allow all users from a trusted OP
73 | - individual: authorise single users via their unique identifier given by `sub` + `iss`
74 | - VO-based: authorise users that are members of a specific VO (or a set of VOs)
75 | 
76 | The VO definitions allowed include:
77 | - String list of groups
78 | - Entitlements according to [AARC-G002 Expressing group membership and role information](https://aarc-community.org/wp-content/uploads/2017/11/AARC-JRA1.4A-201710.pdf)
79 | where the claim containing the VOs is configurable as well.
80 | 
81 | The default configuration contains several examples (commented out), but you'll need to modify `/etc/motley_cue/motley_cue.conf` to enable any authorisation.
82 | 
83 | You can find out your own groups with:
84 | ```
85 | mccli info --oidc <oidc-agent account name>
86 | ```
87 | 
88 | 
89 | 
90 | 


--------------------------------------------------------------------------------
/pam-ssh-oidc.md:
--------------------------------------------------------------------------------
 1 | ### PAM SSH OIDC
 2 | 
 3 | We offer two packages for installation: `pam-ssh-oidc` and
 4 | `pam-ssh-oidc-autoconfig`. The difference being that the `-autoconfig`
 5 | version will automatically patch/create `/etc/pam.d/sshd`, to allow sshd
 6 | to prompt for Access Tokens via Pluggable Authentication Module (PAM).
 7 | 
 8 | 
 9 | Install with either
10 | - `apt-get install pam-ssh-oidc-autoconfig`
11 | - `yum install pam-ssh-oidc-autoconfig`
12 | 
13 | or
14 | 
15 | - `apt-get install pam-ssh-oidc`
16 | - `yum install pam-ssh-oidc`
17 | 
18 | The pam module itself is configured in `/etc/pam.d/pam-ssh-oidc-config.ini`,
19 | the default pointing to the `motley-cue` instance, which is assumed to be
20 | on localhost. If you enabled HTTPS for your `motley-cue` instance, please make sure the configured `motley-cue` hostname matches the one in the host certificate.
21 | 
22 | You can verify it's working by `ssh <anything>@<hostname you installed on>`
23 | You should be prompted with
24 | ```
25 | Access Token: 
26 | ```
27 | If you do not see this prompt, please verify that you have enabled this in
28 | `/etc/ssh/sshd_config`:
29 | ```
30 | ChallengeResponseAuthentication yes
31 | ```
32 | 
33 | # Manual Configuration
34 | 
35 | For information on configuration, please 
36 | [see the Readmes of pam-ssh-oidc packaging](https://github.com/EOSC-synergy/pam-ssh-oidc-packaging/blob/master/documentation/README-pam-ssh-oidc.md)
37 | page.
38 | 
39 | If you still do not see the prompt, please [open an issue](https://github.com/EOSC-synergy/pam-ssh-oidc/issues)
40 | 
41 | 


--------------------------------------------------------------------------------