README.md 8.19 KB
Newer Older
1
# WIP - currently being updated
Michael Wagner's avatar
Michael Wagner committed
2

3
4
5
6
7
8
9
10
11
12
13
14
15
# 0. Intro
So. You would like to have a [openBIS ELN](https://openbis.ch/)? 
But wait, you would also like to actually send E-mails (a functionality necessary for exports for example)? And you would also like to use the institutional FAU SSO?

Then you are in the right place. 
___
# 1. Quickstart - Michi notes - HowTo use this repo 

### 1.1 connection
#### Moving the repo files to Torstens linux server

`scp -r ./* michi@cs6-podman-02.cs6.fau.de:~/openbis-mail-extend/`
#### connecting to Torstens linux server
Michael Wagner's avatar
Michael Wagner committed
16
`ssh michi@cs6-podman-02.cs6.fau.de`
17
18
19

### 1.2 podman
#### remove everything
Michael Wagner's avatar
Michael Wagner committed
20
```
Michael Wagner's avatar
Michael Wagner committed
21
22
23
podman stop -a
podman rm -a
podman volume rm -a
Michael Wagner's avatar
Michael Wagner committed
24
```
25
#### build new openBIS
Michael Wagner's avatar
Michael Wagner committed
26
`./run.sh`
27
#### list pods
Michael Wagner's avatar
Michael Wagner committed
28
`podman ps`
29
30
#### shell in the podman container
`podman exec -it cdi-sso   /bin/bash`
Michael Wagner's avatar
Michael Wagner committed
31
32
33



34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69

___
# 2. Quickstart - in general - HowTo use this repo 

1. clone the repo
2. edit `run.sh`
3. run `run.sh`
4. connect to the URL changed in `run.sh`






---
# 3. knowledge dump: installation tutorial

## 3.1 files explained
Firstly, let us have a look at the relevant files of the repository:


### run.sh and Containerfile
- core files, containing instructions on what to do

```
├── Containerfile
├── README.md
└── run.sh
``` 

- `Containerfile` contains the instructions to what is happening to the Docker image
- `run.sh` contains the podman commands, that build and run the pod


### shibboleth configuration
config files for Shibboleth, moved into the pod in `Containerfile`
Michael Wagner's avatar
Michael Wagner committed
70
```
71
├── shibboleth-configuration-files
Michael Wagner's avatar
Michael Wagner committed
72
73
│   ├── attribute-map.xml
│   ├── attribute-policy.xml
74
│   ├── metadata.xml
Michael Wagner's avatar
Michael Wagner committed
75
76
77
│   ├── protocols.xml
│   ├── security-policy.xml
│   ├── shibboleth2.xml
78
79
80
81
│   ├── sp-encrypt-cert.pem
│   ├── sp-encrypt-key.pem
│   ├── sp-signing-cert.pem
│   ├── sp-signing-key.pem
Michael Wagner's avatar
Michael Wagner committed
82
│   └── sso-metadata.xml
83
84
85
86
87
88
89
90
```

[Here](https://shibboleth.atlassian.net/wiki/spaces/SP3/pages/2067400308/ConfigurationFileSummary) is the link to the official Docu. I'll try to comment on each file and add my understanding of what it does.

- `attribute-map.xml` - this maps (IDP?) Attributes to an id, this id can be used by your application
  - for openBIS these are `mail`, `surname` and `givenName` 
  - FAU SSO gives `sn` instead of `surname`
- `attribute-policy.xml`
91
  - rules/checks/limitations on IDP data 
92
- `metadata.xml`
93
  - contains the certificate (for https, I think) 
94
- `protocols.xml`
95
  - not modified, SSO configuration file; auto config for logout, etc paths
96
- `security-policy.xml`
97
  - not modifies, security settings as booleans
98
- `shibboleth2.xml`
99
100
101
102
103
104
  - **main** configuration file, contains thing like IDP URL, metadata location, etc.
- SSO certificates/keys - normally these are generated by the config file - but I think they need to stay the same for the IDP? 
  - `sp-encrypt-cert.pem`
  - `sp-encrypt-key.pem`
  - `sp-signing-cert.pem`
  - `sp-signing-key.pem`
105
- `sso-metadata.xml`
106
  - [TODO] - I think this is the metadata from the FAU SSO
107
108
109
110
111
112
113
114
115
116
117
118

### openBIS configuration
config files for openBIS, moved into the pod in `Containerfile`
```
├── openBIS_config
│   ├── InstanceProfile.js
│   ├── SingleSignOnServlet.java
│   ├── datastore_server---service.properties
│   ├── openBIS-server---service.properties
│   └── openbis.conf
```

119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
- `InstanceProfile.js`
  - sets the SSO URL for openBIS 
- `SingleSignOnServlet.java`
  - This file defines the IDs openBIS is looking for when logging in via SSO (mail, surname, GivenName)
  - This needs to be modified to match the FAU SSO
- `datastore_server---service.properties`
  - config file for the openBIS datastore server - not used atm 
- `openBIS-server---service.properties`
  - config file for the openBIS server 
  - ldap attributenames can be configured here 
  - configures `allow-missing-user-creation = true`, without which you can't add SSO users in openbis 
    - (new user -> enter mail -> could not be validated -> rejected)
- `openbis.conf`
  - openBIS specific Apache config

134
135
136
### files
```
├── files
Michael Wagner's avatar
Michael Wagner committed
137
138
│   ├── entrypoint.sh
│   └── main.cf
139
```
140
141
142
143
- `entrypoint.sh`
  - openBIS script, I did not touch it, it contains shell script that is run when the  openBIS docker container starts, and it executes shell commands to start openBIS, postfix, etc.
- `main.cf`
  - config file for the postfix server addition (mail)
144
145
146


## 3.2 tutorial on how to get SSO - collection of tutorials
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
211
212
213
214
215
216
217
218
219
220
221
222
223
224
225
226
227
228
ETHzürich wrote [this guide](https://unlimited.ethz.ch/display/openBISDoc2010/Single+Sign+On+Authentication) on how to setup SSO with openBIS. 
What will follow now is a collection of the different tutorials necessary to get SSO running with openBIS. (The following guide is for a Debian system, since that is what I was working with - if you have another operating system, check the official guide for the differences )
___
### Installing Shibboleth

What follows now is an explanation of the different lines of Containerfile and their corresponding steps:

- prerequisites
   - shibboleth needs a folder under /run/
   - Apache installed (https needed)
   - no previous SP installation
   - sudo (running as root), ntp (keeping your system time syncrhonized) & curl (downloading packages/certificates) 

````commandline
   RUN mkdir /run/shibboleth
   RUN apt install sudo
   RUN sudo apt-get install ntp -y
   RUN sudo apt install curl -y
   RUN sudo apt install apache2 -y
````

- curl Shibboleth & install it
  - curl repo package, install package, install shibboleth:
````commandline
   RUN curl --fail --remote-name https://pkg.switch.ch/switchaai/debian/dists/buster/main/binary-all/misc/switchaai-apt-source_1.0.0_all.deb
   RUN sudo apt install ./switchaai-apt-source_1.0.0_all.deb -y
   RUN sudo apt update
   RUN sudo apt install --install-recommends shibboleth -y
   RUN echo sudo apt full-upgrade
   RUN sudo apt autoremove
````

- (optional) test your current configuration
````commandline
   RUN sudo shibd -t
   RUN sudo apache2ctl configtest
````



___
### Configuring Shibboleth

- you need to create SP keys for encryption and signing
````commandline
    RUN shib-keygen -u _shibd -g _shibd -h cdi-sso.openbis.data.fau.de -y 10 -e https://cdi-sso.openbis.data.fau.de/shibboleth -n sp-encrypt -o /etc/shibboleth/
    RUN shib-keygen -u _shibd -g _shibd -h cdi-sso.openbis.data.fau.de -y 10 -e https://cdi-sso.openbis.data.fau.de/shibboleth -n sp-signing -o /etc/shibboleth/
````

- you need to move the shibboleth config files into the pod
````commandline
    COPY shibboleth-configuration-files/* /etc/shibboleth/
````
___
### Configuring openBIS

- copy `http.ini` to actual openBIS server dir
- delete these two files: `https.ini` & `ssl.ini` in `servers/openBIS-server/jetty/start.d/`

````commandline
    RUN cp /home/openbis/openbis/servers/openBIS-server/jetty-dist/demo-base/start.d/http.ini /home/openbis/openbis/servers/openBIS-server/jetty/start.d/http.ini
    RUN rm -f /home/openbis/openbis/servers/openBIS-server/jetty-dist/demo-base/start.d/https.ini
    RUN rm -f /home/openbis/openbis/servers/openBIS-server/jetty-dist/demo-base/start.d/ssl.ini
````
- move the configuration files to the pod
- and make `InstanceProfile.js` writable
````commandline

    RUN chmod +w /home/openbis/openbis/servers/core-plugins/eln-lims/1/as/webapps/eln-lims/html/etc/InstanceProfile.js
    COPY ./openBIS_config/openBIS-server---service.properties /home/openbis/openbis/servers/openBIS-server/jetty/etc/service.properties
    COPY ./openBIS_config/InstanceProfile.js /home/openbis/openbis/servers/core-plugins/eln-lims/1/as/webapps/eln-lims/html/etc/InstanceProfile.js
    COPY ./openBIS_config/openbis.conf /etc/apache2/sites-available/
````    
- enable openbis in the apache sites-enabled
- restart apache2 & shibboleth
````commandline
    RUN sudo a2ensite openbis
    RUN sudo apt-get -y install systemctl
    RUN sudo systemctl reload apache2
    RUN sudo systemctl reload shibd.service
````

Michael Wagner's avatar
Michael Wagner committed
229

230
231
# 4. notes and thougts

232
233
# 5. tips and tricks

234
235
236
237

# What I did:
I followed the [openBIS tutorial](https://unlimited.ethz.ch/display/openBISDoc2010/Single+Sign+On+Authentication) on setting up SSO.
The issue is [here](https://gitlab.rrze.fau.de/cdi/admin/people/michael_wagner/-/issues/77#note_31916).