Skip to main content

Managing roles in Cloud Foundry

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).