comanage-registry-docker/docs/shibboleth-sp-postgresql.md at afd84cffc8110e90da61407e0a3aa7bf7a534867 · tzeller/comanage-registry-docker

1

<!--

2

COmanage Registry Docker documentation

3

4

Portions licensed to the University Corporation for Advanced Internet

5

Development, Inc. ("UCAID") under one or more contributor license agreements.

6

See the NOTICE file distributed with this work for additional information

7

regarding copyright ownership.

8

9

UCAID licenses this file to you under the Apache License, Version 2.0

10

(the "License"); you may not use this file except in compliance with the

11

License. You may obtain a copy of the License at:

12

13

http://www.apache.org/licenses/LICENSE-2.0

14

15

Unless required by applicable law or agreed to in writing, software

16

distributed under the License is distributed on an "AS IS" BASIS,

17

WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.

18

See the License for the specific language governing permissions and

19

limitations under the License.

20

-->

21

22

# COmanage Registry with Shibboleth SP and PostgreSQL

23

24

Follow these steps to build and run COmanage Registry

25

using the Shibboleth SP for authentication and PostgreSQL

26

as the relational database.

27

28

* Install Docker. These instructions require version 17.05 or higher.

29

30

* Clone this repository:

31

32

```

33

git clone https://github.com/Internet2/comanage-registry-docker.git

34

cd comanage-registry-docker

35

```

36

37

* Define the shell variable `COMANAGE_REGISTRY_VERSION` to be the version

38

of COmanage Registry you want to deploy. See the

39

