Docs

Admin / People and roles

Dashboard Authentication Setup

Set up single sign-on (SSO) to the Risotto dashboard with Okta, Google Workspace, or Microsoft Entra ID, and manage dashboard accounts with Directory Sync (SCIM)

Set up how your admins and agents sign in to the Risotto dashboard: through your identity provider (IdP) with single sign-on (SSO), and optionally with accounts that your IdP creates and removes through Directory Sync.

Dashboard SSO applies only to the people who sign in to the dashboard. Employees who ask for help in Slack or Microsoft Teams never sign in to Risotto, so your IdP's own sign-in and MFA already cover them. You can set up dashboard SSO at any time, also during a pilot.

Choose an option

Risotto Support turns on each option for your organization. You set up the app in your IdP and send Risotto Support the values below.

OptionIdentity providersYou send Risotto SupportRisotto Support sends you
Sign in with GoogleGoogle WorkspaceYour Google Workspace domainNothing. Support turns on the connection.
SAML SSOOkta, Google Workspace, Microsoft Entra IDYour email domain, then your IdP's metadataThe values to enter in your IdP's SAML app
Directory Sync (SCIM)Okta, Microsoft Entra IDNothing to start. For role mapping, group namesA SCIM endpoint URL and a Bearer token

Directory Sync needs a working SAML SSO connection first.

Before you start

  • Admin access to your IdP.
  • Dashboard accounts for your people. SSO does not create accounts. Invite the people who use the dashboard first: see Invite users. Or let your IdP create the accounts with Directory Sync.
  • A request to Risotto Support. Email support@tryrisotto.com or your account representative, and say which IdP you use.

How sign-in works with SSO

The Risotto sign-in page has Google and Rippling buttons and an Email address field. There is no separate SSO button. With SSO on, a person enters their work email and clicks Continue. Risotto sends them to your IdP to sign in, then back to the dashboard.

When Risotto Support turns on a SAML connection, it applies to every email address at your domain. Each person with that domain signs in through your IdP from then on, so assign everyone who uses the dashboard to the app in your IdP before Support turns it on.

Sign-in starts on the Risotto sign-in page (SP-initiated). Starting from the app's tile in your IdP (IdP-initiated) is off by default. To use it, ask Risotto Support to turn it on when you send your metadata. Without it, the Okta tile returns a RelayState parameter is missing error.

Okta

Okta apps for Risotto

Your Okta org can have more than one Risotto app. Each app has a different job, so make sure that you open the correct one.

Risotto app from the Okta catalogSAML 2.0 app that you madeAPI Services app
How you got itBrowse App Catalog > RisottoCreate App Integration > SAML 2.0Create App Integration > API Services
What it doesSigns people in to the dashboardSigns people in to the dashboardLets Risotto's agent tools call the Okta API
Directory Sync (SCIM)No. It supports sign-in only. You make a second app for SCIM.Yes. You add SCIM to this app.No. It cannot send SCIM.

The steps below use the catalog app. Do not change the API Services app for SSO or for Directory Sync: a change to it can stop the Risotto agent tools that use Okta. See Okta integration.

Set up Okta SSO

  1. Ask Risotto Support for your SAML Org ID

    Ask Risotto Support to set up dashboard SSO with Okta. Support sends you your SAML Org ID. It starts with samlc_. It is the ID of the SSO connection that Risotto makes for your organization, not your Okta domain and not the organization ID in the Risotto dashboard.

  2. Add the Risotto app from the catalog

    In the Okta Admin Console, go to Applications and Resources > Applications. Click Browse App Catalog, search for Risotto, select it, and click Add Integration.

  3. Enter the SAML Org ID

    In the app's settings, enter the value from Risotto Support in SAML Org ID, under Advanced Sign-on Settings. The catalog app already has every other SAML setting, attribute statement, and Name ID format that Risotto needs.

  4. Assign people and groups

    Open the app's Assignments tab. Click Assign > Assign to Groups or Assign > Assign to People, click Assign next to each group or person who uses the dashboard, then click Done.

  5. Send the metadata URL to Risotto Support

    Open the app's Sign On tab and copy the Metadata URL. Send it to Risotto Support. To also start sign-in from the Okta tile, ask Support to turn on IdP-initiated sign-in now.

  6. Test the sign-in

    When Risotto Support says the connection is on, test the sign-in.

