Unity organizations, projects, roles and permissions

Unity Cloud Identity package can list Unity entities (Unity Organizations as IOrganization and Unity Projects as IProject) that are available to the logged in user through implementations of the IOrganizationRepository interface, like the CompositeAuthenticator and the PkceAuthenticator.

Roles and permissions assigned to a user can be listed or validated using awaitable methods from IOrganization and IProject implementations.

Note

Different roles and permissions can be assigned to a user on a Unity Organization and on a Unity Project. See the list of available roles and permissions.

Fetching Unity Organizations for a user

Once the IAuthenticationStateProvider.AuthenticationStateChanged event is triggered with a value of AuthenticationState.LoggedIn you can call the IOrganizationRepository.ListOrganizationsAsync() method to return the list of Unity Organizations accessible to the logged in user.

public class ListOrganizationsBehaviour : MonoBehaviour
{
    ICompositeAuthenticator m_CompositeAuthenticator;
    IOrganizationRepository m_OrganizationRepository => m_CompositeAuthenticator;
    readonly List<IOrganization> m_Organizations = new ();

    void Awake()
    {
        m_CompositeAuthenticator = PlatformServices.CompositeAuthenticator;
        m_CompositeAuthenticator.AuthenticationStateChanged += OnAuthenticationStateChanged;
    }

    async Task Start()
    {
        await ApplyAuthenticationState(m_CompositeAuthenticator.AuthenticationState);
    }

    void OnDestroy()
    {
        m_CompositeAuthenticator.AuthenticationStateChanged -= OnAuthenticationStateChanged;
    }

    async void OnAuthenticationStateChanged(AuthenticationState newAuthenticationState)
    {
        await ApplyAuthenticationState(newAuthenticationState);
    }

    async Task ApplyAuthenticationState(AuthenticationState state)
    {
        switch (state)
        {
            case AuthenticationState.AwaitingInitialization:
            case AuthenticationState.AwaitingLogin:
            case AuthenticationState.AwaitingLogout:
                break;
            case AuthenticationState.LoggedIn:
                var organizationsAsyncEnumerable = m_OrganizationRepository.ListOrganizationsAsync(Range.All);
                await foreach (var organization in organizationsAsyncEnumerable)
                {
                    m_Organizations.Add(organization);
                }
                break;
            case AuthenticationState.LoggedOut:
                break;
        }
    }
}

Fetching Unity Projects for an IOrganization

The IOrganization interface exposes a ListProjectsAsync() method to fetch a range of Unity Project in an awaitable IAsyncEnumerable<IProject> object.

readonly List<IProject> m_Projects = new ();

async Task FetchOrganizationProjects(IOrganization organization)
{
    m_Projects.Clear();
    var projectsAsyncEnumerable = organization.ListProjectsAsync(Range.All);
    await foreach (var project in projectsAsyncEnumerable)
    {
        m_Projects.Add(project);
    }
}

List and validate roles or permissions for Unity entities

Both IOrganization and IProject implements the IRoleProvider interface. They both expose awaitable methods to list and validate roles and permissions assigned to the user.

You can use roles and permissions information to provide a better user experience by adjusting the UI element available and displayed to the user.

async Task FetchOrganizationRoles(IOrganization organization)
{
    var organizationRoles = await organization.ListRolesAsync();
    if (organizationRoles.HasRole(Role.Owner))
    {
        // Organization Owner specific logic
    }
}

readonly Permission m_AssetManagerCreatorPermission = new Permission("amc.assets.create");

async Task FetchProjectPermissions(IProject project)
{
    var projectPermissions = await project.ListPermissionsAsync();
    if (projectPermissions.HasPermission(m_AssetManagerCreatorPermission))
    {
        // Project Asset Manager Creator specific logic
    }
}

Note

When a user has the IOrganization.Role value of owner or manager, it is considered as having all available roles and permissions over all IProject of this IOrganization. Calling ListRolesAsync() or ListPermissionsAsync() method of these IProject returns an empty list, and calling HasRoleAsync() or HasPermissionAsync() method of these IProject returns false. Consider validating first the IOrganization.Role value of the logged in user before calling IRoleProvider methods on any IProject belonging to this IOrganization.