SAML with Keycloak

** This document is a work in progress 

Keycloak supports multiple authentication realms, so you must first select the appropriate realm for your organisation. Do not make any of the below changes in the Keycloak/master realm.

In this example our realm is called "Acme" and Keycloak is hosted at https://auth.example.com/.

Our Knocknoc instance is a cloud instance with URL https://keycloaktest.knoc.cloud. If you are using a cloud server, replace with your own URL, or if you are using an on-premise server, this is the base URL to your Knocknoc server.

Knocknoc SAML config

• Public URL: https://keycloaktest.knoc.cloud
• Metadata URL https://auth.example.com/realms/Acme/protocol/saml/descriptor (you can get this from Keycloak > Acme realm > Realm settings > General tab > Endpoints section > "SAML 2.0 Identity Provider Metadata").

SamlMetadataFile the idp-metadata.xml downloaded in the Mellon package from Keycloak

SamlKeyFile and SamlCertFile are currently required fields in Knocknoc but unused once you turn off Keycloak > Client > Keys >  "Client signature required"

So if we do a "choose SAML" provider option for Keycloak maybe these could be omitted or not mandatory

Keycloak config

• Change to your realm (e.g. Acme, not master)
• Create client
• Type: SAML
• Client ID: https://keycloaktest.knoc.cloud/api/saml/metadata
• (Accept defaults, save)
• Settings tab
• Name: e.g. Knocknoc
• Root URL: https://keycloaktest.knoc.cloud
• Home URL: https://keycloaktest.knoc.cloud/api/login/saml
• Valid redirect URI: /api/saml/acs
• Master SAML processing URL: https://keycloaktest.knoc.cloud/api/saml/acs
• Name ID format: persistent
• Force name ID format: off
• Force POST binding: off
• Force artifact binding: off
• Include AuthnStatement: on
• Include OneTimeUse Condition: off
• Optimise REDIRECT signing key lookup: off
• Allow ECP flow: off
• Sign documents: on
• Sign assertions: on
• Signature algorithm: RSA_SHA256
• SAML signature key name: KEY_ID
• Canonicalization method: EXCLUSIVE
• Keys tab
• Client signature required: off
• Encrypt assertions: off
• Roles tab: -
• Client scopes tab:
  • realName
  • Mapper type: user attribute
  • name: realName
  • User attribute: select the user attribute containing their name
  • Friendly name: realName
  • SAML attribute name: realName
  • nameid
  • Mapper type: User attribute mapper for NameID
  • name: nameid
  • Name ID format: urn:oasis:names:tc:SAML:2.0:nameid-format:persistent
  • User attribute: email
  • sessionDuration
  • Mapper type: user attribute
  • Name: sessionDuration
  • User attribute: select the user attribute containing the Knocknoc session duration in seconds
• Edit the "dedicated scope and mappers for this client" / https://keycloaktest.knoc.cloud/api/saml/metadata-dedicated and add in mappers:
• The client scope "role_list" should already exist by default
• Advanced tab
  • Browser flow: browser
• Authentication flow overrides