The catalog app supports sign-in only. To also use Directory Sync, see Okta Directory Sync.

Google Workspace

Google Workspace offers two ways to sign in to the dashboard: Sign in with Google, which needs no app in Google Admin, or SAML, with a custom SAML app that you control. Directory Sync is not available for Google Workspace.

Sign in with Google

  1. Ask Risotto Support for Google sign-in

    Ask Risotto Support to set up Google sign-in for the dashboard, and send your Google Workspace domain.

  2. Test the sign-in

    Risotto Support sets up and turns on the connection. Then test the sign-in.

Google SAML

  1. Ask Risotto Support for a SAML connection

    Ask Risotto Support for a Google SAML connection, and send your email domain. Support sends you an ACS URL and an Entity ID.

  2. Add a custom SAML app

    In the Google Admin console, go to Apps > Web and mobile apps. Click Add app > Add custom SAML app. In App name, enter Risotto, then click Continue.

  3. Download the IdP metadata

    On Google Identity Provider details, click Download Metadata and keep the file for Risotto Support. Click Continue.

  4. Enter the service provider details

    Paste the ACS URL and the Entity ID from Risotto Support. Leave Start URL empty. Set Name ID format to EMAIL and Name ID to Basic Information > Primary email. Click Continue.

  5. Map the attributes

    Click Add mapping and map these attributes. Only Primary email is required. Click Finish.

    Google Directory attributeApp attribute
    Primary emailemail
    First namefirstName
    Last namelastName
  6. Turn on the app

    Open the app's User access panel. Turn the app ON for everyone, or for the organizational units and groups that use the dashboard. Click Save.

  7. Send the metadata to Risotto Support

    Send the metadata file to Risotto Support. Without the file, send the SSO URL, the Entity ID, and the Certificate from Google Identity Provider details instead. When Support says the connection is on, test the sign-in.

Microsoft Entra ID

  1. Ask Risotto Support for a SAML connection

    Ask Risotto Support for a Microsoft Entra ID SAML connection, and send your email domain. Support sends you an Identifier (Entity ID) and a Reply URL (Assertion Consumer Service URL).

  2. Create an enterprise application

    In the Microsoft Entra admin center, go to Entra ID > Enterprise apps. Click New application > Create your own application. Name it Risotto, select Integrate any other application you don't find in the gallery (Non-gallery), and click Create.

  3. Assign users and groups

    In Users and groups, click Add user/group, select the people and groups who use the dashboard, and click Assign.

  4. Enter the SAML settings

    In Single sign-on, select SAML. In Basic SAML Configuration, click Edit. Paste the Identifier (Entity ID) and the Reply URL (Assertion Consumer Service URL) from Risotto Support, and click Save.

  5. Check the claims

    In Attributes & Claims, make sure that these claims are present. They are usually the defaults.

    Claim nameSource attribute
    emailaddressuser.mail
    givennameuser.givenname
    surnameuser.surname
  6. Send the metadata URL to Risotto Support

    In SAML Certificates, copy the App Federation Metadata Url and send it to Risotto Support. When Support says the connection is on, test the sign-in.

Test the sign-in

  1. Open the sign-in page in a private window

    Open a private or incognito browser window and go to the Risotto dashboard.

  2. Enter your work email

    In Email address, enter your work email and click Continue. For Sign in with Google, click Google instead.

  3. Sign in to your identity provider

    Risotto sends you to your IdP. Sign in there. You return to the Risotto dashboard, signed in.

If Risotto asks you to choose an organization, select your organization. Do not create a new one.

Directory Sync (SCIM)

