Keycloak

Keycloak supports multiple authentication realms, so you must first select the appropriate realm for your organization. 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://knocknoc.example.com. If you are using a cloud server, replace with your own URL, or if you are using an on-premises server, this is the base URL to your Knocknoc server.

Knocknoc SAML config

• Public URL: https://knocknoc.example.com
• 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").

Metadata file: the idp-metadata.xml downloaded in the Mellon package from Keycloak

A signing key and certificate are required under Key and Cert files. Knocknoc generates a self-signed pair when you save if you do not supply your own. They are unused once you turn off Keycloak > Client > Keys >  "Client signature required".

Keycloak config

• Change to your realm (e.g. Acme, not master)
• Create client
  • Type: SAML
  • Client ID: https://knocknoc.example.com/api/saml/metadata
  • (Accept defaults, save)
• Settings tab
  • Name: e.g. Knocknoc
  • Root URL: https://knocknoc.example.com
  • Home URL: https://knocknoc.example.com/api/login/saml
  • Valid redirect URI: /api/saml/acs
  • Master SAML processing URL: https://knocknoc.example.com/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
  • Optimize 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:
  • Edit the "dedicated scope and mappers for this client" / https://knocknoc.example.com/api/saml/metadata-dedicated and add in mappers:
    • 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 minutes
    • groups
      • Mapper type: Group list
      • Name: groups
      • Group attribute name: groups
      • SAML attribute NameFormat: Basic
      • Single Group Attribute: on
      • Full group path: off
  • The client scope "role_list" should already exist by default
• Advanced tab
  • Authentication flow overrides
    • Browser Flow: browser