[COmanage Registry Release History](https://spaces.internet2.edu/display/COmanage/Release+History)

40

wiki page for the list of releases. We recommend using the latest release.

41

42

Here is an example (but please check the wiki page for the latest release number):

43

44

```

45

export COMANAGE_REGISTRY_VERSION=3.2.1

46

```

47

48

* Define the shell variable `COMANAGE_REGISTRY_BASE_IMAGE_VERSION` to be the

49

version of the base image you are about to build:

50

51

```

52

export COMANAGE_REGISTRY_BASE_IMAGE_VERSION=1

53

```

54

55

* Build the base COmanage Registry image:

56

57

```

58

pushd comanage-registry-base

59

TAG="${COMANAGE_REGISTRY_VERSION}-${COMANAGE_REGISTRY_BASE_IMAGE_VERSION}"

60

docker build \

61

--build-arg COMANAGE_REGISTRY_VERSION=${COMANAGE_REGISTRY_VERSION} \

62

-t comanage-registry-base:${TAG} .

63

popd

64

```

65

66

* Define the shell variable `COMANAGE_REGISTRY_SHIBBOLETH_SP_BASE_IMAGE_VERSION`

67

to be the version of the base Shibboleth SP image you are about to build:

68

69

```

70

export COMANAGE_REGISTRY_SHIBBOLETH_SP_BASE_IMAGE_VERSION=1

71

```

72

73

* Build the base Shibboleth SP image:

74

75

```

76

pushd comanage-registry-shibboleth-sp-base

77

TAG="${COMANAGE_REGISTRY_SHIBBOLETH_SP_BASE_IMAGE_VERSION}"

78

docker build \

79

-t comanage-registry-shibboleth-sp-base:$TAG .

80

popd

81

```

82

83

* Define the shell variable `COMANAGE_REGISTRY_SHIBBOLETH_SP_IMAGE_VERSION`

84

to be the version of the image you are about to build:

85

86

```

87

export COMANAGE_REGISTRY_SHIBBOLETH_SP_IMAGE_VERSION=1

88

```

89

90

* Build an image for COmanage Registry that uses the Shibboleth SP

91

for authentication:

92

93

```

94

pushd comanage-registry-shibboleth-sp

95

TAG="${COMANAGE_REGISTRY_VERSION}-shibboleth-sp-${COMANAGE_REGISTRY_SHIBBOLETH_SP_IMAGE_VERSION}"

96

docker build \

97

--build-arg COMANAGE_REGISTRY_VERSION=${COMANAGE_REGISTRY_VERSION} \

98

    --build-arg COMANAGE_REGISTRY_BASE_IMAGE_VERSION=${COMANAGE_REGISTRY_BASE_IMAGE_VERSION} \

99

    --build-arg COMANAGE_REGISTRY_SHIBBOLETH_SP_BASE_IMAGE_VERSION=${COMANAGE_REGISTRY_SHIBBOLETH_SP_BASE_IMAGE_VERSION} \

100

-t comanage-registry:$TAG .

101

popd

102

```

103

104

* Define the shell variable `COMANAGE_REGISTRY_POSTGRES_IMAGE_VERSION`

105

to be the version of the image you are about to build:

106

107

```

108

export COMANAGE_REGISTRY_POSTGRES_IMAGE_VERSION=1

109

```

110

111

* Build an image for PostgreSQL for COmanage Registry:

112

113

```

114

pushd comanage-registry-postgres

115

TAG="${COMANAGE_REGISTRY_POSTGRES_IMAGE_VERSION}"

116

docker build \

117

-t comanage-registry-postgres:${TAG} .

118

popd

119

```

120

121

* Initialize the Docker Swarm:

122

123

```

124

docker swarm init

125

```

126

127

* Create secrets for the database root password, the COmanage Registry database

128

password, the HTTPS certificate (and CA signing chain) and private key files,

129

and the Shibboleth SP encryption certificate and private key files (be sure

130

to choose your own values and do not use the examples below):

131

132

```

133

echo "jPkrc3TUijfmT3vi1ZKw" | docker secret create postgres_password -

134

135

echo "ayFjKFHTre74A0k8k1mq" | docker secret create comanage_registry_postgres_user_password - 

136

137

echo "ayFjKFHTre74A0k8k1mq" | docker secret create comanage_registry_database_user_password - 

138

139

docker secret create https_cert_file fullchain.cert.pem

140

141

docker secret create https_privkey_file privkey.pem

142

143

docker secret create shibboleth_sp_encrypt_cert sp-encrypt-cert.pem

144

145

docker secret create shibboleth_sp_encrypt_privkey sp-encrypt-key.pem

146

```

147

148

* Create directories on the Docker engine host(s) for state files

149

and other files including the Shibboleth SP configuration files:

150

151

```

152

sudo mkdir -p /srv/docker/var/lib/postgresql/data

153

sudo mkdir -p /srv/docker/srv/comanage-registry/local

154

sudo mkdir -p /srv/docker/etc/shibboleth

155

```

156

157

* Copy Shibboleth SP configuration files into place to be mounted

158

into the running container. Your Shibboleth SP configuration should

159

result in the primary identifier attribute you expect to be asserted by the SAML

160

IdP(s) to populate `REMOTE_USER` so that it can be read by COmanage Registry.

161

A common choice is to populate `REMOTE_USER` with eduPersonPrincipalName, but

162

the details will depend on your SAML federation choices.

163

164

165

```

166

cp shibboleth2.xml /srv/docker/etc/shibboleth/

167

cp attribute-map.xml /srv/docker/etc/shibboleth/

168

cp saml-metadata.xml /src/docker/etc/shibboleth/

169

```

170

171

* Define shell variables for the first COmanage Registry platform

172

administrator, for example:

173

174

```

175

export COMANAGE_REGISTRY_ADMIN_GIVEN_NAME=Karel

176

export COMANAGE_REGISTRY_ADMIN_FAMILY_NAME=Novak

177

export COMANAGE_REGISTRY_ADMIN_USERNAME=karel.novak@my.org

178

```

179

180

The username should be the value you expect to be asserted by the

181

SAML IdP for the first platform administrator. The Shibboleth SP

182

configuration should be such that the value is populated into

183

`REMOTE_USER` where it will be read when the first platform

184

administrator logs into COmanage Registry.

185

186

* Define a shell variable with the fully-qualified domain name for

187

the virtual host from which COmanage Registry will be served. For

188

example

189

190

```

191

export COMANAGE_REGISTRY_VIRTUAL_HOST_FQDN=registry.my.org

192

```

193

194

* Create a Docker Swarm services stack description (compose) file in YAML format:

195

196

```

197

version: '3.1'

198

199

services:

200

201

comanage-registry-database:

202

image: comanage-registry-postgres:${COMANAGE_REGISTRY_POSTGRES_IMAGE_VERSION}

203

volumes:

204

- /srv/docker/var/lib/postgresql/data:/var/lib/postgresql/data

205

environment:

206

- POSTGRES_PASSWORD_FILE=/run/secrets/postgres_password

207

            - COMANAGE_REGISTRY_POSTGRES_USER_PASSWORD_FILE=/run/secrets/comanage_registry_postgres_user_password

208

secrets:

209

- postgres_password

210

- comanage_registry_postgres_user_password

211

networks:

212

- default

213

deploy:

214

replicas: 1

215

216

comanage-registry:

217

        image: comanage-registry:${COMANAGE_REGISTRY_VERSION}-shibboleth-sp-${COMANAGE_REGISTRY_SHIBBOLETH_SP_IMAGE_VERSION}

218

volumes:

219

- /srv/docker/srv/comanage-registry/local:/srv/comanage-registry/local

220

- /srv/docker/etc/shibboleth/shibboleth2.xml:/etc/shibboleth/shibboleth2.xml

221

            - /srv/docker/etc/shibboleth/attribute-map.xml:/etc/shibboleth/attribute-map.xml

222

            - /srv/docker/etc/shibboleth/saml-metadata.xml:/etc/shibboleth/saml-metadata.xml

223

environment:

224

- COMANAGE_REGISTRY_ADMIN_GIVEN_NAME=${COMANAGE_REGISTRY_ADMIN_GIVEN_NAME}

225

- COMANAGE_REGISTRY_ADMIN_FAMILY_NAME=${COMANAGE_REGISTRY_ADMIN_FAMILY_NAME}

226

- COMANAGE_REGISTRY_ADMIN_USERNAME=${COMANAGE_REGISTRY_ADMIN_USERNAME}

227

- COMANAGE_REGISTRY_DATASOURCE=Database/Postgres

228

            - COMANAGE_REGISTRY_DATABASE_USER_PASSWORD_FILE=/run/secrets/comanage_registry_database_user_password

229

- COMANAGE_REGISTRY_VIRTUAL_HOST_FQDN=${COMANAGE_REGISTRY_VIRTUAL_HOST_FQDN}

230

- HTTPS_CERT_FILE=/run/secrets/https_cert_file

231

- HTTPS_PRIVKEY_FILE=/run/secrets/https_privkey_file

232

- SHIBBOLETH_SP_ENCRYPT_CERT=/run/secrets/shibboleth_sp_encrypt_cert

233

- SHIBBOLETH_SP_ENCRYPT_PRIVKEY=/run/secrets/shibboleth_sp_encrypt_privkey

234

secrets:

235

- comanage_registry_database_user_password

236

- https_cert_file

237

- https_privkey_file

238

- shibboleth_sp_encrypt_cert

239

- shibboleth_sp_encrypt_privkey

240

networks:

241

- default

242

ports:

243

- "80:80"

244

- "443:443"

245

deploy:

246

replicas: 1

247

248

secrets:

249

comanage_registry_database_user_password:

250

external: true

251

comanage_registry_postgres_user_password:

252

external: true

253

postgres_password:

254

external: true

255

shibboleth_sp_encrypt_cert:

256

external: true

257

shibboleth_sp_encrypt_privkey:

258

external: true

259

https_cert_file:

260

external: true

261

https_privkey_file:

262

external: true

263

```

264

265

* Deploy the COmanage Registry service stack:

266

267

```

268

docker stack deploy --compose-file comanage-registry-stack.yml comanage-registry

269

```

270

271

Since this is the first initialization of the containers it will take some

272

time for the database tables to be created. The Apache HTTP Server and

273

Shibboleth SP daemons will not be started until the entrypoint scripts

274

detect that the database has been initialized.

275

276

You may monitor the progress of the database container using

277

278

```

279

docker service logs -f comanage-registry-database

280

```

281

282

and the progress of the COmanage Registry container using

283

284

```

285

docker service logs -f comanage-registry

286

```

287

288

* After the Apache HTTP Server has started browse to port 443 on the host.

289

290

* Click `Login` to initiate a SAML authentication flow. After authenticating at

291

the SAML IdP the Shibboleth SP should consume the SAML assertion and populate

292

`REMOTE_USER` with the value for the username for the first platform

293

administrator.

294

295

* During the first instantiation of the COmanage Registry service the entrypoint

296

script will have created the template file

297

298

```

299

Config/email.php

300

```

301

302

in the directory `/srv/docker/srv/comanage-registry/local` on the Docker engine

303

host. Edit that file to configure how COmanage Registry should connect to an

304

SMTP server to send outgoing email.

305

306

* Visit the [COmanage wiki](https://spaces.internet2.edu/display/COmanage/Setting+Up+Your+First+CO)

307

to learn how to create your first collaborative organization (CO) and begin using

308

the platform.

309

310

* To stop the services:

311

```

312

docker stack rm comanage-registry

313

```