The Cloud Foundry UAA is an independent open source project that you can use within your organization to provide user & client authentication and authorization. It has been a stable component of Cloud Foundry itself for more than half a decade. Rather than your team writing their own authentication and authorization subsystem, I recommend giving the UAA a try.
Whilst it is a relatively old open source project, it can still be slightly tricky to deploy for yourself. To make it much easier to deploy a UAA we’ve released a new project Quick UAA. You can deploy a UAA to any cloud or local VirtualBox.
The project includes a simple helper script
quaa, for "Quick UAA". And
quaa up is all it takes to deploy the UAA, with its friendly PostgreSQL database, to your local VirtualBox.
NOTE: the tutorial can download up to 1G of files to your local machine, and upload many of them to your target cloud. If you want to download all the assets first, then deploy the UAA, see the section on Offline Download below.
To install this project, clone the repo, and eval the
bin/quaa env helper. This will download the required
bosh CLI to talk to your cloud infrastructure, and the
uaa CLI for interacting with your UAA:
git clone https://github.com/starkandwayne/quick-uaa-deployment ~/workspace/quick-uaa-deployment cd ~/workspace/quick-uaa-deployment eval "$(bin/quaa env)"
Note, if you have
direnv installed, then you can run
direnv allow instead of
eval "$(bin/quaa env)".
To bootstrap UAA inside VirtualBox:
To see the deployment sequence in action:
Alternately, to bootstrap your UAA to AWS, specify the
--cpi aws flag, fill in the sample
vars.yml, and run
quaa up again:
quaa up --cpi aws vi vars.yml quaa up
quaa up command uses
bosh create-env and the corresponding BOSH CPI for your target cloud infrastructure. A persistent disk will be created, mounted, formatted, and used for your UAA’s PostgreSQL database. You can resize the VM, resize the persistent disk, upgrade the base stemcell, or upgrade the UAA software, all with the same
quaa up command.
quaa helper includes many subcommands to help you interact with your UAA. You can setup the
uaa CLI and authenticate as an admin client:
eval "$(bin/quaa env)" quaa auth-client
Now you can use the
uaa CLI to introspect your UAA, create new users, etc:
uaa clients uaa users uaa create-user drnic -v \ --email [email protected] \ --givenName "Dr Nic" \ --familyName "Williams" \ --password drnic_secret
To see these example commands in action:
Example client applications
There is a growing set of example applications that use your new UAA for their client or user authentication at https://github.com/starkandwayne/ultimate-guide-to-uaa-examples
quick-uaa-deployment/releases for the list of BOSH releases that are included when you run
quaa up from the master branch.
The project has a CI pipeline that tracks all upstream BOSH releases to ensure we keep your UAA as up-to-date as possible.
The instructions above will progressively download any missing CLIs, BOSH releases, and BOSH stemcell. On your first time this can add up to almost 1G. If you need to download everything at once and then proceed with the deployment we are publishing an offline tarball via CDN.
To discover the latest offline tarball, download it, unpack, and bootstrap your quick UAA:
curl -s https://raw.githubusercontent.com/starkandwayne/quick-uaa-deployment/master/bin/download-latest-offline | bash mkdir -p ~/workspace/quick-uaa-deployment tar xfz uaa-deployment-offline-*.tar.gz -C ~/workspace/quick-uaa-deployment
You can now use
~/workspace/quick-uaa-deployment as per the rest of the article above.
cd ~/workspace/quick-uaa-deployment eval "$(bin/u env)" quaa up
Deploy the UAA to Cloud Foundry
In a future article we will introduce the companion project that makes it very easy to deploy the UAA to any Cloud Foundry.