Directory Sync connects your IdP to Risotto with SCIM. Your IdP then controls who has a dashboard account, and your IdP groups control who is in each department:

  • When you assign a person to the app, Risotto creates their account. Risotto adds them to the departments that their groups map to.
  • When you add a person to a group or remove them from it, Risotto adds them to the departments that the group maps to, or removes them.
  • When you deactivate the person, or remove them from the app, Risotto removes their access. See Deprovisioning.

Directory Sync is available for Okta and Microsoft Entra ID. It manages dashboard users only. It does not change who can ask Risotto for help in Slack or Microsoft Teams.

Before you begin

You need:

  • An admin account in your IdP.
  • An org admin account in Risotto.
  • The SCIM endpoint URL and the Bearer token from Risotto Support. Keep the token secret. It lets its holder add users to your Risotto organization.
  • A group in your IdP for each Risotto department. The members of a group are people, not other groups. A group that has another group as a member is refused.

Assign only the people who use the Risotto dashboard. Each person that you assign gets a dashboard account with the Member role. An org admin changes roles in Organization settings. To let your IdP set who is an org admin, see Let your IdP set org roles.

Okta Directory Sync

  1. Find your sign-in app

    In the Okta Admin Console, go to Applications and Resources > Applications. Open the app that signs your people in to Risotto: a SAML app, not an API Services app. Open the General tab, and in App Settings, click Edit.

    • If you see a Provisioning field, select SCIM and click Save. Skip the next step.
    • If you do not see it, click Cancel. Your sign-in app is the Risotto catalog app, which cannot send SCIM. Do the next step.
  2. Make a provisioning app (catalog app only)

    Make a second app that only sends SCIM. Your people keep signing in through the catalog app.

    1. Click Create App Integration. If Okta asks, select Classic experience.
    2. Select SAML 2.0, not API Services. Click Next.
    3. In App name, enter Risotto Directory Sync. Select Do not display application icon to users. Click Next.
    4. In Single sign-on URL and Audience URI (SP Entity ID), enter the values from Risotto Support. Click Next.
    5. Select I'm an Okta customer adding an internal app and This is an internal app that we have created. Click Finish.
    6. Open the General tab. In App Settings, click Edit. In Provisioning, select SCIM. Click Save.
  3. Connect Okta to Risotto

    Open the Provisioning tab of the app that sends SCIM. In Settings > Integration, click Edit, and fill in:

    • SCIM connector base URL: the SCIM endpoint URL.
    • Unique identifier field for users: userName.
    • Supported provisioning actions: Push New Users, Push Profile Updates, and Push Groups.
    • Authentication Mode: HTTP Header.
    • Authorization: the Bearer token.

    Click Test Connector Configuration and make sure that the test succeeds. If it fails, check the URL and the token. Click Save.

  4. Turn on provisioning to Risotto

    In Settings > To App, click Edit. Enable Create Users, Update User Attributes, and Deactivate Users, and click Save. In Attribute Mappings on the same page, make sure that email comes from user.email.

  5. Assign the people

    Open the Assignments tab of the app that sends SCIM. Assign the groups of people who use the Risotto dashboard. Do not assign Everyone.

    • If you added SCIM to your sign-in app: Okta does not send the people that you assigned before you added SCIM. Click Provision Users on the Assignments tab. If Okta does not show this button, remove those assignments and add them again. This stops their sign-in until you add them again.
    • If you made a provisioning app: assign the same groups to the sign-in app and to the provisioning app.
  6. Push the groups

    Open the Push Groups tab of the app that sends SCIM. Click Push Groups > Find groups by name. Find a group whose members belong in a Risotto department, make sure that Push group memberships immediately is selected, and click Save. Do this for each group that you map to a department.

    Okta pushes only the members that it also sends to the app. Assign each member of a pushed group to the app, directly or through an assigned group.

  7. Map your departments

  8. Test a removal

    Remove a test person from a pushed group. In a few minutes, they are not on the Members page of the department that the group maps to. Then remove the test person from the app, or deactivate them. Do not use Suspend. In a few minutes, they are not on the Members page of any department.

Microsoft Entra ID Directory Sync

