SSO SAML with Keycloak

[VincentSC]

Generally works. Not done yet:

• Logging out
• mapping Location, Phone and Title

Keycloak

Settings:

• client ID: https://<domain>/sso/metadata
• name: OnlyOffice
• root url: https://<domain>/sso/acs
• home url: https://<domain>/sso/acs
• Valid redirect URIs: https://<domain>/sso/acs
• Valid post logout redirect URIs: https://<domain>/sso/slo/callback
• Name ID format: email
• Force POST binding: on (else it seems not to work)
• Sign documents: on
• Sign assertions: on
• Signature algorithm: RSA_SHA256 (or RSA_SHA512)

Keys:

• Client signature required: off
• Encrypt assertions: generate. Use the public key (shown) and private key (automatically downloaded) for the "SP Certificates" of OnlyOffice. Possibly a key generated by OnlyOffice might also work, but did not test this. Leave this off initially, to check if the rest works!

Client Scopes:

• go to https://<domain>/sso/metadata-dedicated
• Add these predefined mappers: email, givenName and surName.
• Set the "SAML Attribute NameFormat" of each mapper to "URI reference". Using basic names seemingly does not work.

OnlyOffice

• Load metadata from https://<keycloak-base>/realms/master/protocol/saml/descriptor
• Optionally change the bindings to POST. Watch out: OnlyOffice empties what's filled in!
• Change NameID format to email
• Default Signature Verification Algorithm: rsa-sha256 (same as configured in Keycloak)
• Use SP Certificates (public and private key) generated by Keycloak. Leave this off initially, to check if the rest works!
  • Be sure to add the -----BEGIN CERTIFICATE-----, -----END CERTIFICATE-----, -----BEGIN RSA PRIVATE KEY----- and -----END RSA PRIVATE KEY-----, else OnlyOffice will not accept.
  • Pick "rsa-sha1" and "aes256-cbc" - others might also work - I noticed that I could just change "aes128-cbc" to "aes256-cbc" and everything kept working.
  • Select "signing and encrypt"
• Attribute mapping. These can also be copied from Keycloak. Using basic names did not work for me.
  • First name: urn:oid:2.5.4.42
  • Last name: urn:oid:2.5.4.4
  • Email: urn:oid:1.2.840.113549.1.9.1
  • Empty Location, Phone and Title

Debugging

In onlyoffice-community-server you'll find the only interesting logging:

tail -n 50 -f /var/log/onlyoffice/web.sso.<date>.log

Feedback welcome on:

• How to get log-out working
• How to do mapping with Simple names
• General improvements of the above

[georgy-k852]

Hello! Thank you for your tutorial. Unfortunatlly, can not use the first step: "Load metadata from https:///auth/realms/master/protocol/saml/descriptor". Please, can you explain what should I full in this gaps:

• IdP Entity ID
• IdP Single Sign-On Endpoint URL
• IdP Single Logout Endpoint URL
• NameID Format It would be great if you are able to attach image explonation of using OnlyOffice SSO Control panel (screenshot).

[VincentSC]

Can not use the first step: "Load metadata from https:///auth/realms/master/protocol/saml/descriptor".

I fixed the text. The <domain> and <keycloak-base> parts were removed at some places. I hope you understood that you need to replace these parts with data from your environment. See for example https://www.itsfullofstars.de/2020/02/keycloak-download-saml-2-0-idp-metadata/ how to get the SAML descriptor, if the url does not work.

Do know that this is quite basic knowledge for Keycloak-administration. I therefore strongly suggest you read a bit further, to prevent from making some serious mistakes.

[DanilfromRussia]

Hello! Thank you for your tutorial. I encountered an endless redirect after successful authorization (user session is displayed in keycloak -> Clients -> Sessions). I analyzed the connection with the SAML-Tracer tool and saw a infinity loop of the following picture.

Can you see anything errors? Or maybe you got this err, thank you very mutch

[YuanZhencai]

@VincentSC I want to add additional parameters during SSO login, such as kc_idp_hint=github. What should I do

[VincentSC]

@YuanZhencai I don't know, as I'm not using that myself. Sorry.

[benjamin-kirkbride]

Anyone get logging out to work?

[ZAZmaster]

Anyone get logging out to work?

In my case i use all of first post but with some:

Keycloak

• Home URL: /
• Force POST binding: On
• Signature algorithm: RSA_SHA256

OnlyOffice

• Bindings: POST

Check all checkbox about sign logout responses/requests

[ZAZmaster]

• mapping Location, Phone and Title If you map this attributest from ldap to keycloak, then it simply to add from Client Scopes. Add mapper by configuration, and name it as mapped attribute, use SAML Attribute Names: Location urn:oid:1.3.6.1.4.1.6822.1.1.5 Phone urn:oid:2.5.4.20 Title urn:oid:2.5.4.12 Then use it in OnlyOffice SSO Attribute mapping

[yuting-zhang11]

Is adding new SSO user work? After I config, the user who already in onlyoffice can log in by SSO successfully. But the new SSO user can not be created.

[yuting-zhang11]

Solved. My new user does not set a first name and a last name. After I added, it works.

[VincentSC]

We had a problem with a disappeared SP certificate in Keycloak.

Errors - in case we get it again:

• Missing SP certificate: {"message":"onLoginResponse The first argument must be of type string or an instance of Buffer, ArrayBuffer, or Array or an Array-like Object. Received undefined","level":"error"}
• Incorrect SP certificate: {"message":"onLoginResponse ERR_EXCEPTION_OF_ASSERTION_DECRYPTION","level":"error"}
• Decrypt Assertions" not on: {"message":"parseLoginResponse failed ERR_EMPTY_ASSERTION","level":"error"}