Create-Keyloak-Server.md

+Keycloak server is the Identity broker used for BAND.
+
+The server is a Ubuntu machine.You may need a public IP and proper domain name for your own Keycloak server.
+
+You will need a server ready with proper DNS name for the public facing portal, before configuring keyloak.
+
+**Installation**
+
+1.  install docker engine on the machine. [https://www.digitalocean.com/community/tutorials/how-to-install-and-use-docker-on-ubuntu-18-04](https://www.digitalocean.com/community/tutorials/how-to-install-and-use-docker-on-ubuntu-18-04)
+2.  install nginx
+
+```text
+apt-get update -y & apt-get install -y nginx
+```
+
+3\. Obtain SSL certificates from IT or Letsencrypt
+
+4\. create a directory for SSL certificates
+
+```text
+mkdir /etc/nginx/certificates
+```
+
+5\. make sure hostname matches DNS name
+
+6\. apt-get install apt-transport-https ca-certificates curl software-properties-common  
+7\. pull keycloak container. Note that the currently keycloak version used is 4.5.0Final which is pretty old and due to upgrade. A more recent version would be better, but this will be a future work
+
+docker pull jboss/keycloak
+
+8\. configure nginx. remove default from /etc/nginx/site-enabled, add a file 'ssl' with the below content to /etc/nginx/site-available and enable it.
+
+```text
+server {
+        listen       443 ssl http2 default_server;
+        listen       [::]:443 ssl http2 default_server;
+        server_name  auth.cbbcs.embl.de;
+        root         /usr/share/nginx/html;
+
+        ssl_certificate "CERTIFICATE";
+        ssl_certificate_key "SERVER KEY";
+        ssl_session_cache shared:SSL:1m;
+        ssl_session_timeout  10m;
+        ssl_ciphers HIGH:!aNULL:!MD5;
+        ssl_prefer_server_ciphers on;
+
+        location / {
+                proxy_pass http://127.0.0.1:8080;
+                proxy_set_header Host $host;
+                proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for;
+                proxy_set_header X-Forwarded-Proto https;
+                # proxy_set_header Host $host;
+                proxy_set_header X-Real-IP $remote_addr;
+        }
+
+        error_page 404 /404.html;
+            location = /40x.html {
+        }
+
+        error_page 500 502 503 504 /50x.html;
+            location = /50x.html {
+        }
+    }
+```
+
+**Configuration**
+
+1.  start keycloak with the below command, modify PASSWORD for admin user and keycloak image version.
+
+```text
+docker run --name=keycloak -p 8080:8080 -e KEYCLOAK_USER=admin -e KEYCLOAK_PASSWORD=PASSWORD -e DB_VENDOR=H2 -e PROXY_ADDRESS_FORWARDING=true -e ROOT_LOGLEVEL=ALL -e b=0.0.0.0 jboss/keycloak &
+```
+
+2\. log into the container
+
+docker exec -it --user root keycloak bash
+
+3\. add ldap certificates to keystore (LDAP certificates are self signed certificates generated from the LDAP server.)
+
+keytool -import -trustcacerts -alias ldap  -file LDAP\_CERT -keystore /usr/lib/jvm/java-1.8.0-openjdk-1.8.0.181-3.b13.el7\_5.x86\_64/jre/lib/security/cacerts
+
+4\. log out of the container, and restart container
+
+docker restart keycloak
+
+5\. Configure Google as Identify provider via admin interface.
+
+*   redirect URI: [https://YOUR_KEYCLOAK_SERVER/auth/realms/master/broker/google/endpoint](https://YOUR_KEYCLOAK_SERVER//auth/realms/master/broker/google/endpoint)
+*   google client id: YOUR_GOOGLE_CLIENT_ID
+*   client secret: YOUR_GOOGLE_CLIENT_SECRET
+*   in Google developer console, enable Google+ API
+*   on Keycloak Identity Provider interface
+    *   change to "ON" for Enabled, Store Tokens, Trust Email
+    *   Alias:google
+    *   Display Name: Google
+    *   First Login Flow: EOSC First Broker Login
+    *   Authorization URL: [https://accounts.google.com/o/oauth2/v2/auth](https://accounts.google.com/o/oauth2/v2/auth)
+    *   Token URL: [https://oauth2.googleapis.com/token](https://oauth2.googleapis.com/token)
+    *   Default Scopes: openid email profile
+    *   Permission tab: enabled
+
+6\. Configure LSAAI as identity provider via admin interface (Register your service with LSAAI beforehand)
+
+*   client id: REFER TO PASSWORD FILE
+*   client secret: REFER TO PASSWORD FILE
+*   on Keycloak Identity Provider interface
+    *   change to "ON" for Enabled, Store Tokens, Trust Email
+    *   Alias: lsaai
+    *   Display Name: LS AAI
+    *   First Login Flow: EOSC First Broker Login
+    *   Authorization URL: https://proxy.aai.lifescience-ri.eu/saml2sp/OIDC/authorization
+    *   Token URL: [https://proxy.aai.lifescience-ri.eu/OIDC/token](https://proxy.aai.lifescience-ri.eu/OIDC/token)
+    *   User Info URL: https://proxy.aai.lifescience-ri.eu/OIDC/userinfo
+    *   Default Scopes: openid email profile
+    *   Permission tab: enabled
+
+7\. Create your own keyloak login flow extension, compile it as jar file and copy keycloak-flow-extension.jar to /opt/jboss/keycloak/standalone/deployments inside the keycloak container.
+
+This article will be of help on creating keylcoak extensions https://andrebiegel.github.io/projects/2021/08/28/keycloak-extensions.html
+
+8\. Create your own login them, and copy it into keycloak container (https://www.keycloak.org/docs/latest/server_development/)
+
+9\. restart keycloak container
+
+10.login into the keycloak container, check /etc/hosts. it should contain the correct LDAP server IP
+
+**Configuration via Keycloak admin interface**
+
+[Refer to Keycload documentations](https://www.keycloak.org/docs/latest/server_admin/)
+
+The below steps are examples used in BAND, if your client names are different, change accordingly.
+
+1.  create realm name 
+    1.  endpoints: OpenID Endpoint Configuration
+    2.  Login tabs: all OFF
+    3.  Themes: name_of_your_theme 
+2.  create following clients. 
+    1.  eosc-client
+        1.  set to ON for "Enabled, Standard Flow Enabled, Direct Access Grants Enabled", leave the rest OFF
+        2.  Valid redirect URIs:
+            1.  https://band.embl.de/*
+            2.  https://band.embl.de/eosc/*
+            3.  https://band.embl.de/eosc/api/linked
+            4.  create Token Mappers
+                *   email -> User Property, Token claim: email, Property: email
+                *   username ->User Property, Token claim: preferred\_username, Property: username
+                *   openid ->RealmProperty, Token claim: openid, Realm role prefix: openid
+                *   family name ->User Property, Token claim: family\_name, Property: lastName
+                *   full name -> User's full name
+                *   given name ->User Property, Token claim:given\_name, Property: firstName
+    2.  resource
+        1.  set to ON for "Enabled, Standard Flow Enabled, Direct Access Grants Enabled, Service Accounts Enabled, authorization Enabled", leave the rest OFF
+        2.  valid redirect URI
+            1.  https://band.embl.de/*
+            2.  https://band.embl.de/kc/api/*
+            3.  https://band.embl.de/resource
+            4.  create Token Mappers (same as eosc-client)
+        3.  service account roles. eosc and user role are created via Roles page
+            1.  eosc
+            2.  user
+            3.  offline\_access
+            4.  uma\_authorization
+        4.  Scope: full scope allowed
+3.  User Federation:
+    1.  these are settings connect to ldap server
+        1.  username LDAP attribute: uid
+        2.  RDN: cn
+        3.  UUID: uid
+        4.  User object classes: inetOrgPerson, organizationalPerson
+        5.  user DN:ou=users,dc=eosc-life,dc=eu #CHANGE TO YOUR OWN LDAP
+        6.  connection URL: YOUR_LDAP_SERVER_ADDRESS
+        7.  authentication : simple
+        8.  bind DN: cn=admin,dc=eosc-life,dc=eu # CHANGE TO YOUR OWN ADMIN DN
+        9.  bind credential: YOUR_LDAP_BIND_PASSWORD
+        10.  custom user ldap filter: (objectClass=posixAccount)
+        11.  search scope: subtree
+        12.  use truststore spi: only for ldaps
+        13.  connection pooling: on
+        14.  pagination: on
+    2.  create Mappers
+        1.  gid -> group-ldap-mapper
+            1.  group dn: ou=groups,dc=eosc-life,dc=eu
+            2.  group name attribute: cn
+            3.  group object classes: posixGroup
+            4.  Membership attribute: memberUid
+            5.  membership attribute type: UID
+            6.  member user attribute: uid
+            7.  ldap filter: (objectClass=posixGroup)
+            8.  MemberOf ldap attribute: memberOf
+            9.  mode: read\_only
+            10.  retrieve strategy: load\_groups\_by\_member\_attribute
+        2.  modify date ->
+            1.  user model attribute: modifyTimestamp
+            2.  ldap attribute: modifyTimestamp
+            3.  readonly: on
+        3.  email -> 
+            1.  user model attribute: email
+            2.  ldap attribute: mail
+            3.  readonly: on
+        4.  username ->
+            1.  user model attribute: username
+            2.  ldap attribute: uid
+            3.  readonly: on
+            4.  mandatory: on
+        5.  last name ->
+            1.  user model attribute: lastName
+            2.  ldap attribute: sn
+            3.  readonly: on
+            4.  mandatory: on
+        6.  creation date ->
+            1.  user model attribute: createTimestamp
+            2.  ldap attribute: createTimestamp
+            3.  readonly: on
+        7.  full name ->
+            1.  full name attribute: cn
+            2.  readonly :on
+        8.  givenName ->
+            1.  model attribute: firstName
+            2.  ldap attribute: givenName
+            3.  readonly:on
+            4.  mandatory: on
+4.  Authentication 
+    1.  select EOSC First Broker Login from dropdown (If you named your extension differently, select accordingly)
+    2.  Create EOSC User If Unique : alternative
+    3.  Link IDP Login: alternative
+    4.  Bindings: browser, registration, direct grant, reset credentials, clients
\ No newline at end of file