Directory Sync uses the same enterprise app that signs your people in to Risotto.

  1. Connect Entra to Risotto

    In the Microsoft Entra admin center, go to Entra ID > Enterprise apps and open the app that signs your people in to Risotto. Select Provisioning. If Entra shows Get started, select it. Set Provisioning Mode to Automatic.

    In Admin Credentials, paste the SCIM endpoint URL in Tenant URL and the Bearer token in Secret Token. Select Test Connection, make sure that the test succeeds, and select Save.

  2. Check the mappings

    Open Mappings > Provision Microsoft Entra ID Users. Make sure that each of these target attributes has a mapping:

    • userName
    • active
    • emails[type eq "work"].value
    • name.givenName
    • name.familyName

    Then open Mappings > Provision Microsoft Entra ID Groups. Set Enabled to Yes and select Save. Entra then sends each assigned group with its members.

    In Settings, keep Scope at Sync only assigned users and groups. Keep Provisioning Status at Off for now.

  3. Assign the people and the groups

    In Users and groups, assign the groups of people who use the Risotto dashboard. Entra sends each assigned group, so assign each group that you map to a department. Assign only groups whose members are people: Entra does not send the members of a group in an assigned group.

  4. Turn on provisioning

    In Provisioning, set Provisioning Status to On and select Save. The first cycle can take more than 40 minutes. Then Entra syncs about every 40 minutes.

  5. Map your departments

    Follow Map departments. A group shows in the Directory Sync card after Entra sends it.

  6. Test a removal

    Remove a test person from Users and groups, then select Provision on demand for them. Without this, the removal waits for the next cycle. In a few minutes, the test person is not on the department's Members page.

Map departments

An org admin maps the groups of your IdP to Risotto departments. The Directory Sync card shows only to org admins, and only after Risotto Support turns on Directory Sync. For the rest of the Members page, see Departments.

  1. Open the department's members

    In the Risotto dashboard, click Settings at the bottom of the sidebar. Under Departments, click the department, then click Members.

  2. Add a group

    In the Directory Sync card, click Add a group and choose a group that your IdP pushed. You can also type the name of a group that your IdP has not pushed yet, and click Add "group name". Do this for each group that maps to the department, then for each department.

  3. Check the members

    Wait one minute, then reload the page. The members of the group show in Members with a building icon: "Managed by directory sync". If the group has many members, wait longer. Risotto updates about 5 people each second.

Rules for the mapping:

  • The mapping uses the name of the group. The match is case-sensitive: IT, it, and I.T. are three different groups.
  • Each group maps to one department only. A department can have more than one group.
  • A person in more than one mapped group joins the department of each group.
  • If you rename a group in your IdP, the mapping no longer matches it. Directory Sync removes the agents that it added for the group. Add the new name in the Directory Sync card.
  • Directory Sync adds people as agents. To make a person a supervisor, change their role on the Members page.
  • You cannot remove a synced member on the Members page: their row shows a lock instead of the ⋮ menu. Remove them from the group in your IdP, or remove the group from the Directory Sync card.
  • When you remove a group (the × on its badge, then Remove), Directory Sync removes the agents that it added for that group. Supervisors and members that you added by hand stay.
  • If a supervisor is no longer in a group that maps to their department, Risotto keeps them there as a member that you manage by hand, and notifies your org admins.
  • A supervisor of a parent department already has access to its sub-departments. Directory Sync does not add them to a sub-department as an agent, and removes an agent membership that it added there before. To make them a supervisor of the sub-department too, add them there by hand.

Push groups to Risotto

The setup steps push the groups that you map to departments. Push another group, such as an admin group for role mapping, the same way.

  • Push flat groups only. Risotto reads only the direct members of a group. If you push a group that has another group in it, your IdP shows an error for that group at each sync.
  • Assign each person in a pushed group to the app too. Your IdP sends only the group members that it provisions to the app.
  • Risotto Support can use a group only after your IdP pushed it one time.

Okta: Make a new group to push, for example Risotto Admins, with only people who are assigned to the app. Do not push a group that assigns people to the app: Okta does not support one group for both app assignment and Group Push. Open the Push Groups tab of the app that sends SCIM, click Push Groups > Find groups by name, select the group, and click Save. Make sure that the group's Push Status is Active.

