Skip to main content Skip to section navigation
U.S. flag

An official website of the United States government

cloud.gov service account

To set up your application to be deployed with an automated system, you need a deployer account that has access to push your application.

Plans

Plan Name Description Cloud Foundry Role
space-deployer A service account for continuous deployment, initially limited to a single space SpaceDeveloper
space-auditor A service account for auditing configuration and monitoring events, initially limited to a single space SpaceAuditor

The space-deployer service account is assigned the SpaceDeveloper role in the space (pushing apps, provisioning services, etc). The space-auditor service account is assigned the SpaceAuditor role in the space (read-only access). For details on the capabilities associated with the SpaceDeveloper and SpaceAuditor roles, please see the Cloud Foundry documentation: https://docs.cloudfoundry.org/concepts/roles.html.

Note: Service accounts will initially be assigned a single role (SpaceDeveloper or SpaceAuditor) in a single space. However, you can add/remove roles for this account in any org and/or space using the cf CLI. Please be sure to read the documentation and understand the ramifications of role modifications before proceeding: https://docs.cloudfoundry.org/concepts/roles.html.

These instances are available in sandbox spaces.

How to create an instance

To create a service instance that can provision service accounts, run the following command:

cf create-service cloud-gov-service-account space-deployer my-service-account

If your service account only requires read access and does not need the ability to deploy applications, use the space-auditor plan instead:

cf create-service cloud-gov-service-account space-auditor my-service-account

Obtaining credentials

To create a service account, bind a service key to the service instance:

cf create-service-key my-service-account my-service-key
cf service-key my-service-account my-service-key

The last command will return a username/password pair, that you can use, like this:

{
 "password": "oYasdfliaweinasfdliecV",
 "username": "deadbeed-aabb-1234-feha0987654321000"
}

This will create a cloud.gov service account and make the credentials available to you via a service key. Keep these credentials secure. If they’re compromised, the way to invalidate the credentials is to delete the service key (you can create another, and it will have a fresh set of credentials). Each service key that you bind to your instance creates a separate service account with different credentials; you can create as many service keys per instance as you like.

After you create one of these service keys, you will see a new “user” in your org and space with a name made of 36 letters, numbers, and dashes as its unique identifier, similar to f6ab4cfb-6e6c-4b10-8585-3f39e740905c. In your event logs, its actions will display as actions by service-account@cloud.gov.

You can use these credentials with the cf auth command in automated deployment scripts.

If you can’t find your service keys

If you’re trying to retrieve credentials for a service instance created before July 7, 2017, those old service instances had a different way of retrieving credentials. You can check this by running cf services to get your service instance name and then running cf service service-instance-name – if the service information includes a link to fugacious.18f.gov, it’s an old service instance. See this post for changes – your best next step is to delete the old service instance and create a new one.

More information

To use this service, see continuous deployment.

Rotating credentials

The service account service creates unique cloud.gov credentials for each service key. To rotate credentials associated with a service key, delete and recreate the service key.

Handling expired passwords

Service account passwords expire every 90 days. If you see an error like:

Error Code: 403
Raw Response: {"error":"access_denied","error_description":"Your current password has expired. Please reset your password."}

Then you’ll need to delete the existing service key, recreate it, and update the username/password in your deployment scripts. For example:

cf delete-service-key my-service-account my-service-key
cf create-service-key my-service-account my-service-key
cf service-key my-service-account my-service-key

The last command will return the service account username/password pair. These steps can be used at any time to update/rotate credentials for service accounts.

Not for human consumption

Don’t use service account credentials to manually log into cloud.gov as a human. cloud.gov has no technical mechanism to prevent you from doing this, because there’s no way to distinguish a human from an automated script at login. Typically, your agency and system security compliance requirements require people to only log in using their own accounts (agency single sign-on accounts or cloud.gov accounts with multi-factor authentication).

The broker in GitHub

You can find the broker here: https://github.com/cloudfoundry-community/uaa-credentials-broker.

cloud.gov

An official website of the U.S. General Services Administration

Looking for U.S. government information and services?
Visit USA.gov