Note:

• This tutorial requires access to Oracle Cloud. To sign up for a free account, see Get started with Oracle Cloud Infrastructure Free Tier.
• It uses example values for Oracle Cloud Infrastructure credentials, tenancy, and compartments. When completing your lab, substitute these values with ones specific to your cloud environment.

Integrate Rocket.Chat with Identity Domains for Single Sign-On

Introduction

Rocket.Chat is a secure and highly customizable open-source communication platform for organizations with sophisticated security and privacy concerns. Rocket.Chat provides full control over user data and conversations. The platform supports native apps, seamless integration with third-party applications, cross-channel collaboration, Security Assertion Markup Language (SAML) based single sign-on (SSO) and configuration control using APIs.

Oracle Cloud Infrastructure Identity and Access Management (OCI IAM) is a container for managing users and roles, federating and provisioning of users, secure application integration through Oracle SSO configuration, and SAML/OAuth based Identity Provider (IdP) administration.

In this tutorial, we will automate the installation of Rocket.Chat and will integrate OCI IAM as its IdP for SSO.

Objectives

• Use Terraform based stack to create the following resources.

  • Keystore and Hardware Security Module (HSM) protected key.
  • Certificates and Certificate Authorities (CA).
  • An OCI Compute instance to host Rocket.Chat.
  • An OCI Load Balancer to access Rocket.Chat securely.

• Auto deploy Rocket.Chat on the compute instance and add a created load balancer on top of it.

• Set up Rocket.Chat and create a SAML based IdP for OCI IAM.

• Test the SSO flow between OCI IAM and Rocket.Chat.

Prerequisites

• An active OCI subscription.

• Identity domain and an admin account on it.

• Familiar with OCI IAM and Terraform.

• An existing VCN and a public subnet.

• Security list with the following ports open for ingress traffic.

  Type	Source Port	Source CIDR	Destination Port	Protocol	Description
  Ingress	All	0.0.0.0/0	22	TCP	SSH
  Ingress	All	0.0.0.0/0	3000	TCP	For Rocket.Chat Server
  Ingress	All	0.0.0.0/0	443	TCP	Standard HTTPS Port
  Ingress	All	0.0.0.0/0	80	TCP	TCP traffic for ports: 80

Task 1: Deploy a Stack to Install Rocket.Chat and Create a SAML Application using an Automated Terraform Stack

Rocket.Chat can be deployed using different methods. For this tutorial, we have used Deploy with Docker & Docker Compose option. For more information, see Deploy Rocket.Chat.

To ease up the installation of Rocket.Chat, we have created a Terraform automation stack. This stack will:

• Create a host Linux box of VM.Standard.E2.1 shape.
• Install Rocket.Chat on it.
• Create a Keystore, HSM protected key, Certificate Authority and a Certificate for Secure Sockets Layer(SSL) communication over internet.
• Deploy a load balancer and configure it for accessing Rocket.Chat over SSL.
• Create a SAML application under an existing identity domain.

Note: Ensure to check the service limits on the resources to be created before execution of the linked stack. For more information, see IAM With Identity Domains Limits.

1. Download the Rocket.Chat full stack from here: Full_Stack_Rocket.Chat.zip.

   Once the Rocket.Chat full stack zip file is downloaded, unzip the file, and replace the content of the -rchat.pem file with your respective content of the private key.

   Note: Use OCI Resource Manager from the OCI Console to deploy the stack to avoid any failures.

2. Log in to the OCI Console as an admin user, navigate to Developer Services and under Resource Manager, click Stacks.

   

3. Select the compartment and click Create Stack. In the Stack configurations section, select the stack zip file downloaded in Step 1 to deploy stack and click Next.

   

   

4. In the Configure variables page, enter the required details to create a compute instance and other resources and click Next.

   Note: To create compute instance and load balancer, you will need an existing VCN with public connectivity.

   

   

5. In the Review page, review the provided details and click Create.

   

6. In the Stack details page, click Plan. You should get a Success output.

   

   

7. In the Stack details page, click Apply. You should get a Success output.

   

   

8. You can find load balancer attached to the compute instance hosting Rocket.Chat and a SAML application in your IAM domain after successful execution of the stack.

   

   

   

   Note: The stack might take around 40 minutes for execution. Wait until the job succeeds.

Task 2: Set up Rocket.Chat Admin Account

In this task, we will update the hosts file on our local system and then will validate the deployed resources.

For Windows: C:\Windows\System32\Drivers\etc\hosts.

For Linux: /etc/hosts

Public IP Address of Load Balancer   your-domain-name.com

Access Rocket.Chat at https://your-domain-name.com:443 and you will be redirected to the set up page.

Note: Keep the admin password secured, we will need this while creating a SAML IdP in Rocket.Chat.

Task 3: Create a SAML IdP in Rocket.Chat for Single Sign-On

1. Log in to your Rocket.Chat instance, navigate to Workspace and Settings.

   

   

2. In the Settings window, enter SAML and click Open.

   

3. In the Connection page, select Enable. Enter the following details and click Save changes. If prompted for admin password, enter the password.

   • Custom Provider: Enter idcs.

   • Update Custom Entry Point: Enter your custom entry point. For example, https://idcs-xxxx.identity.oraclecloud.com/fed/v1/idp/sso.

   • IDP SLO Redirect URL: Enter your IdP SLO redirect URL. For example, https://idcs-xxxx.identity.oraclecloud.com/fed/v1/idp/slo.

   • Custom Issuer: Enter custom issuer. For example, https://your-domain-name.com/_saml/metadata/idcs.

   • Custom Certificate: Download the Signing Certificate from the SAML application created using stack and copy the content.

     Note: Exclude BEGIN CERTIFICATE AND END CERTIFICATE lines.

   • Public Cert Contents: Copy the entire content of the certificate.

   • Signature Validation Type: Select Validate Assertion Signature.

   

   

   Note: Use the same Custom Provider static value, else the SSO might fail as it is referred in the SAML application created in Task 1.

4. In the General page, under User Interface section, update the Button Text and other details if you need to change it and click Save Changes.

   

Task 4: Test the SSO for Rocket.Chat using OCI IAM

1. Open your browser and enter the URL for Rocket.Chat https://demo.rocketchat.com:443.

   

2. The OCI IAM identity domains sign in page appears. Use the Username and Password of the previously created user.

   

3. Upon successful authentication, the user is redirected to the Rocket.Chat homepage.

   

   Note: You should have a common user created both in OCI IAM and Rocket.Chat with the same email address.

Common troubleshooting scenarios for Rocket.Chat SSO with OCI IAM

1. Ensure that you have Allow cross-origin resource sharing (CORS) enabled under Domains, your domain, Settings and Session settings.

2. If your Rocket.Chat instance takes time to load you can try to SSH into the instance and restart your Docker compose with the following commands.

   	docker compose down
   
   	docker compose up -d
   

Related Links

• Managing Identity Domains

• Introducing OCI IAM Identity Domains

• Rocket.Chat documentation

• Deploy with Docker & Docker Compose

Acknowledgments

• Author - Chetan Soni (Cloud Solutions Engineer)

More Learning Resources

Explore other labs on docs.oracle.com/learn or access more free learning content on the Oracle Learning YouTube channel. Additionally, visit education.oracle.com/learning-explorer to become an Oracle Learning Explorer.

For product documentation, visit Oracle Help Center.

---

Title and Copyright Information

Integrate Rocket.Chat with Identity Domains for Single Sign-On

G11385-03

August 2024

Copyright ©2024,

Oracle and/or its affiliates.