====== Keycloak as (SAML) SSO-Authentication provider for Nextcloud ======

We can use Keycloak as SSO (Single Sign On) authentication provider for nextcloud using SAML. <del>Unfortunately the SAML plugin for nextcloud doesn't support groups (yet?). If you need/want to use them, you can get them over LDAP. Therefor you want to use [[:linux_server_manuals:keycloak_openldap_integration|LDAP federation in Keycloak]] and before setting up the SAML authentication, set up the [[:linux_server_manuals:nextcloud_ldap_integration| LDAP connection in Nextcloud.]]</del> Newer Versions of the SAML plugin are able to get the groups from Keycloak and also to restrict by them. Unfortunately they aren't able to get first and last name from keycloak, but expect the Full Name (Displayname) to be provided. Which keycloak in the newer versions doesn't provide in an easy way (You need to upload your own SPI).

Before anything else you should have a working Keycloak installation ;-) : [[:linux_server_manuals:docker_keycloak_container_with_local_postgresql|]]

===== Nextcloud configuration =====

Before you configure nextcloud, create a self signed x.509 certificate, you'll need it in the next step. The cn and other details you enter for it, don't really matter. That certificate will be used by nextcloud to sign its request and proof to keycloak that it is allowed to authenticate against it.
<code>

openssl req  -nodes -new -x509  -keyout private.key -out public.cert

</code>

Then in Nextcloud, install and activated the plugin **user_saml**. Go to the Admin section **SSO & SAML authentication** and setup a new SAML connection with following settings. Some of the settings are hidden and you need to click first **Hide/Show … Setting**:

^Setting^Value^Comment|
|**Attribute to map the UID to** |username| |
|**Only allow authentication if acount exists … ** | |Enable it if you want LDAP for group permission, otherwise disable it|
|**X.509 Certificate of Service provider ** | |This one is kinda difficult to discover. Behind "Service Provider data" click "Hide Service Provider settings …". Copy here the content from the above generated public.cert with or without the "–begin …" and "–end …" lines. Alternatively you can also leave that empty, do all the other steps, activate in keycloak **Client Signature Required**, save and then copy the private and public key from the tab **SAML keys** to nextcloud. But I think the way described here is more straight forward, and you won't need to change any special settings in Keycloak like that.|
|**Private Key of service provider ** | |Copy here the content from privat.key|
|**Identifier of IdP entity** |<nowiki>https://auth.example.com/realms/{realm-name} </nowiki>|replace {realm-name} with your realm name|
|**URL target of the IdP …** |<nowiki>https://auth.example.com/realms/{realm-name}/protocol/saml</nowiki>| |
|**URL location of the IdP for SLO ** |<nowiki>https://auth.example.com/realms/{realm-name}/protocol/saml</nowiki>| |
|**Public x.509 certificate of the IdP** | |Copy here the public certificate of keycloak which you can find in **realm settings/keys/rs256/certificate**   |
|**Attribute to map the email to** |email| |
|**Attribute to map the User groups to** |Role|if you want to get the roles from keycloak. if you want to get the groups, use member, otherwise leave empty|
|**Indicates whether the <samlp:AuthnRequest> messages sent by this SP will be signed.** |enabled| |
|**Indicates whether the <samlp:logoutRequest> messages sent by this SP will be signed.** |enabled| |
|**Indicates whether the <samlp:logoutResponse> messages sent by this SP will be signed.** |enabled| |
|**Indicates a requirement for the <samlp:Response>, <samlp:LogoutRequest> and <samlp:LogoutResponse> elements received by this SP to be signed.** |enabled| |
|**Indicates a requirement for the <saml:Assertion> elements received by this SP to be signed.** |enabled| |

You could do the whole thing, also without the certificates, and without requiring the the SP or the IdP to sign their requests and responses, but without doing that, neither the IdP nor the SP are sure it the other one, is really the one he pretends to be. I'm not a SAML specialist, and I'm definitely not planing to become one, so I'm not completely sure, which parts should be signed, and which ones aren't important. So we just sign everything we can ;-) . Since we believe in HTTPS encryption, I didn't activate any of the encryption options.

Then click an **Download metadata XML** and save the file, you'll need it for Keycloak.
===== Keycloak configuration =====

In keycloak go to clients and choose "Import Client". Upload the previously downladed **medata.xml** and click ok.

Then go to the **Client scopes** tab and delete the **roles_list** scope. It won't work since it is not configured as <b>Single Role Attribute</b> it will lead a <b>Duplicated Attribute Error</b> in Nextcloud.\\
Now below Assigned client scope click on the URL **<nextcloud-url>/index.php/apps/user_saml/saml/metadata-dedicated** (a bold UI Design decision… only took me hours to find that. Hopefully that will be changed in Keycloak > 21).

 Then create multiple new mappers: **add Mapper/by configuration/User Property**:\\

^setting^value|
|**name** |username|
|**property** |username|
|**SAML attribute name** |username|
|**SAML attribute name format** |basic|

^setting^value|
|**name** |email|
|**property** |email|
|**SAML attribute name** |email|
|**SAML attribute name format** |basic|

If you want to map the roles or groups to nextcloud add a **Role list** respectively **Group list** mapper (instead of User property).

^setting^value|
|**name** |role list|
|**
Role attribute name ** |Role|
|**SAML attribute name format** |basic|
|**
Single Role Attribute ** |on|

So now everything should be working. Try to log in. If it doesn't work check out the nextcloud log file and the keycloak log.