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"
}