# Single sign-on

## Overview <a href="#overview" id="overview"></a>

By enabling single sign-on (SSO) on Breakroom, you can provide your users with a secure and simplified login process. Integrating your current identity management system with Breakroom takes only a few minutes, but has the potential to save you a lot of hassle.

In order to enable SSO, you will need to contract for services with an Identity Provider (IdP). Some IdPs to consider include Okta and Microsoft Azure.

{% hint style="info" %}
Only [World Owners](https://docs.breakroom.tech/opening-the-doors/world-level-user-permissions#owner) and [World Administrators](https://docs.breakroom.tech/opening-the-doors/world-level-user-permissions#administrator) can access the Dashboard.
{% endhint %}

## Enabling SSO <a href="#enabling-sso" id="enabling-sso"></a>

To enable SSO within Breakroom, you will need to copy the parameters Breakroom provides and enter them into your IdP's SAML Signing Certificate generator. Your IdP will then provide you with a SAML Signing Certificate, which will include a metadata file containing additional information. You will need to enter this information into the Breakroom Dashboard in order to complete setup.

<figure><img src="https://1679086873-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2F5gOE0ivmDtuXfHroTVSx%2Fuploads%2FQTCwJU4BiaGIgwj1oHvm%2FSingle_Sign_001.png?alt=media&#x26;token=12fa22d2-e19e-47d2-be43-28dceeaba537" alt=""><figcaption><p>Highlighted: The Dashboard > World Customization > World Access tab, and the location of the SSO Login toggle.</p></figcaption></figure>

You can enable SSO within Breakroom by following the steps below.

1. Navigate to your [Dashboard](https://docs.breakroom.tech/building-new-worlds/breakroom-dashboard-tour).
2. Click on the **World Customization > World Access tab**.
3. Click the **SSO Login toggle** to enable SSO.

<figure><img src="https://1679086873-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2F5gOE0ivmDtuXfHroTVSx%2Fuploads%2Fr1C4TdRsFU6OEgzvMhzn%2FSingle_Sign_002.png?alt=media&#x26;token=8ce1c299-b974-40dd-8a12-bdf29f3904e4" alt="" width="563"><figcaption><p>Pictured: The SSO Settings > Identity Provider Setup panel.</p></figcaption></figure>

5. Once the SSO Login toggle is enabled, several additional sections will appear on your screen. Scroll down to the **Identity Provider Setup panel**.&#x20;
6. Here you will see two parameters provided in the form of links—the **SSO URL** and the **SP Entity ID**. You can click the **copy icon** located next to either of these parameters in order to copy it.&#x20;
7. Enter these parameters into the SAML Signing Certificate generator on your IdP's website. Once your IdP finishes creating your SAML Signing Certificate, they will provide you with a metadata file.

<figure><img src="https://1679086873-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2F5gOE0ivmDtuXfHroTVSx%2Fuploads%2FJEHKQYDZaDoPPZcFifu5%2FSingle_Sign_003.png?alt=media&#x26;token=6c052099-f7de-4629-b5ae-14d1991670a3" alt="" width="563"><figcaption><p>Pictured: The IdP panel.</p></figcaption></figure>

8. Return to the Breakroom Dashboard and scroll to the **Details Provided by your Identity Provider section**. Enter the **Entity ID, X.509 Certificate, and Sign-in URL parameters** from the IdP metadata file into the relevant fields.&#x20;
9. Click the **Save button**.

### Important notes <a href="#important-notes" id="important-notes"></a>

Upon enabling SSO, user accounts are *not* automatically generated in Breakroom, and you will not see any users appear under the [Manage Users tab](https://docs.breakroom.tech/opening-the-doors/creating-and-managing-user-accounts). Instead, Breakroom accounts will be generated as users log in. Each user account will occupy one of the available [seats](https://docs.breakroom.tech/opening-the-doors/seats-and-concurrency) under your Breakroom account.

### Disabling SSO <a href="#disabling-sso" id="disabling-sso"></a>

To disable SSO integration, follow steps 1-2 as [detailed above](#enabling-sso) and click the **SSO Login toggle** again.

## Customizing the Breakroom login screen

<figure><img src="https://1679086873-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2F5gOE0ivmDtuXfHroTVSx%2Fuploads%2FoqY9G98Ot5KSLisvjDAC%2FSingle_Sign_004.png?alt=media&#x26;token=b4003ea3-153f-4d08-9057-fb471c3546ca" alt=""><figcaption><p>Pictured: Here the SSO buton has been customized, and the self registration and standard login features have been disabled. The end result is visible in the Login Screen Preview panel.</p></figcaption></figure>

The World Access tab features a login panel preview, so you can see how your changes will appear on the [World Stream](https://docs.breakroom.tech/opening-the-doors/world-stream) landing page and on the [desktop app](https://docs.breakroom.tech/opening-the-doors/desktop-viewers). You can also personalize your SSO button with a logo and custom text.

To customize the login panel, follow these steps.

1. Navigate to your [Dashboard](https://docs.breakroom.tech/building-new-worlds/breakroom-dashboard-tour).
2. Click on the **World Customization > World Access tab**.
3. First, choose which login methods will be available for your users.
   1. Enable or disable [self-registration](https://docs.breakroom.tech/opening-the-doors/creating-and-managing-user-accounts/..#enabling-self-registration).
   2. Enable or disable [SSO](#enabling-sso).
   3. Enable or disable the standard login (Breakroom account email and password).
4. If you have chosen to enable SSO, you can then customize the SSO login button appearance.
   1. In the **Button Text field**, enter the text you would like to appear on the button.
   2. If you want to upload a custom logo for the SSO login button, click the **Browse link** in the Button Image field. This will launch a standard file import window on your computer. Locate the image file you want to use, click on it, and then click the **Open button**.
   3. If you want to clear the current logo, click the **Delete button.**
5. When you are satisfied with your changes, click the **Save button**.


---

# Agent Instructions: Querying This Documentation

If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question.

Perform an HTTP GET request on the current page URL with the `ask` query parameter:

```
GET https://docs.breakroom.tech/opening-the-doors/creating-and-managing-user-accounts/single-sign-on.md?ask=<question>
```

The question should be specific, self-contained, and written in natural language.
The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.