You can manage your CloudZero Roles by enabling your single-sign on (SSO) identity provider (IdP) to automatically assign users to existing, manually-created Roles.

After you create one or more Roles and set up your SSO integration in CloudZero, you can enable the SSO for Roles setting.

To do this, navigate to Settings > SSO Integrations > Select an SSO Integration you have configured from the list > Check Enable SSO for Groups.

If you pass in group claims using your IdP (for example, Finance team, IT team, Product team), CloudZero will look for existing Roles with a name matching the group claims passed in and then sync the appropriate users to those Roles. Any Roles without a matching name will be ignored.

To enable SSO for Roles, follow the steps for your IdP:

Manage Roles with Okta

ℹ️
You must manually create one or more Roles in CloudZero before you can enable SSO for Roles.

To enable SSO for Roles using an Okta integration, follow these steps:

Step 1: Add Claim to Okta Authorization Server

In Okta, navigate to Security > API > Authorization > Servers and select the appropriate authorization server. This is usually the default server.
Select Claims > Add Claim.
Enter a Name for the Okta claim.
In the Include in token type field, select ID Token, and in the second drop-down selector, choose Userinfo/id_token request.
Set Value type to Groups.
In the Filter field, set the filter predicate drop-down menu to your choice of predicate, for example, Matches regex.
Set the filter value to your choice of value, for example, .* to match all CloudZero Roles. Ensure this matches the name of the Roles your users are in.
Set the Include in field to Any scope.
Click Save.

These Okta settings are illustrated in the Edit Claim form:

You should then see the claim in the claims table for your authorization server:

Step 2: Add Claim to CloudZero application in Okta

In Okta, navigate to Admin Console > Applications > Applications.
Select your CloudZero application.
On the Sign On tab, scroll down to the OpenID Connect ID Token and click Edit.
In the Groups claim filter section, set the first drop-down menu to groups.
Set the second drop-down menu to your choice of filter predicate, for example, Matches regex.
Set the filter value field to your choice of value, for example, .* to match all CloudZero Roles. In the example that follows, we want to pass all groups that start with app-clou.
Click Save.

Step 3: Enable SSO for Roles in CloudZero

In CloudZero, navigate to Settings > SSO Integrations and select your Okta integration:
Scroll down to the SSO Connection Status and Controls section and check the Enable SSO for Roles (called Groups in the image) box:
Click Enable.

Microsoft Entra ID (Azure AD)

ℹ️
You must manually create one or more Roles in CloudZero before you can enable SSO for Roles.

To enable SSO for Roles using a Microsoft Entra ID (Azure Active Directory) integration:

In CloudZero, navigate to Settings > SSO Integrations and select your Microsoft Entra ID (Azure AD) integration:
Scroll down to the SSO Connection Status and Controls section and check the Enable SSO for Roles (called Groups in the image) box:
Click Enable.

OpenID Connect including GCP

ℹ️
You must manually create one or more Roles in CloudZero before you can enable SSO for Roles.

The Roles claim is often a new scope in your OpenID Connect (OIDC) IdP. None of CloudZero's existing OIDC integrations ask for this claim.

Follow these steps to send CloudZero the Roles claim and enable your OIDC IdP to manage your existing Roles in CloudZero:

In CloudZero, navigate to Settings > SSO Integrations and select your OIDC integration.
Scroll down to the SSO Connection Status and Controls section and check the Enable SSO for Roles (called Groups in the image) box.
Click Enable.