Commit 0492569e authored by Martin Schoeler's avatar Martin Schoeler
Browse files

Revert "GitBook: [master] 1,035 pages modified"

This reverts commit 33fcdb03.
parent 33fcdb03
......@@ -8,19 +8,19 @@ In the interest of fostering an open and welcoming environment, we as contributo
Examples of behavior that contributes to creating a positive environment include:
* Using welcoming and inclusive language
* Being respectful of differing viewpoints and experiences
* Gracefully accepting constructive criticism
* Focusing on what is best for the community
* Showing empathy towards other community members
- Using welcoming and inclusive language
- Being respectful of differing viewpoints and experiences
- Gracefully accepting constructive criticism
- Focusing on what is best for the community
- Showing empathy towards other community members
Examples of unacceptable behavior by participants include:
* The use of sexualized language or imagery and unwelcome sexual attention or advances
* Trolling, insulting/derogatory comments, and personal or political attacks
* Public or private harassment
* Publishing others' private information, such as a physical or electronic address, without explicit permission
* Other conduct which could reasonably be considered inappropriate in a professional setting
- The use of sexualized language or imagery and unwelcome sexual attention or advances
- Trolling, insulting/derogatory comments, and personal or political attacks
- Public or private harassment
- Publishing others' private information, such as a physical or electronic address, without explicit permission
- Other conduct which could reasonably be considered inappropriate in a professional setting
## Our Responsibilities
......@@ -40,5 +40,8 @@ Project maintainers who do not follow or enforce the Code of Conduct in good fai
## Attribution
This Code of Conduct is adapted from the [Contributor Covenant](http://contributor-covenant.org), version 1.4, available at [http://contributor-covenant.org/version/1/4](http://contributor-covenant.org/version/1/4/)
This Code of Conduct is adapted from the [Contributor Covenant][homepage], version 1.4, available at [http://contributor-covenant.org/version/1/4][version]
[homepage]: http://contributor-covenant.org
[version]: http://contributor-covenant.org/version/1/4/
# Documentation Contribution Guidelines
You can find the documentation guidelines in [here](contributing/documentation/)
You can find the documentation guidelines in [here](contributing/documentation)
\ No newline at end of file
MIT License
Copyright (c) 2015 - 2018 Rocket.Chat Technologies Corp
Permission is hereby granted, free of charge, to any person obtaining a copy
of this software and associated documentation files (the "Software"), to deal
in the Software without restriction, including without limitation the rights
to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
copies of the Software, and to permit persons to whom the Software is
furnished to do so, subject to the following conditions:
The above copyright notice and this permission notice shall be included in all
copies or substantial portions of the Software.
THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
SOFTWARE.
# Rocket.Chat Docs
This is the official repository for the Rocket.Chat Documentation.
This is the official repository for Rocket.Chat Documentation.
## Requirements
* Ruby >= 2.3 \(Recommended >= 2.5\)
* [bundler](https://bundler.io/) gem installed \(>= 1.17.3\)
- Ruby >= 2.3 (Recommended >= 2.5)
- [bundler](https://bundler.io/) gem installed (>= 1.17.3)
## Contributing
This is a quick guide on how to run the docs site locally, for a more in depth guide please look [here](contributing/documentation/).
This is a quick guide on how to run the docs site locally, for a more in depth guide please look [here](contributing/documentation).
## Installation
......@@ -19,7 +19,7 @@ Install `bundler` using your terminal, run:
$ gem install bundler --version 1.17.3
```
And install the dependencies \(also on terminal\):
And install the dependencies (also on terminal):
```bash
$ bundle install
......@@ -42,4 +42,3 @@ You should always lint your changes to find errors locally before pushing your c
```bash
$ mdl ./ -r ~MD004 -i -g
```
This diff is collapsed.
# Markdown Linter
# Markdown Linter
\ No newline at end of file
......@@ -2,25 +2,24 @@
If you are a server administrator, here are a few guides on how to setup your instance to your needs.
* [Account Settings](account-settings.md)
* [Authentication](authentication/)
* [Custom Emoji](custom-emoji.md)
* [Custom Fields](custom-fields.md)
* [Custom Sounds](custom-sounds.md)
* [Database-Migration](database-migration.md)
* [Email](email/)
* [Federation](federation.md)
* [File Upload](file-upload/)
* [Message Auditing](message-auditing.md)
* [Import](import/)
* [Integrations](integrations/)
* [Rocket.Chat Apps](rocket-chat-apps/)
* [Setting up Video Conferencing](setting-up-video-conferencing.md)
* [Livechat](livechat/)
* [Notifications](notifications/)
* [Permissions](permissions.md)
* [Plug-ins](plug-ins/)
* [Create the First Admin](create-the-first-admin.md)
* [Restoring an Admin](restoring-an-admin.md)
* [Managing Settings Via Environment Variables](settings-via-env-vars.md)
- [Account Settings](account-settings/)
- [Authentication](authentication/)
- [Custom Emoji](custom-emoji/)
- [Custom Fields](custom-fields/)
- [Custom Sounds](custom-sounds/)
- [Database-Migration](database-migration/)
- [Email](email/)
- [Federation](federation/)
- [File Upload](file-upload/)
- [Message Auditing](message-auditing/)
- [Import](import/)
- [Integrations](integrations/)
- [Rocket.Chat Apps](rocket-chat-apps/)
- [Setting up Video Conferencing](setting-up-video-conferencing/)
- [Livechat](livechat/)
- [Notifications](notifications/)
- [Permissions](permissions/)
- [Plug-ins](plug-ins/)
- [Create the First Admin](create-the-first-admin/)
- [Restoring an Admin](restoring-an-admin/)
- [Managing Settings Via Environment Variables](settings-via-env-vars/)
......@@ -4,52 +4,54 @@ In this section, you can modify various settings about the accounts of the users
In this guide, we will go over all settings in the _Accounts_ Section.
* **Allow anonymous read**: Setting this to true will allow people to use the chat without having to create an account or log in. Anonymous users will be only allowed to read messages on public channels.
* **Allow anonymous write**: This will allow Anonymous users to post messages on public channels.
* **Allow users to delete own account**: Setting this to true allows users to delete their account. When a user is deleted all their messages are deleted too.
* **Allow User Profile Change**: Setting this to false will block users from changing information on their profile.
* **Allow User Avatar Change**: Setting this to false will block users from changing their avatar.
* **Allow User Username Change**: Setting this to false will block users from changing their username.
* **Allow User Email Change**: Setting this to false will block users from changing their email
* **Allow User Password Change**: Setting this to false will block users from changing their password.
* **Login Expiration in Days**: After this number of days of inactivity the user will be logged out.
* **Show form-based Login**: Setting this to false will remove the login form from the login screen. This setting is useful when you are using a third-party login system.
* **Placeholder for email or username login field**: This will change the placeholder for the _email or username_ field on the login screen.
* **Placeholder for password login field**: This will change the placeholder for the _password_ field on the login screen.
* **Forget user session on window close**: This will log out users when they close the window containing Rocket.Chat
- **Allow anonymous read**: Setting this to true will allow people to use the chat without having to create an account or log in. Anonymous users will be only allowed to read messages on public channels.
- **Allow anonymous write**: This will allow Anonymous users to post messages on public channels.
- **Allow users to delete own account**: Setting this to true allows users to delete their account. When a user is deleted all their messages are deleted too.
- **Allow User Profile Change**: Setting this to false will block users from changing information on their profile.
- **Allow User Avatar Change**: Setting this to false will block users from changing their avatar.
- **Allow User Username Change**: Setting this to false will block users from changing their username.
- **Allow User Email Change**: Setting this to false will block users from changing their email
- **Allow User Password Change**: Setting this to false will block users from changing their password.
<!-- - __Custom Fields to Show in User Info__: link to dedicated custom field document -->
- **Login Expiration in Days**: After this number of days of inactivity the user will be logged out.
- **Show form-based Login**: Setting this to false will remove the login form from the login screen. This setting is useful when you are using a third-party login system.
- **Placeholder for email or username login field**: This will change the placeholder for the _email or username_ field on the login screen.
- **Placeholder for password login field**: This will change the placeholder for the _password_ field on the login screen.
- **Forget user session on window close**: This will log out users when they close the window containing Rocket.Chat
## Avatar
* **Resize Avatar**: Set this to true to resize users avatars to a predefined size. You need ImageMagick or GraphicsMagick installed on your server for this feature to work.
* **Avatar Size**: The desired size after the avatar resizing. The unit is pixels \(px\).
* **Set Default Avatar**: If this setting is set to true, Rocket.Chat will try to find a default avatar based on OAuth Account or Gravatar.
- **Resize Avatar**: Set this to true to resize users avatars to a predefined size. You need ImageMagick or GraphicsMagick installed on your server for this feature to work.
- **Avatar Size**: The desired size after the avatar resizing. The unit is pixels (px).
- **Set Default Avatar**: If this setting is set to true, Rocket.Chat will try to find a default avatar based on OAuth Account or Gravatar.
## Iframe
These settings are related to the Iframe Integration, please see the [Iframe integration page](../developer-guides/iframe-integration/) for more details.
These settings are related to the Iframe Integration, please see the [Iframe integration page](../../developer-guides/iframe-integration) for more details.
## Registration
* **Default username prefix suggestion**: This is the prefix that will be suggested when a user is creating a username.
* **Require Name For Signup**: If this is set to true, the name of the user will be required to create an account.
* **Require Password Confirmation**: If this is set to true, the user will have to input his password twice when registering.
* **Email Verification**: If this is set to true, users will have to confirm their email via a confirmation email sent to their email. \(For this setting work, the SMTP settings must be already set up. See [Email Configuration](email/setup.md)\)
* **Manually Approve New Users**: If this is set to true, new users will have to wait for a user with the `view-user-administration` permission to approve their account before using Rocket.Chat.
* **Allowed Domains List**: This will block emails with different domains than the ones on this list.
* **Blocked Domains List**: This will block emails with domains that are on this list.
* **Use Default Blocked Domains List**: Will block the email domains listed on this [file](https://github.com/RocketChat/Rocket.Chat/blob/develop/packages/rocketchat-lib/server/lib/defaultBlockedDomainsList.js)
* **Use DNS Domain Check**: When this is set to true, users won't be able to register with invalid domains.
* **Registration Form**: This will change how the registration form is presented. Currently, there are 3 options:
* Public: The form will be public and anyone will be able to access;
* Disabled: The form will be disabled and users won't be able to register through it;
* Secret URL: The form will be only accessible using a specific URL;
* **Registration Form Secret URL**: String to be added to the secret URL. Is recommended to use a random string for that. Example: `https://open.rocket.chat/register/[secret_hash]`.
* **Registration Form Link Replacement Text**: Text to be shown in place of the registration form when the registration form is disabled.
* **Registration with Authentication Services**: Set this to true to allow registration with third-party authentication services like Google or Twitter.
* **Default Roles for Authentication Services**: Default roles users will be given when registering through authentication services.
* **Password Reset**: Set this to true to allow users to reset their password.
- **Default username prefix suggestion**: This is the prefix that will be suggested when a user is creating a username.
- **Require Name For Signup**: If this is set to true, the name of the user will be required to create an account.
- **Require Password Confirmation**: If this is set to true, the user will have to input his password twice when registering.
- **Email Verification**: If this is set to true, users will have to confirm their email via a confirmation email sent to their email. (For this setting work, the SMTP settings must be already set up. See [Email Configuration](../email/setup))
- **Manually Approve New Users**: If this is set to true, new users will have to wait for a user with the `view-user-administration` permission to approve their account before using Rocket.Chat.
- **Allowed Domains List**: This will block emails with different domains than the ones on this list.
- **Blocked Domains List**: This will block emails with domains that are on this list.
- **Use Default Blocked Domains List**: Will block the email domains listed on this [file](https://github.com/RocketChat/Rocket.Chat/blob/develop/packages/rocketchat-lib/server/lib/defaultBlockedDomainsList.js)
- **Use DNS Domain Check**: When this is set to true, users won't be able to register with invalid domains.
- **Registration Form**: This will change how the registration form is presented. Currently, there are 3 options:
- Public: The form will be public and anyone will be able to access;
- Disabled: The form will be disabled and users won't be able to register through it;
- Secret URL: The form will be only accessible using a specific URL;
- **Registration Form Secret URL**: String to be added to the secret URL. Is recommended to use a random string for that. Example: `https://open.rocket.chat/register/[secret_hash]`.
- **Registration Form Link Replacement Text**: Text to be shown in place of the registration form when the registration form is disabled.
- **Registration with Authentication Services**: Set this to true to allow registration with third-party authentication services like Google or Twitter.
- **Default Roles for Authentication Services**: Default roles users will be given when registering through authentication services.
- **Password Reset**: Set this to true to allow users to reset their password.
## Two Factor Authentication
Here you can enable or disable Two Factor Authentication for users, and set for how long a token is valid.
# Authentication
* [CAS](https://rocket.chat/docs/administrator-guides/authentication/cas/)
* [LDAP](https://rocket.chat/docs/administrator-guides/authentication/ldap/)
* [Oauth](https://rocket.chat/docs/administrator-guides/authentication/oauth/)
* [SAML](https://rocket.chat/docs/administrator-guides/authentication/saml/)
* [Wordpress](https://rocket.chat/docs/administrator-guides/authentication/wordpress/)
- [CAS](https://rocket.chat/docs/administrator-guides/authentication/cas/)
- [LDAP](https://rocket.chat/docs/administrator-guides/authentication/ldap/)
- [Oauth](https://rocket.chat/docs/administrator-guides/authentication/oauth/)
- [SAML](https://rocket.chat/docs/administrator-guides/authentication/saml/)
- [Wordpress](https://rocket.chat/docs/administrator-guides/authentication/wordpress/)
## External Authentication
If you need to automatically login users from your own website you can look at [Iframe integration page](../../developer-guides/iframe-integration/) or you can use the REST API [Login](../../developer-guides/rest-api/authentication/login.md) in combination with [deeplinking](../../developer-guides/deeplink.md) and the resumeToken.
If you need to automatically login users from your own website you can look at [Iframe integration page](../../developer-guides/iframe-integration) or you can use the REST API [Login](../../developer-guides/rest-api/authentication/login/) in combination with [deeplinking](../../developer-guides/deeplink) and the resumeToken.
```text
```
# get the resumeToken from your REST API login - it's the authToken field
https://yourown.rocket.chat/home?resumeToken=abcd123456789
```
# CAS
Central Authentication Service \(CAS\) allows users to use one set of credentials to sign into many sites. Rocket.Chat comes preloaded with an easy-to-use method of integration with an existing CAS server.
Central Authentication Service (CAS) allows users to use one set of credentials to sign into many sites. Rocket.Chat comes preloaded with an easy-to-use method of integration with an existing CAS server.
## Set up
......@@ -8,17 +8,16 @@ These settings are in the `CAS` setting page under `Administration`.
**NOTE**: CAS by ja-sig requires SSL/TLS for all connections.
* SSO Base URL: `https://<<CAS_website_url>>/cas`
- SSO Base URL: `https://<<CAS_website_url>>/cas`
The SSO Base URL should point towards the URL of the CAS service. When in doubt, navigate to the CAS service and remove 'login' \(if existing\) from the end of the URL.
The SSO Base URL should point towards the URL of the CAS service. When in doubt, navigate to the CAS service and remove 'login' (if existing) from the end of the URL.
* SSO Login URL: `https://<<CAS_website_url>>/cas/login`
- SSO Login URL: `https://<<CAS_website_url>>/cas/login`
The SSO Login URL should point towards the CAS service login page. This is usually the SSO base URL with the suffix `/login`
* CAS Version: `(1.0|2.0)`
- CAS Version: `(1.0|2.0)`
Select the CAS version used by your CAS provider. Most modern providers use `CAS 2.0`
**NOTE**: You may have to allow your Rocket.Chat site to connect to your CAS, so the best approach is to use the CAS Management Service.
......@@ -4,46 +4,46 @@ To configure LDAP authentication, go to LDAP section of administration settings,
## Examples
* Domain = domain.com \(Active Directory Domain\)
* Group = CN=ROCKET\_ACCESS,CN=Users,DC=domain,DC=com \(Access Control Group\)
* Proxy User = rocket.service@domain.com or CN=rocket service,CN=Users,DC=domain,DC=com \(DN or userPrincipalName\)
* Proxy User password = urpass \(Proxy Users password
- Domain = domain.com (Active Directory Domain)
- Group = CN=ROCKET_ACCESS,CN=Users,DC=domain,DC=com (Access Control Group)
- Proxy User = rocket.service@domain.com or CN=rocket service,CN=Users,DC=domain,DC=com (DN or userPrincipalName)
- Proxy User password = urpass (Proxy Users password
For now \(until we add more input fields to LDAP\) set it like this: \(This is based on the above assumptions, replace with your environment\)
For now (until we add more input fields to LDAP) set it like this: (This is based on the above assumptions, replace with your environment)
## Log on with username
* LDAP\_Enable = True
* LDAP\_Dn = dc=domain,dc=com
* LDAP\_Url = ldap://ldapserver
* LDAP\_Port = 389
* LDAP\_Bind\_Search =
- LDAP_Enable = True
- LDAP_Dn = dc=domain,dc=com
- LDAP_Url = ldap://ldapserver
- LDAP_Port = 389
- LDAP_Bind_Search =
{"filter": "\(&\(objectCategory=person\)\(objectclass=user\)\(memberOf=CN=ROCKET\_ACCESS,CN=Users,DC=domain,DC=com\)\(sAMAccountName=\#{username}\)\)", "scope": "sub", "userDN": "rocket.service@domain.com", "password": "urpass"}
{"filter": "(&(objectCategory=person)(objectclass=user)(memberOf=CN=ROCKET_ACCESS,CN=Users,DC=domain,DC=com)(sAMAccountName=#{username}))", "scope": "sub", "userDN": "rocket.service@domain.com", "password": "urpass"}
If you need to auth users from subgroups in LDAP use this filter:
* LDAP\_Bind\_search = {"filter": "\(&\(objectCategory=person\)\(objectclass=user\)\(memberOf:1.2.840.113556.1.4.1941:=CN=ROCKET\_ACCESS,CN=Users,DC=domain,DC=com\)\(sAMAccountName=\#{username}\)\)", "scope": "sub", "userDN": "rocket.service@domain.com", "password": "urpass"}
- LDAP_Bind_search = {"filter": "(&(objectCategory=person)(objectclass=user)(memberOf:1.2.840.113556.1.4.1941:=CN=ROCKET_ACCESS,CN=Users,DC=domain,DC=com)(sAMAccountName=#{username}))", "scope": "sub", "userDN": "rocket.service@domain.com", "password": "urpass"}
## Log on with email address
* LDAP\_Enable = True
* LDAP\_Dn = dc=domain,dc=com
* LDAP\_Url = ldap://ldapserver
* LDAP\_Port = 389
* LDAP\_Bind\_Search =
- LDAP_Enable = True
- LDAP_Dn = dc=domain,dc=com
- LDAP_Url = ldap://ldapserver
- LDAP_Port = 389
- LDAP_Bind_Search =
{"filter": "\(&\(objectCategory=person\)\(objectclass=user\)\(memberOf=CN=ROCKET\_ACCESS,CN=Users,DC=domain,DC=com\)\(mail=\#{username}\)\)", "scope": "sub", "userDN": "rocket.service@domain.com", "password": "urpass"}
{"filter": "(&(objectCategory=person)(objectclass=user)(memberOf=CN=ROCKET_ACCESS,CN=Users,DC=domain,DC=com)(mail=#{username}))", "scope": "sub", "userDN": "rocket.service@domain.com", "password": "urpass"}
## Log on with either email address or username
* LDAP\_Enable = True
* LDAP\_Dn = dc=domain,dc=com
* LDAP\_Url = ldap://ldapserver
* LDAP\_Port = 389
* LDAP\_Bind\_Search =
- LDAP_Enable = True
- LDAP_Dn = dc=domain,dc=com
- LDAP_Url = ldap://ldapserver
- LDAP_Port = 389
- LDAP_Bind_Search =
{"filter": "\(&\(objectCategory=person\)\(objectclass=user\)\(memberOf=CN=ROCKET\_ACCESS,CN=Users,DC=domain,DC=com\)\(\|\(mail=\#{username}\)\(sAMAccountName=\#{username}\)\)\)", "scope": "sub", "userDN": "rocket.service@domain.com", "password": "urpass"}
{"filter": "(&(objectCategory=person)(objectclass=user)(memberOf=CN=ROCKET_ACCESS,CN=Users,DC=domain,DC=com)(|(mail=#{username})(sAMAccountName=#{username})))", "scope": "sub", "userDN": "rocket.service@domain.com", "password": "urpass"}
## Log in
......@@ -53,7 +53,7 @@ When you enable LDAP the login form will login users via LDAP instead the intern
Use stunnel to create a secure connection to the LDAP server. Create a new configuration file /etc/stunnel/ldaps.conf with following content:
```text
```.ini
options = NO_SSLv2
[ldaps]
......@@ -62,17 +62,17 @@ accept = 389
connect = your_ldap_server.com:636
```
To enable Stunnel automatic startup change the `ENABLED` variable in /etc/default/stunnel4 to `1`:
To enable Stunnel automatic startup change the ``ENABLED`` variable in /etc/default/stunnel4 to ``1``:
```bash
```.sh
# Change to one to enable stunnel automatic startup
ENABLED=1
```
Finally on the Rocket.Chat server under /admin/LDAP set
* LDAP\_Url = localhost
* LDAP\_Port = 389
- LDAP_Url = localhost
- LDAP_Port = 389
## Work in Progress
......@@ -82,7 +82,7 @@ We're not experts on LDAP, so there might be lots of features we don't know abou
### I cannot login even everything looks good
If you cannot login without getting any error messages \(the last thing in log you see is `Attempt to bind <correct dn of user>`\), make sure the username of your ldap account does not match any username of a local account. For example if you created a local user with username `joe`, then enable ldap and try to login with username `joe` \(who exists on your ldap server\), it will silently fail without any error message in your log simply saying username or password do not match. You cannot login with `joe` by your ldap password nor by your local password any more.
If you cannot login without getting any error messages (the last thing in log you see is `Attempt to bind <correct dn of user>`), make sure the username of your ldap account does not match any username of a local account. For example if you created a local user with username `joe`, then enable ldap and try to login with username `joe` (who exists on your ldap server), it will silently fail without any error message in your log simply saying username or password do not match. You cannot login with `joe` by your ldap password nor by your local password any more.
### No users are created even everything looks good
......@@ -90,5 +90,4 @@ Every rocket.chat-user has to have an email. So either the LDAP users have an em
## References
MS LDAP Info: [https://msdn.microsoft.com/en-us/library/windows/desktop/aa746475\(v=vs.85\).aspx](https://msdn.microsoft.com/en-us/library/windows/desktop/aa746475%28v=vs.85%29.aspx)
MS LDAP Info: <https://msdn.microsoft.com/en-us/library/windows/desktop/aa746475(v=vs.85).aspx>
......@@ -6,11 +6,11 @@ These settings are in the `Accounts` setting page under `Administration`.
## Facebook
* Callback URL: `<<website_url>>/_oauth/facebook?close`
- Callback URL: `<<website_url>>/_oauth/facebook?close`
## GitHub
* Callback URL: `<<website_url>>/_oauth/github?close`
- Callback URL: `<<website_url>>/_oauth/github?close`
### GitHub Set up
......@@ -24,17 +24,17 @@ These settings are in the `Accounts` setting page under `Administration`.
## Google
* Callback URL: `<<website_url>>/_oauth/google?close`
- Callback URL: `<<website_url>>/_oauth/google?close`
### Google Set up
1. Go to the [Google Developer Console](https://console.developers.google.com), and create a new project
2. Set up your project by creating an "OAuth 2.0 client ID" \(under `APIs & Auth` and `Credentials`\)
2. Set up your project by creating an "OAuth 2.0 client ID" (under `APIs & Auth` and `Credentials`)
3. After that, make sure you define a **Product Name** in the OAuth consent screen, and select **Web App** as application type. Otherwise, you won't be able to provide a callback URL
## LinkedIn
* Callback URL: `<<website_url>>/_oauth/linkedin`
- Callback URL: `<<website_url>>/_oauth/linkedin`
## Meteor
......@@ -42,5 +42,4 @@ TBD.
## Twitter
* Callback URL: `<<website_url>>/_oauth/twitter`
- Callback URL: `<<website_url>>/_oauth/twitter`
......@@ -12,9 +12,10 @@ Create a client in Keycloak.
The following image shows the minimal configurations needed to setup Keycloak as an Identity Provider to Rocket.Chat.
![](../../../.gitbook/assets/client_configurations.png)
![Client Configurations][Client Configurations]
After saving the changes a new credentials tab will be created for the client. This credentials tab will provide the client secrets which will be used when configuring the Rocket.Chat
After saving the changes a new credentials tab will be created for the client. This credentials tab will provide the
client secrets which will be used when configuring the Rocket.Chat
## Configuring Rocket.Chat
......@@ -23,7 +24,9 @@ After saving the changes a new credentials tab will be created for the client. T
* Login to Rocket.Chat with an administrator account and navigate to OAuth page.
* Click the Add custom OAuth button and provide the following configurations
The URL paths provided in the below configurations can be also obtained by navigating to the Realm setting and clicking the endpoints link in the `General Tab`. While configuring the below settings replace the `realm_name` with the appropriate realm name. The default realm provided by Keycloak is `master`.
The URL paths provided in the below configurations can be also obtained by navigating to the Realm setting and
clicking the endpoints link in the `General Tab`. While configuring the below settings replace the `realm_name` with
the appropriate realm name. The default realm provided by Keycloak is `master`.
1. URL: `http://{keycloak_ip_address}:{port}/auth`
2. Token Path: `/realms/{realm_name}/protocol/openid-connect/token`
......@@ -41,27 +44,32 @@ Leave the rest of the configurations as default.
Now logout from Rocket.Chat to view the keycloak based login option visible in the login page.
![](../../../.gitbook/assets/keycloak_federation.png)
![Key Cloak Federation][Key Cloak Federation]
## Mapping non-federated keycloak user roles to Rocket.Chat roles
This section documents how client-specific roles of keycloak managed user can be mapped to Rocket.Chat roles. This does not work for federated users \(e.g. LDAP managed users\).
This section documents how client-specific roles of keycloak managed user can be mapped to Rocket.Chat roles. This does not work for federated users (e.g. LDAP managed users).
For this example, we map the `admin` and `livechat-manager` role, as documented in [Permissions](https://rocket.chat/docs/administrator-guides/permissions/).
First we add the required roles to the client
![](../../../.gitbook/assets/client_roles_configurations.png)
![Client Roles Configurations][Client Roles Configurations]
then we have to add a mapper entry, that maps our client roles to OpenId, passing the value to Rocket.Chat
![](../../../.gitbook/assets/client_roles_mapper_roles.png)
![Client Roles Mapper Roles][Client Roles Mapper Roles]
Now in order to grant the Rocket.Chat role to a user, we have to modify the users Role Mappings.
!\[User Role Mapping\]\[User Role Mapping\]
![User Role Mapping][User Role Mapping]
The roles are only synced on first login, and not being refreshed on each login. Please see the [bug report](https://github.com/RocketChat/Rocket.Chat/issues/15225) for current state.
\[User Role Mapping\]: user\_role\_mapping.png
The roles are only synced on first login, and not being refreshed on each login.
Please see the [bug report](https://github.com/RocketChat/Rocket.Chat/issues/15225) for
current state.
[Client Configurations]: client_configurations.png
[Key Cloak Federation]: keycloak_federation.png
[Client Roles Configurations]: client_roles_configurations.png
[Client Roles Mapper Roles]: client_roles_mapper_roles.png
[User Role Mapping]: user_role_mapping.png
\ No newline at end of file
......@@ -6,30 +6,30 @@ Okta Identity Cloud Service can be integrated as an OAuth OpenID Identity Provid
On the Rocket.Chat OAuth settings page **add a custom auth**.
Give the custom OAuth a unqiue name. For this example we will use _okta_.
Give the custom OAuth a unqiue name. For this example we will use *okta*.
Set the following:
* **Enabled**: _True_
* **URL**: The URL to your okta domain on okta.com with a suffix of _/oauth2/v1_. For example: _`https://mycompany.okta.com/oauth2/v1`_
* **Token**: _/token_
* **Token Sent Via**: _Header_
* **Identity Token Sent Via**: _Same as Token Sent Via_
* **Identity Path**: _/userinfo_
* **Authorize Path**: _/authorize_
* **Scope**: _openid email profile groups offline\_access_
* **Param Name for access token**: _access\_token_
* **id**: Set to the **Client ID** in the Okta app **Client Credentials** below.
* **Secret**: Set to the **Client secret** in the Okta app **Client Credentials** below.
* **Login Style**: Either setting works. Popup with pop up the Okta check/login in another window. Redirect will redirect the current page.
* **Button Text**: Set to personal preference.
* **Button Text Color**: Set to personal preference.
* **Button Color**: Set to personal preference.
* **Username field**: _preferred\_username_
* **Avatar field**: Was not used on our Okta instance. Further research will be required to use this.
* **Roles/Groups field name**: roles
* **Merge Roles from SSO**: Our server syncs from ldap so we left this _false_.
* **Merge users**: Our server syncs from ldap so we left this _false_.
- **Enabled**: *True*
- **URL**: The URL to your okta domain on okta.com with a suffix of */oauth2/v1*. For example: *`https://mycompany.okta.com/oauth2/v1`*
- **Token**: */token*
- **Token Sent Via**: *Header*
- **Identity Token Sent Via**: *Same as Token Sent Via*
- **Identity Path**: */userinfo*
- **Authorize Path**: */authorize*
- **Scope**: *openid email profile groups offline_access*
- **Param Name for access token**: *access_token*
- **id**: Set to the **Client ID** in the Okta app **Client Credentials** below.
- **Secret**: Set to the **Client secret** in the Okta app **Client Credentials** below.
- **Login Style**: Either setting works. Popup with pop up the Okta check/login in another window. Redirect will redirect the current page.
- **Button Text**: Set to personal preference.
- **Button Text Color**: Set to personal preference.
- **Button Color**: Set to personal preference.
- **Username field**: *preferred_username*
- **Avatar field**: Was not used on our Okta instance. Further research will be required to use this.
- **Roles/Groups field name**: roles
- **Merge Roles from SSO**: Our server syncs from ldap so we left this *false*.
- **Merge users**: Our server syncs from ldap so we left this *false*.
## Configuring the Identity Provider
......@@ -37,15 +37,15 @@ Set the following:
On your Okta Applications Dashboard, find the button to create a new app. It should open the following pop-up:
![](../../../.gitbook/assets/addapp.png)
![Add App Popup][AddApp]
Select **OpenID Connect** and select **Create** to open the window to create the new integration.
### Create Integration
!\[Create Integration\]\[CreateIntegration\]
![Create Integration][CreateIntegration]
The only information needed on this page is the **application name** and **redirect URI**. The URI you need to use here is the same one that is shown on the **callback URL** listed at the top of the page after creating the custom OAuth section in the Rocket.Chat settings. In this example the custom oauth will be called _okta_. This will result in a **redirect URI** of _`https://my-rocketchat-server.org/_oauth/okta`_.
The only information needed on this page is the **application name** and **redirect URI**. The URI you need to use here is the same one that is shown on the **callback URL** listed at the top of the page after creating the custom OAuth section in the Rocket.Chat settings. In this example the custom oauth will be called *okta*. This will result in a **redirect URI** of *`https://my-rocketchat-server.org/_oauth/okta`*.
Select **Save** to be taken to the **General Settings** for the new app.
......@@ -59,5 +59,5 @@ Copy the **Client secret** to the Rocket.Chat **secret** field on the oauth sett
Everything should be properly configured now. You can now assign users or groups users to your Integration app on the Okta Dashboard and then test the login on your Rocket.Chat instance.