comanage-registry-docker/docs/shibboleth-sp-mariadb.md at afd84cffc8110e90da61407e0a3aa7bf7a534867 · docker/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 MariaDB

23

24

Follow these steps to build and run COmanage Registry

25

using the Shibboleth SP for authentication and MariaDB

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

* Initialize the Docker Swarm:

105

106

```

107

docker swarm init

108

```

109

110

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

111

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

112

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

113

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

114

115

```

116

echo "jPkrc3TUijfmT3vi1ZKw" | docker secret create mariadb_root_password -

117

118

echo "ayFjKFHTre74A0k8k1mq" | docker secret create mariadb_password -

119

120

echo "ayFjKFHTre74A0k8k1mq" | docker secret create comanage_registry_database_user_password - 

121

122

docker secret create https_cert_file fullchain.cert.pem

123

124

docker secret create https_privkey_file privkey.pem

125

126

docker secret create shibboleth_sp_encrypt_cert sp-encrypt-cert.pem

127

128

docker secret create shibboleth_sp_encrypt_privkey sp-encrypt-key.pem

129

```

130

131

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

132

and other files including the Shibboleth SP configuration files:

133

134

```

135

sudo mkdir -p /srv/docker/var/lib/mysql

136

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

137

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

138

```

139

140

* Copy Shibboleth SP configuration files into place to be mounted

141

into the running container. Your Shibboleth SP configuration should

142

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

143

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

144

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

145

the details will depend on your SAML federation choices.

146

147

148

```

149

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

150

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

151

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

152

```

153

154

* Define shell variables for the first COmanage Registry platform

155

administrator, for example:

156

157

```

158

export COMANAGE_REGISTRY_ADMIN_GIVEN_NAME=Karel

159

export COMANAGE_REGISTRY_ADMIN_FAMILY_NAME=Novak

160

export COMANAGE_REGISTRY_ADMIN_USERNAME=karel.novak@my.org

161

```

162

163

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

164

SAML IdP for the first platform administrator. The Shibboleth SP

165

configuration should be such that the value is populated into

166

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

167

administrator logs into COmanage Registry.

168

169

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

170

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

171

example

172

173

```

174

export COMANAGE_REGISTRY_VIRTUAL_HOST_FQDN=registry.my.org

175

```

176

177

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

178

179

```

180

version: '3.1'

181

182

services:

183

184

comanage-registry-database:

185

image: mariadb:10.2

186

volumes:

187

- /srv/docker/var/lib/mysql:/var/lib/mysql

188

environment:

189

- MYSQL_ROOT_PASSWORD_FILE=/run/secrets/mariadb_root_password

190

- MYSQL_DATABASE=registry

191

- MYSQL_USER=registry_user

192

- MYSQL_PASSWORD_FILE=/run/secrets/mariadb_password

193

secrets:

194

- mariadb_root_password

195

- mariadb_password

196

networks:

197

- default

198

deploy:

199

replicas: 1

200

201

comanage-registry:

202

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

203

volumes:

204

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

205

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

206

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

207

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

208

environment:

209

- COMANAGE_REGISTRY_ADMIN_GIVEN_NAME=${COMANAGE_REGISTRY_ADMIN_GIVEN_NAME}

210

- COMANAGE_REGISTRY_ADMIN_FAMILY_NAME=${COMANAGE_REGISTRY_ADMIN_FAMILY_NAME}

211

- COMANAGE_REGISTRY_ADMIN_USERNAME=${COMANAGE_REGISTRY_ADMIN_USERNAME}

212

- COMANAGE_REGISTRY_DATASOURCE=Database/Mysql

213

            - COMANAGE_REGISTRY_DATABASE_USER_PASSWORD_FILE=/run/secrets/comanage_registry_database_user_password

214

- COMANAGE_REGISTRY_VIRTUAL_HOST_FQDN=${COMANAGE_REGISTRY_VIRTUAL_HOST_FQDN}

215

- HTTPS_CERT_FILE=/run/secrets/https_cert_file

216

- HTTPS_PRIVKEY_FILE=/run/secrets/https_privkey_file

217

- SHIBBOLETH_SP_ENCRYPT_CERT=/run/secrets/shibboleth_sp_encrypt_cert

218

- SHIBBOLETH_SP_ENCRYPT_PRIVKEY=/run/secrets/shibboleth_sp_encrypt_privkey

219

secrets:

220

- comanage_registry_database_user_password

221

- https_cert_file

222

- https_privkey_file

223

- shibboleth_sp_encrypt_cert

224

- shibboleth_sp_encrypt_privkey

225

networks:

226

- default

227

ports:

228

- "80:80"

229

- "443:443"

230

deploy:

231

replicas: 1

232

233

secrets:

234

comanage_registry_database_user_password:

235

external: true

236

mariadb_root_password

237

external: true

238

mariadb_password

239

external: true

240

shibboleth_sp_encrypt_cert:

241

external: true

242

shibboleth_sp_encrypt_privkey:

243

external: true

244

https_cert_file:

245

external: true

246

https_privkey_file:

247

external: true

248

```

249

250

* Deploy the COmanage Registry service stack:

251

252

```

253

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

254

```

255

256

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

257

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

258

Shibboleth SP daemons will not be started until the entrypoint scripts

259

detect that the database has been initialized.

260

261

You may monitor the progress of the database container using

262

263

```

264

docker service logs -f comanage-registry-database

265

```

266

267

and the progress of the COmanage Registry container using

268

269

```

270

docker service logs -f comanage-registry

271

```

272

273

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

274

275

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

276

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

277

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

278

administrator.

279

280

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

281

script will have created the template file

282

283

```

284

Config/email.php

285

```

286

287

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

288

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

289

SMTP server to send outgoing email.

290

291

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

292

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

293

the platform.

294

295

* To stop the services:

296

```

297

docker stack rm comanage-registry

298

```