Commit 823ec8a2 authored by Martin's avatar Martin
Browse files

fix conflicts

parents fb4ade61 3122daef
# SAML
## Rocket.Chat Settings Page
### Custom Provider (Suffix to SP entityID)
This is the unique name for your application as a Service Provider (SP) for SAML. Whatever you enter here produces a metadata XML file you need in order to populate the metadata your IdP (Identity Provider) requires. For example, if you put 'my-app', then your metadata will be at:
`https://my-rocketchat-domain.tld/_saml/metadata/my-app`
### Custom Entry Point (IDP SSO Redirect URL)
This is the URL provided by your IdP for logging in. In SAML-terminology, it refers to the location (URL) of the SingleSignOnService with the Redirect binding (urn:oasis:names:tc:SAML:2.0:bindings:HTTP-Redirect).
### 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 (SP entityID)
The URI that 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`
### Custom Certificate (IdP Signing Certificate)
This is the Identity providers public certificate. It is used by rocketchat to verify the SAML requests (response) validity. Format is PEM **WITHOUT** `-----BEGIN CERTIFICATE-----` and `-----END CERTIFICATE-----`.
### Public Cert Contents (SP Signing Certificate)
The public part of the self-signed certificate you created for encrypting your SAML transactions. Format is PEM **WITH** `-----BEGIN CERTIFICATE-----` and `-----END CERTIFICATE-----`.
See [Example of self-signed certificate on the SimpleSAMLphp website here.](https://simplesamlphp.org/docs/stable/simplesamlphp-sp#section_1_1) on how to create the resp. keys.
### Private Key Contents (SP Signing Private Key)
The private key part of the SP Signing Certificate. It is used to encrypt your
SAML requests. Format is PEM **WITH** `-----BEGIN PRIVATE KEY-----` and `-----END PRIVATE KEY-----`.
### SAML Assertion
You must to send the **Email** field in your assertion, or it doesn't work. When the email matches the existing user, it overwrites the user's username with the username value, if that is in your assertion.
## SimpleSAMLphp IdP Configuration
As a popular open source IdP, SimpleSAMLphp can be used to provide an authentication endpoint for Rocket.Chat and the build in SAML support. Assuming that you have a SimpleSAMLphp IdP up and running - [quickstart instructions here](https://simplesamlphp.org/docs/stable/simplesamlphp-idp), you can find the metadata for the Rocket.Chat SAML Service Provider (SP) here, where 'my-app' is whatever you put in the **Custom Provider** box in the Rocket.Chat SAML admin page:
`https://my-rocketchat-domain.tld/_saml/metadata/my-app`
1. Copy the XML on this page
2. Open the metadata converter page in your SimpleSAMLphp admin UI found at: `/admin/metadata-converter.php`
3. Paste the XML, and submit it
4. Copy the resulting PHP output to the file in your SimpleSAMLphp installation under metadata: `/metadata/saml20-sp-remote.php`
5. You should now see your SP on the SimpleSAMLphp Federation page, listed as a trusted SAML 2.0 SP at: `module.php/core/frontpage_federation.php`
## IdP Attribute Mapping
Use the following attributes required to return user information to Rocket Chat:
| Idp Returned Attribute Name | Usage |
| --------------------------- | -------------------- |
| cn | User's Full Name |
| email | User's Email Address |
| username | User's username |
# Keycloak SAML Client
In order to properly configure the SAML connection between Keycloak and Rocketchat, we need the following parameters:
* The `rocketchat-url` where your rocketchat service (i.e. the Service Provider or SP) is being served. We will assume `https://rocketchat.your.server/chat`.
* The `keycloak-url` where your keycloak service (i.e. the Identity Provider or IdP) is being served
* The `keycloak-realm` you are creating your client in
* A `custom-issuer` (Service Provider EntityID), that is a name for your rocketchat-service. We will assume `rocketchat-saml`.
## Configuring Keycloak Identity Provider
Create a new client in your `<keycloak-realm>`.
1. Set the *Client ID*: `<custom-issuer>`
2. Select the *Client protocol*: `saml`
3. Set *Client SAML Endpoint*: `<rocketchat-url>/_saml/metadata/<custom-issuer>`
4. Deactivate the option *Client Signature Required*
5. Set a *Valid Redirect URIs* value like `<rocketchat-url>/*`
The following image shows this basic configuration (nevermind the different option settings):
![Keycloak SAML Configuration Basic][Keycloak SAML Configuration Basic]
## Configuring Rocketchat SAML
Login to Rocket.Chat with an administrator account and navigate to SAML page.
1. Set *Custom Provider* to `<custom-issuer>`
2. Set *Custom Entry Point* to `<keycloak-url>/auth/realms/ElexisEnvironment/protocol/saml`
3. Set *IDP SLO Redirect URL* to `<keycloak-url>/auth/realms/ElexisEnvironment/protocol/saml`
4. Set *Custom Issuer* to `<custom-issuer>`
### Optional (recommended)
To validate that the correct IdP signed the SAML, set *Custom Certificate (IDP Signing Certificate)* to the `<keycloak-realm>` RS256 certificate. The respective certificate can be found here: ![Keycloak SAML Realm RS256 Certificate]
## Caveat
* End SAML session setup currently does not seem to work correctly, see https://github.com/RocketChat/Rocket.Chat/issues/14881
## Open Topics
* Mapping of Attributes
* Certs (?) - what about them??
[Keycloak SAML Configuration Basic]: keycloak-saml-configuration-basic.png
[Keycloak SAML Realm RS256 Certificate]: keycloak-saml-realm-256-certificate.png
Markdown is supported
0% or .
You are about to add 0 people to the discussion. Proceed with caution.
Finish editing this message first!
Please register or to comment