Page Comparison

...

• allowAnonymous

  • By default, every user will have to login before they can access anything. By setting allowAnonymous to true users can access Weave, as an anonymous user, without having to login.

• logRequests

  • Certain HTTP headers are utilised when performing the SAML authentication process but logging those headers continually would pollute the Weave log with information that would be useless most of the time. So you can set logRequests to true while trying to debug authentication issues.

• includePaths

  • includePaths can be set to a comma-separated list of URL patterns that should always be forced to be authenticated via SAML, even if allowAnonymous us set to true. Any request URL that matches one of the entries in includePaths will be required to be authenticated before it is processed by the server, either before the request is made or by performing the SAML authentication process as part of the request processing.

  • There’s no recommended value for the includePaths setting, but if you’re doing something like setting up a Weave server that’s just used by other servers and not as a user-facing Weave instance, then it could be useful for locking down the server in combination with excludePaths.

• excludePaths

  • excludePaths can be set to a comma-separated list of URL patterns that should never be authenticated via SAML, even if allowAnonymous is set to false. This is for things like server health check URL’s that need to be made available to monitor the server and you don’t want/need to perform authentication before processing the request.

  • The recommended value for excludePaths is: /metrics,/server/ping,/server/healthcheck,/server/health.do./server/mq.do

• includeBeforeExclude

  • Normally Weave checks the excludePaths list before the includePaths list to determine if a given request should be forced to be authenticated or forced to not be authenticated. You can reverse this check so that includePaths is checked first then excludePaths by setting includeBeforeExclude to true.

  • This setting is provided because both includePaths and excludePaths can include wildcards and you may wish to include a more permissive value in one list whilst including a more specific value(s) in the other list. By providing this setting, you can determine which list it is easier make permissive and which one to make more specific.

• roleFilter.*

  • You can add a number of roleFilter entries to ensure that a user has a particular roles before they can access the given url.

  • Any suffix can be used for the filter name, and the values are applied in alphabetical order based on the filter name (not the order listed)

  • The value for each filter should contain a URL path to match followed by an equals sign followed by a comma-separated list of roles that the user must have at least one of before they can access the given path

  • This should be done for at least the Admin UI (replacing ROLE_ADMIN with the role that admin users will have)

  • This is only available with version 12.0.4 or later of the Keycloak security plugin

• userProperties

  • The path to a user properties file that can be used to replace the roles assigned to users

  • If the user is listed in this file then the roles assigned in this file will completely replace those provide by the SAML server, that is, there is currently no way to assign additional roles, or remove individual roles from those provided by the SAML server.

  • The file should contain a single line for each user in the format:

    • username@domain.name=role1,role2,…,roleN

  • Note that that is assuming that the usernames returned from the SAML server contain a domain, e.g. @domain.name in the above example, if the SAML server isn’t returning the domain in the username then it does not need to be included in the user properties file.

  • If one of the roles, or the only role, listed for the user is “disabled” then the user will be provided with no roles, this can be used to override what’s in the SAML server and disable access for the user

• userPropertiesHasPassword

  • If the user properties file specified by the userProperties setting has been copied from an existing users.properties file then file will likely contain passwords that aren’t used by Keycloak and should be ignored as a “role” assigned to the user when reading the file. So if this property is set to “true” then it indicates that the Keycloak user properties file does contain a password and the password should be ignored, but if this property either isn’t set or is set to anything other than “true” then it indicates that the Keycloak user properties file does not contain a password

• userPropertiesHasDomain

  • This flag indicates that the usernames stored in the Keycloak user properties file contain a domain for the user, i.e. the user is listed as “user@example.com=…” rather than just “user=…”.

  • Most times the username returned from the SAML server will contain the domain and the Keycloak user properties file should be setup so that each user entry also contains a domain, this setting is primarily intended to make it easy to migrate an existing users.properties file, and can likely be ignored if you’re creating a new Keycloak user properties file from scratch, in which case you’d include the full username, including the domain, in the file

  • If this property is set to “true” or not set at all then it’s assumed that the Keycloak user properties file contains the domain for a user, if this property is set to “false” then it’s assumed that the Keycloak user properties file does not contain a domain for the user, which may be the case if the file is copied from an existing users.properties file.

  • This may be required to be explicitly set to false if you’re copying an existing users.properties file that doesn’t contain a domain but the SAML server is returning usernames that do contain a domain. Note that this assumes that the user names listed in the file (without a domain) are unique, which may not be the case, in which case the file should be updated to include the domain for each user and this property not be set (or set to true).

• defaultRoles

  • A comma-separated list of roles that the user will be assigned if the SAML provider does not return any roles when the user logs in.

  • This does not effect anonymous logins, anonymous users won’t get any additional roles, and doesn’t allow users who are not able to authenticate via SAML any access.

  • This is useful if you want to use SAML authentication to restrict access to Weave, so users have to log in, but you don’t use any special roles (e.g. everyone just gets ROLE_USER) to then alter what the user has access to and don’t want to or can’t to setup all of the role in the SAML provider.

• stripDomain

  • If the user name is an email address and you want to remove the domain from the email address for the username (and don’t want to or can’t do it via the SAML provider) then you can set this to true to have Weave remove the email domain from the email address.

The following would be a recommended keycloak.properties file (if anonymous user access is also required)

allowAnonymous=true

excludePaths=/metrics,\
/server/ping,\
/server/healthcheck,\
/server/health.do,\
/server/mq.do,\
/report/remote

roleFilter.1=/admin.*=ROLE_ADMIN
roleFilter.2=/admin/**=ROLE_ADMIN

...

keycloak-saml.xml

keycloak-saml.xml (it can also be called just keycloak.xml) is the Keycloak specific XML configuration file documented here. The settings you need to specify in that file will be determined by the identity provider you’re using and will likely require assistance from someone familiar with that particular identity provider but is something that Cohga can provide assistance with.

One thing to note from the documentation linked above is that when it refers to external files, for example, a Java keystore containing certificates required to protect/verify communications with the SAML server, it’s assuming that those files are embedded within a “web application” and references those files relative to a WEB-INF directory. However, for Weave, those files are located adjacent to the keystore.properties file so do not require that the files are referenced relative to a WEB-INF directory.

...