Microsoft Entra ID: In Users and groups, assign the group. Entra pushes each assigned group with its members. To push it before the next cycle, select Provision on demand, find the group, and select Provision.

Let your IdP set org roles

This step is optional. Without it, each person that you assign gets the Member role, and an org admin changes roles in Organization settings. With role mapping, your IdP sets who is an org admin: Risotto Support maps an IdP group to each Risotto role.

While role mapping is on:

  • A person in a mapped group gets the role of that group. If a person is in more than one mapped group, the mapping that is first in the list wins.
  • A person in no mapped group gets the Member role.
  • An org admin cannot change a role that a mapped group gives. To change it, change the person's groups in your IdP. An org admin can still change the role of a person in no mapped group in Organization settings.
  1. Make an admin group

    In your IdP, make a group for the people who must be org admins, for example Risotto Admins. Add each person directly.

  2. Push the group

  3. Send the group names to Risotto Support

    Tell Risotto Support the name of the group. For the Manager role, push a second group and send its name too. Risotto Support maps each group to its role, then turns on role mapping.

  4. Check the roles

    In Risotto, open Organization settings > Members. Make sure that the people in the admin group have the Admin role.

To turn off role mapping, ask Risotto Support. Each person keeps their role, and an org admin can change any role in Organization settings again.

Limitations

  • One Risotto organization. Directory Sync adds people to one Risotto organization: the organization of your SSO connection. If you have more than one Risotto organization, invite people to the others by hand.
  • Every Risotto organization. When your IdP deactivates a person, they cannot sign in to any Risotto organization. Risotto removes them from each Risotto organization that they belong to. Do not assign guest accounts or emails from outside your company.
  • Okta Suspend. Okta sends nothing to Risotto for a suspended user. Deactivate the person, or remove them from the app.
  • Entra timing. A change in Entra can take about 40 minutes to reach Risotto. For an urgent removal, remove the person from Users and groups, then select Provision on demand for them.
  • Groups and roles. IdP groups map to departments. They do not set organization roles, unless you turn on role mapping.
  • Nested groups. Push only groups whose members are people. A group that has another group as a member is refused, and your IdP reports an error for it in each cycle.
  • A group that Risotto missed. If a group does not show in the Directory Sync card, push the group again from your IdP.
  • Reactivation. When your IdP reactivates a person, Risotto adds them again to the departments that their groups map to, as an agent. An org admin sets their supervisor roles again. Without role mapping, an org admin also sets their organization role again. If the person cannot open your organization, invite them again.
  • First sign-in. Risotto can ask a new person to choose an organization at their first sign-in. They select your organization. They must not create a new organization.

Two-step sign-in for password accounts

If an Org Admin or Manager signs in with a password, has no second sign-in step, and has no active SSO, the dashboard shows Protect your account when a page loads. The prompt is a reminder: it does not block sign-in. To use SSO for your whole organization instead, click Contact us about SSO in it. See The Protect your account prompt.

User management

Provisioning

With Directory Sync, your IdP creates the dashboard accounts. See Directory Sync (SCIM).

Without Directory Sync, SSO does not create accounts: just-in-time (JIT) provisioning is not supported. Invite each person to your Risotto organization first. SSO then matches them by email address and signs them in with their existing Risotto profile and permissions. See Invite users.

Deprovisioning

With Directory Sync, deactivate the person in your IdP, or remove them from the app. Then:

  • Their dashboard sessions end, and they cannot sign in.
  • Risotto removes them from each department and from your Risotto organization.
  • Risotto revokes their MCP access.
  • This applies to each Risotto organization that the person belongs to.
  • API keys that the person created stay active, because they belong to your organization. Risotto notifies your org admins and lists the keys. An admin can revoke a key in Settings > Developers > API keys.

Okta sends the change at once. In Okta, Suspend sends nothing to Risotto. Entra sends the change in the next cycle, about every 40 minutes.

Something wrong or missing? Report an issue · View as Markdown