Deprecation/Archive Notice:

The stated rationale for this project were:

Authenticating with cloud.gov can be challenging when developing an app:

• It can be difficult or impossible to log in as multiple different users to manually test your application's functionality.
• If you're offline or on a spotty internet connection, authenticating with cloud.gov may be challenging.
• Because logging into cloud.gov usually involves 2 factor authentication, logging in can be slow and cumbersome, which can slow down development.
• Registering the client ID, client secret, and callback URL in cloud.gov requires creating new identity providers, and you may want a lighter-weight approach for development.
• Debugging problems with the OAuth2 handshake can be difficult because you don't have much visibility into cloud.gov's internal state.
• The fake UAA is intended to solve these problems by making it easy to host your own UAA server on your local system. The simplicity of its implementation and its debugging messages allow developers to easily understand what's going on during the OAuth2 handshake. It also makes it dead simple to log in as multiple different users.

All of these issues are now well-addressed by running UAA in Docker, and we have provided a guide to that at https://cloud.gov/docs/apps/leveraging-authentication/ and in more detail at https://github.com/18F/cg-demos/blob/master/cg-identity/README.md.

Working with Dockerized UAA, one can:

• log in as multiple different users, paul or stefan
• run this without cloud.gov being available (if you use a local uaa.yml and have already download the docker image)
• skip 2-factor auth and just use user/password per your uaa.yml configuration
• fully configure uaa.yml to mimic whatever features of cloud.gov auth that one wants
• debug by connecting to the container and tailing the log file, e.g. docker exec uaa-uaa /usr/bin/tail -f /tomcat/logs/uaa.log

So, we've deprecated this project, and removed references to it from cloud.gov

Thanks to @toolness and others who kept this running until Docker caught up with our needs.

---

This is a fake User Account and Authentication (UAA) server for cloud.gov, useful for development and debugging.

Motivation

Authenticating with cloud.gov can be challenging when developing an app:

• It can be difficult or impossible to log in as multiple different users to manually test your application's functionality.
• If you're offline or on a spotty internet connection, authenticating with cloud.gov may be challenging.
• Because logging into cloud.gov usually involves 2 factor authentication, logging in can be slow and cumbersome, which can slow down development.
• Registering the client ID, client secret, and callback URL in cloud.gov requires creating new identity providers, and you may want a lighter-weight approach for development.
• Debugging problems with the OAuth2 handshake can be difficult because you don't have much visibility into cloud.gov's internal state.

The fake UAA is intended to solve these problems by making it easy to host your own UAA server on your local system. The simplicity of its implementation and its debugging messages allow developers to easily understand what's going on during the OAuth2 handshake. It also makes it dead simple to log in as multiple different users.

Usage

To use this fake UAA, just download the latest release, uncompress the archive, and run the binary in it:

./cg-fake-uaa

The output of this command will help you set things up from there.

Build Requirements

• Go 1.6

Once built, the executable binary is fully self-contained and can be distributed freely.

Development Quick Start

First, get dependencies:

go get -d ./...
go get -u github.com/jteeuwen/go-bindata/...

Then generate and build:

go generate
go build

Finally, run the server:

./cg-fake-uaa

During development, you can define FAKECLOUDGOV_DEBUG=yup to make the server fetch data files from the data directory instead of using the files embedded into the executable at build time.

To learn about changing any of the runtime options, run ./cg-fake-uaa -help.

Running Tests

go test

Running the Example Client

A node-based example OAuth2 client is in the example-client directory. To use it, run:

cd example-client
npm install
npm start

Then visit http://localhost:8000/.

Note that the server, ./cg-fake-uaa, must also be running in order for the client to work.

Running the Example Client on cloud.gov with the cloud.gov UAA

Although we built cg-fake-uaa for testing real client applications with UAA, you can use the client in example-client to demonstrate the capability of the cloud.gov identity provider.

In this example you run the DO-NOT-USE-IN-PRODUCTION example-client.js node application to authenticate real users. You'll need a cloud.gov account, and you should already be logged-in (cf login --sso).

First we'll push the example-client with a random route, and get that route name for later use:

cd example-client/
cf push -m 128M --no-start --random-route id-example
app_route=$(cf apps | grep '^id-example' | awk '{print $NF}')
echo $app_route

Then, create an identity provider service, and service key with the correct callback URL:

cf create-service cloud-gov-identity-provider oauth-client my-uaa-client
sleep 15 # it takes a moment to provision the oauth-client
cf create-service-key my-uaa-client my-service-key \
  -c '{"redirect_uri": ["https://'$app_route'/auth/callback"]}'
cf bind-service id-example my-uaa-client \
  -c '{"redirect_uri": ["https://'$app_route'/auth/callback"]}'

Pass the environment variables for the UAA URLs to the application, and start the app:

cf set-env id-example UAA_AUTH_URL https://login.fr.cloud.gov/oauth/authorize
cf set-env id-example UAA_TOKEN_URL https://uaa.fr.cloud.gov/oauth/token
cf start id-example

At this point you can visit https://$app_route and you'll be prompted to log in. If you complete that, you'll get a welcome page similar to:

Hello fname.lname@agency.gov!

Your access token lasts for another 598 seconds, but will be renewed automatically.

You can also logout.

Cleaning Up the Example Client

cf delete -f id-example
cf delete-service-key -f my-uaa-client my-service-key
cf delete-service -f my-uaa-client

Limitations

The fake server currently has a lot of limitations, most notably:

• Only the openid scope is supported. That is, the server is only really built for giving you the logged-in user's email address.