Managing roles in Cloud Foundry

Page last updated:

This topic describes how to manage user roles in Cloud Foundry using the cf CLI.

For a description of the available roles and their permissions, see Orgs, Spaces, Roles, and Permissions.

Prerequisites

To manage roles, you must be logged in as a user with sufficient permissions:

• Assigning and removing org roles requires admin or Org Manager privileges in the target org.
• Assigning and removing space roles requires admin, Org Manager in the parent org, or Space Manager privileges in the target space.

For more information, see Permitted roles in the Cloud Foundry API documentation.

View users in an org or space

To list the users with roles in an org:

cf org-users ORG

Where ORG is the name of the org.

$ cf org-users example-org
Getting users in org example-org as admin...

ORG MANAGER
  alice@example.com

BILLING MANAGER
  huey@example.com

ORG AUDITOR
  louie@example.com

To list the users with roles in a space:

cf space-users ORG SPACE

$ cf space-users example-org example-space
Getting users in org example-org / space example-space as admin...

SPACE MANAGER
  alice@example.com

SPACE DEVELOPER
  huey@example.com
  dewey@example.com

SPACE AUDITOR
  louie@example.com

Assign a role

Assign an org role

To assign an org role to a user:

cf set-org-role USERNAME ORG ROLE

Where:

• USERNAME is the username of the user.
• ORG is the name of the org.
• ROLE is the role to assign. Valid org roles are OrgManager, OrgAuditor, and BillingManager.

$ cf set-org-role huey@example.com example-org OrgManager
Assigning role OrgManager to user huey@example.com in org example-org as admin...
OK

Assign a space role

Before assigning a space role to a user or UAA client, you must first assign them an org role in the parent org. The space role assignment will fail with error code: 1002 otherwise.

To assign a space role to a user:

cf set-space-role USERNAME ORG SPACE ROLE

Where:

• USERNAME is the username of the user.
• ORG is the name of the org that contains the space.
• SPACE is the name of the space.
• ROLE is the role to assign. Valid space roles are SpaceDeveloper, SpaceManager, SpaceAuditor, and SpaceSupporter.

$ cf set-space-role huey@example.com example-org example-space SpaceDeveloper
Assigning role SpaceDeveloper to user huey@example.com in org example-org / space example-space as admin...
OK

Remove a role

To remove an org role from a user:

cf unset-org-role USERNAME ORG ROLE

To remove a space role from a user:

cf unset-space-role USERNAME ORG SPACE ROLE

The arguments follow the same conventions as the corresponding set-*-role commands.

Assign roles to UAA clients

UAA clients can be assigned org and space roles in the same way as users. The client’s UAA client ID takes the place of the username, and you must pass the --client flag to indicate that the subject is a UAA client rather than a user. For more information about UAA clients, see UAA clients in Orgs, Spaces, Roles, and Permissions.

Assign an org role to a client

cf set-org-role CLIENT_ID ORG ROLE --client

$ cf set-org-role my-pipeline-client example-org OrgAuditor --client
Assigning role OrgAuditor to user my-pipeline-client in org example-org as admin...
OK

Assign a space role to a client

cf set-space-role CLIENT_ID ORG SPACE ROLE --client

$ cf set-space-role my-pipeline-client example-org example-space SpaceDeveloper --client
Assigning role SpaceDeveloper to user my-pipeline-client in org example-org / space example-space as admin...
OK

To remove a client role, use cf unset-org-role or cf unset-space-role with the --client flag in the same way.

Note: For automation that requires elevated platform-wide permissions, configure those scopes directly on the UAA client rather than assigning org or space roles. For more information, see Creating and Managing Users with the UAA CLI (UAAC).

Disambiguate users across multiple origins

If a username corresponds to accounts in more than one identity provider — for example, a user exists in both the internal UAA store and an external LDAP store — running cf set-org-role or cf unset-org-role with only a username returns an error:

The user exists in multiple origins. Specify an origin for the requested user from: 'uaa', 'ldap'

Pass the --origin flag to specify which origin’s account to target:

cf set-org-role USERNAME ORG ROLE --origin ORIGIN

Where ORIGIN is the UAA origin key for the identity provider (for example, uaa, ldap, or saml).