rocket.chat-server-settings.md

Rocket.Chat server settings

Connection

• Enable: Enables the SAML connection
• Custom Provider: The SAML provider name
• Custom Entry Point: The custom entry point
• IDP SLO Redirect URL: This is the URL provided by your IdP for logging out. In SAML-terminology, it refers to the location (URL) of the SingleLogoutService with the Redirect binding (urn:oasis:names:tc:SAML:2.0:bindings: HTTP-Redirect)
• Custom Issuer: The URI is the unique identifier of your service. By convention, this is also the URL of your (unedited) metadata. Again, where you set Custom Provider to 'my-app', this will be: https://my-rocketchat-domain.tld/_saml/metadata/my-app
• Enable Debug: Set to true to enable debugging

Certification

• Custom Certificate: This is the public certificate for IdP providers used to verify SAML requests. The format for this is PEM without -----BEGIN CERTIFICATE----- and --

• Public Cert Contents: The public part of the self-signed certificate you created for encrypting your SAML transactions. Example of self-signed certificate on the SimpleSAMLphp website here.

  Format for this is PEM WITH -----BEGIN CERTIFICATE----- and -----END CERTIFICATE-----

• Signature Validation Type: Select the type of signature validation. This setting will be ignored if no Custom Certificate is provided.

• Private Key Contents: The private key matches the self-signed certificate you created as PKCS#1 PEM. Format for this is PEM WITH -----BEGIN PRIVATE KEY----- and -----END PRIVATE KEY-----.

Enterprise

Roles

• Sync User Roles: Enable to sync user roles on login (overwrites local user roles).
• Role Attribute Name: If this attribute is found on the SAML response, its values will be used as role names for new users.

Advanced

• Identifier Format: Format of the identifier. Leave this empty to omit the NameID Policy from the request

• NameID Policy Template: The NameID policy template. You can use any variable from the Authorize Request Template here.

• Custom Authn Context: Leave this empty to omit the authn context from the request.

  To add multiple authn contexts, add the additional ones directly to the AuthnContext Template setting.

• Authn Context Comparison: Select the Authn context comparison method

• AuthnContext Template: You can use any variable from the AuthnRequest Template here.

  To add additional authn contexts, duplicate the AuthnContextClassRef tag and replace the __authnContext__ variable with the new context.

• AuthnRequest Template: The following variables are available:

  • __newId__: Randomly generated id string
  • __instant__: Current timestamp
  • __callbackUrl__: The Rocket.Chat callback URL.
  • __entryPoint__: The value of the Custom Entry Point setting.
  • __issuer__: The value of the Custom Issuer setting.
  • __identifierFormatTag__: The contents of the NameID Policy Template if a valid Identifier Format is configured.
  • __identifierFormat__: The value of the Identifier Format setting.
  • __authnContextTag__: The contents of the AuthnContext Template if a valid Custom Authn Context is configured.
  • __authnContextComparison__: The value of the Authn Context Comparison setting.
  • __authnContext__: The value of the Custom Authn Context setting.

• Logout Response Template: The following variables are available:

  • __newId__: Randomly generated id string
  • __inResponseToId__: The ID of the Logout Request received from the IdP
  • __instant__: Current timestamp
  • __idpSLORedirectURL__: The IDP Single LogOut URL to redirect to.
  • __issuer__: The value of the Custom Issuer setting.
  • __identifierFormat__: The value of the Identifier Format setting.
  • __nameID__: The NameID received from the IdP Logout Request.
  • __sessionIndex__: The sessionIndex received from the IdP Logout Request.

• Logout Request Template: The following variables are available:

  • __newId__: Randomly generated id string
  • __instant__: Current timestamp
  • __idpSLORedirectURL__: The IDP Single LogOut URL to redirect to.
  • __issuer__: The value of the Custom Issuer setting.
  • __identifierFormat__: The value of the Identifier Format setting.
  • __nameID__: The NameID received from the IdP when the user logged in.
  • __sessionIndex__: The sessionIndex received from the IdP when the user logged in.

• Metadata Certificate Template: The following variables are available:

  • __certificate__: The private certificate for assertion encryption.

• Metadata Template: The following variables are available:

  • __sloLocation__: The Rocket.Chat Single LogOut URL.
  • __issuer__: The value of the Custom Issuer setting.
  • __identifierFormat__: The value of the Identifier Format setting.
  • __certificateTag__: If a private certificate is configured, this will include the Metadata Certificate Template, otherwise it will be ignored.
  • __callbackUrl__: The Rocket.Chat callback URL.

Mapping

• User Data Custom Field Map: Configure how user custom fields are populated from a record in SAML (once found).

General

User Interface

• Button Text: Text to display on the button
• Button Text Color: Lets you set the button text color
• Button Color: The button color

Behavior

• Generate Username: Enable to generate username
• Normalize username: Set the type of normalization to perform on a username
• Immutable field name: Select the field name to be immutable
• Overwrite user fullname (use idp attribute): Enable to overwrite user fullname
• Overwrite user mail (use idp attribute): Enable to overwrite user mail
• Logout Behaviour: Lets you set the behavior to happen on logout
• Update Room Subscriptions on Each Login: When enabled, room subscriptions is updated on each login. Ensures the user is a member of all channels in SAML assertion on every login.
• Include Private Rooms in Room Subscription: When set to true, private rooms are able to use for a subscription. Adds a user to any private rooms that exist in the SAML assertion.
• Default User Role: Lets you set the default user role. You can specify multiple roles, separating them with commas.
• Allowed clock drift from Identity Provider: The clock of the Identity Provider may drift slightly ahead of your system clocks. You can allow for a small amount of clock drift. Its value must be given in a number of milliseconds (ms). The value given is added to the current time at which the response is validated.

Mapping

• User Data Field Map: Configure how user account fields (like email) are populated from a record in SAML (once found). As an example, {"name":"cn", "email":"mail"} chooses a person's human-readable name from the cn attribute, and their email from the mail attribute. Available fields in Rocket.Chat: name, email and username. Everything else is discarded.

"email": "mail",
  "username": {
    "fieldName": "mail",
    "regex": "(.*)@.+$",
    "template": "user-__regex__"
  },
  "name": {
   "fieldNames": [
      "firstName",
      "lastName"
    ],
    "template": "__firstName__ __lastName__"
  },
  "__identifier__": "uid"
}