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)".
Deploy UAA
To bootstrap UAA inside VirtualBox:
quaa up
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
Internally, the 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.
Client authentication
The 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
Software versions
See the 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.
Offline download
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.
Spread the word
