# Deployment and Administration guide This is the INDIGO IAM deployment and administration guide. ## Requirements ### Docker The IAM service is currently distributed as a docker image from Dockerhub, so in order to run the service, you will need: * Docker v. 1.11.1 or greater If you want to use docker-compose to deploy the service, you will also need * docker-compose v.1.7.0 or greater ### MariaDB/MySQL The IAM service stores information in a mariadb/mysql database. ### NginX The IAM service is designed to run as a backend Java application behind an NGINX reverse proxy (it could run equally well behing apache, but we tested it behind NGINX). ## Configuration ### Prerequisites In order to run a production instance of the IAM, you will need: * An X.509 certificate, used for SSL termination at the NGINX reverse proxy * A JSON keystore holding the keys used to sign JSON Web Tokens. You can use [this handy tool](https://github.com/mitreid-connect/json-web-key-generator) to generate JSON web keys for your service If you enable SAML login: * SAML metadata for your SAML federation * SAML metadata for the IAM service #### MySQL configuration Just create a database and a user that has read/write/schema change access to the database. #### NGINX configuration Configure NGINX to act as a reverse proxy for the IAM backend application. The example configuration below is taken from the docker file for the IAM development environment: ``` server { listen 443 ssl; server_name YOUR_HOSTNAME_HERE; access_log /var/log/nginx/iam.access.log combined; ssl on; ssl_protocols TLSv1 TLSv1.1 TLSv1.2; ssl_certificate /path/to/your/ssl/cert.pem; ssl_certificate_key /path/to/your/ssl/key.pem; location / { proxy_pass YOUR_BE_HOSTNAME_HERE:8080; proxy_set_header X-Real-IP $remote_addr; proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for; proxy_set_header X-Forwarded-Proto https; proxy_set_header Host $http_host; } ``` #### JSON web keys generation Checkout the json-web-key-generator repository: ```bash git clone https://github.com/mitreid-connect/json-web-key-generator ``` Build the code with: ```bash mvn package ``` Generate a key with the following command: ```bash java -jar target/json-web-key-generator-0.3-SNAPSHOT-jar-with-dependencies.jar \ -t RSA -s 1024 -S -i rsa1 Full key: { "keys": [ { "p": "3oh7ex6zgdmJh5NBD0IplmBDDGC2ECu2A1vcp8e8DqE7OSSpAc1T9tTjJioCGqkNM51JK_MtgCJz1CiysVDOQQ", "kty": "RSA", "q": "nRmBm5tQ2wmOtd1XUYDRH2qWai6eElt-1cvO5tnTdWZkFaAeaHQ3_xf_PFOjyAv5Y5rNLgf_Xbu9UCo_mSrDMQ", "d": "BGHRhQP6ADqqSrM8_mI0YhjGStj1aW9rLi7wXQMJ122kegPxIT7dfP-5UScxykD_BrCCHQVPxdJl5wXy-giZnhaL9wtDkOXb8D8RCi1n02cs3Z1T23xONi_AG47QPBZjM5GcX-oOGCENByuEIdkU_Bn6vvqM3oyVlj5sio7tNAE", "e": "AQAB", "kid": "rsa1", "qi": "RarXtTFCE3hk5ZanLWEapDnn7SLSxAvDcBTmG5SpCI9Eix7cfTigaK6N7OQIN0uGO1GJ-KVWL2v8dyI1jMoU6g", "dp": "MtBtieavzMXUzr2ETKyp_GmMxeXLjRO-IzQ1xaYpPhn5AQprATtWofVozQ0on9fcaN3QmJWV3T2Av4BvlWfDQQ", "dq": "CWJ7rpsBooQYpV6al8DVPUY1xBQS10_l7MmnC31Zt3qtYelVx7GhoriBQ85PS2UDueKGfUh3BddwQLi1YeX_EQ", "n": "iI_fuJq4z_9VQY5EH41sQWOAYUsjtxAFjRnAc1P5-GPOx3Izg9V7yKNmudLUt-jIkv6D5h-AzrhEV6DOdBRoiN4el1mCZ95jiJkjU2kpVOmutDysZkrn667zPd43w7E6IqHnahmMrVUjUyx6pie1SqJHLUXghz8Gle-1yi08_XE" } ] } ``` Save the output of the above command (minus the `Full key:` initial text) in a file. ### IAM docker image The IAM service is provided on the following Dockerhub repositories: * indigoiam/iam-login-service * indigodatacloud/iam-login-service We keep the images in sync, so the following instructions apply to images fetched from any of the two repositories. ### IAM configuration The IAM service is configured via spring profiles and environment variables. #### IAM profiles IAM profiles are used to enable/disable group of IAM functionalities. Currently the following profiles are defined: | *Profile name* | *Active by default* | *Description* | | -------------- | ------------------- | ----------------------------------------------------------------- | | h2 | yes | Enables h2 in-memory database, useful for development and testing | | mysql | no | Enables MySQL database backend | | google | no | Enables Google authentication | | saml | no | Enables SAML authentication | | dev | yes | Enables development debugging information | | registration | yes | Enables user registration and reset password functionalities | Profiles are enabled by setting the `spring.profiles.active` Java system property when starting the IAM service. This can be done, using the official IAM docker image, by setting the IAM\_JAVA\_OPTS environment variable as follows: ``` IAM_JAVA_OPTS="-Dspring.profiles.active=mysql,google,saml" ``` #### Service configuration All configurable aspects of the IAM are configured via environment variables. | *Env. variable* | *Default value* | *Meaning* | | ---------------------------------- | ------------------------------- | ----------------------------------------------------------------------------------------------------------- | | IAM\_PORT | 8080 | The IAM service will listen on this port | | IAM\_USE\_FORWARDED\_HEADERS | false | Use forward headers from reverse proxy. Set this to true when deploying the service behind a reverse proxy. | | IAM\_ISSUER | | This is the endpoint on which the IAM will receive requests. | | IAM\_KEY\_STORE\_LOCATION | N/A | The path to the JSON key store that holds the keys used to sign the tokens | | IAM\_X509\_TRUST\_ANCHORS\_DIR | /etc/grid-security/certificates | Where CA certificates will be searched | | IAM\_X509\_TRUST\_ANCHORS\_REFRESH | 14400 | How frequently (in seconds) should trust anchors be refreshed | #### Database access options | *Env. variable* | *Default value* | *Meaning* | | ----------------- | --------------- | -------------------------------------------------- | | IAM\_DB\_HOST | N/A | The host where the MariaDB/MySQL daemon is running | | IAM\_DB\_PORT | 3306 | The database port | | IAM\_DB\_NAME | iam | The database name | | IAM\_DB\_USERNAME | iam | The database username | | IAM\_DB\_PASSWORD | pwd | The database password | #### Google authentication options | *Env. variable* | *Default value* | *Meaning* | | --------------------------- | --------------- | --------------------------------------- | | IAM\_GOOGLE\_CLIENT\_ID | N/A | The google OpenID-connect client id | | IAM\_GOOGLE\_CLIENT\_SECRET | N/A | The Google OpenID-connect client secret | | IAM\_GOOGLE\_REDIRECT\_URIS | N/A | The Google OpenID-connect redirect URIs | #### SAML authentication options | *Env. variable* | *Default value* | *Meaning* | | ----------------------------- | --------------- | ------------------------------------------------------------------------- | | IAM\_SAML\_ENTITY\_ID | N/A | The SAML entity ID | | IAM\_SAML\_KEYSTORE | N/A | The keystore holding SAML certificate and keys | | IAM\_SAML\_KEYSTORE\_PASSWORD | N/A | The keystore password | | IAM\_SAML\_KEY\_ID | N/A | The identifier of the key that should be used to sign requests/assertions | | IAM\_SAML\_KEY\_PASSWORD | N/A | The SAML key password | | IAM\_SAML\_IDP\_METADATA | N/A | The path to the SAML federation idp metadata | #### Notification service options IAM notification service use an external SMTP server for sending email notifications. The table below contains the options for configure the SMTP server. | *Env. variable* | *Default value* | *Meaning* | | ------------------- | --------------- | ------------------------------------------------------------------ | | IAM\_MAIL\_HOST | localhost | Hostname of the SMTP server to use for sending notification emails | | IAM\_MAIL\_PORT | 25 | Port on which SMTP server to use is listening | | IAM\_MAIL\_USERNAME | N/A | Username to use for authentication on SMTP server, if required | | IAM\_MAIL\_PASSWORD | N/A | Password to use for authentication on SMTP server, if required | Specific options: | *Env. variable* | *Default value* | *Meaning* | | --------------------------------- | ------------------------ | -------------------------------------------------------------------------------------------------------------------------- | | IAM\_NOTIFICATION\_DISABLE | false | Turn on the notification service. If set to `true`, notifications aren't send to mail server, but logged into the log file | | IAM\_NOTIFICATION\_FROM | indigo\@localhost | Mail address used as mail sender | | IAM\_NOTIFICATION\_TASK\_DELAY | 30000 | Time interval, in milliseconds, between two consecutive runs of the job that send notifications | | IAM\_NOTIFICATION\_CLEANUP\_AGE | 30 | Retention of delivered messages, in days | | IAM\_NOTIFICATION\_ADMIN\_ADDRESS | indigo-alerts\@localhost | Mail address used as receiver for administrative notifications | ### Example configuration The IAM service is run starting the docker container with the following command: ```bash /usr/bin/docker run \ --name iam-login-service --net=iam -p 8080:8080 \ --env-file=/path/to//iam-login-service/env \ -v /path/to//keystore.jks:/keystore.jks:ro \ indigodatacloud/iam-login-service ``` The env file content is the following: ``` IAM_JAVA_OPTS=-Dspring.profiles.active=google,mysql -Djava.security.egd=file:/dev/urandom IAM_BASE_URL=https://iam-test.indigo-datacloud.eu IAM_ISSUER=https://iam-test.indigo-datacloud.eu/ IAM_USE_FORWARDED_HEADERS=true IAM_KEY_STORE_LOCATION=file:/keystore.jks IAM_DB_HOST=the_db_host IAM_DB_NAME=iam_login_service IAM_DB_USERNAME=iam_test IAM_DB_PASSWORD=some_super_secure_password IAM_DB_VALIDATION_QUERY=SELECT 1 IAM_GOOGLE_CLIENT_ID=XXXXXXXXXXXXXXXXX.apps.googleusercontent.com IAM_GOOGLE_CLIENT_SECRET=*********** IAM_GOOGLE_REDIRECT_URIS=https://iam-test.indigo-datacloud.eu/openid_connect_login IAM_SAML_ENTITY_ID=https://iam-test.indigo-datacloud.eu IAM_SAML_KEYSTORE=file:///saml-keystore.jks IAM_SAML_KEYSTORE_PASSWORD=******** IAM_SAML_KEY_ID=iam-test IAM_SAML_KEY_PASSWORD=******** IAM_SAML_IDP_METADATA=file:///idp-metadata.xml IAM_NOTIFICATION_FROM=iam@iam-test.mydomain.eu IAM_NOTIFICATION_TASK_DELAY=5000 IAM_NOTIFICATION_ADMIN_ADDRESS=iam-admins@mydomain.eu IAM_MAIL_HOST=mailman.mydomain.eu ``` --- # Agent Instructions: Querying This Documentation If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question. Perform an HTTP GET request on the current page URL with the `ask` query parameter: ``` GET https://indigo-dc.gitbook.io/iam/admin.md?ask= ``` The question should be specific, self-contained, and written in natural language. The response will contain a direct answer to the question and relevant excerpts and sources from the documentation. Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.