Cloud Foundry is a distributed system with many components front and back end. If you are familiar with the Cloud Foundry architecture you have probably noticed that the Cloud Controller exposes its functionality via lightweight HTTP APIs. The internal components also use the same approach to communicate with each other. Up until recently this was done using a custom authentication mechanism which had some drawbacks. This blog post will walk you through the changes that we are making in this area.
We created a new component to handle all external user-facing security concerns named the User Account and Authentication Service or UAA for short. It has been live in cloudfoundry.com since March 2012, and is now starting to play a big role in the interactions between Cloud Foundry users and the platform. This article explains the basic features of the UAA and the role that it plays for users and administrators of Cloud Foundry.
Design Goals of the UAA
- Web applications need to be able to authenticate users and access platform resources on their behalf without collecting user credentials. (Several examples of applications collecting user credentials have been brought to our attention but until the UAA was available, there was no way to offer an alternative.)
- The system needs to be able to grow, with more components being added by the platform and by users (for example providing management UIs for existing applications or for deploying new applications or services).
- It should provide Single Sign On (SSO) for all user-facing applications in the platform.
- It should support cross-platform and polyglot programming for users of the platform APIs.
- It should be easy to strategize the authentication mechanism for social (e.g., sign on with GitHub) and enterprise (e.g., corporate AD) scenarios.
Security is not something to skimp on during implementation. One way to be sure that you have the bases covered and to reassure users that their data is safe is to use standard protocols and interfaces because they have been vetted by many security engineers and reviewed by a board of approvers. Open standards tend to get a large community behind the implementation and documentation of client libraries and utilities, so they make it much easier to support a wide range of users. For that reason, we chose to use some of the latest and greatest open standards in the UAA, the most important of which is OAuth2. Also worth mentioning are SCIM and OpenID Connect (the latter spec is still unstable so we haven’t fully implemented it yet).
Quick Introduction to OAuth2
OAuth2 is a protocol enabling a Client application, often a web application, to act on behalf of a User, but with the User’s permission. The actions a Client is allowed to perform are carried out on a Resource Server (another web application or web service), and the User approves the actions by telling an Authorization Server that he trusts the Client to do what it is asking. Clients can also act as themselves (not on behalf of a User) if they are permitted to do so by the Authorization Server.
The Cloud Foundry UAA is an Authorization Server and also a Resource Server (e.g. for resources to do with user accounts). Another Resource Server in Cloud Foundry is the Cloud Controller, which is the main interface for managing user’s applications and services. There are some more detailed descriptions of authentication and authorization flows, including sequence diagrams, later in this article.
UAA Quick Start
The quickest way to see the UAA in action is to point your browser at http://uaa.cloudfoundry.com. If you have a Cloud Foundry account you can login and see a basic home page just confirming that you are authenticated. Log out by clicking on the link at the top right.
On a command line you can also interrogate the UAA a bit to see what it is doing:
$ curl -H "Accept: application/json" uaa.cloudfoundry.com/login { "timestamp":"2012-06-21T10:52:35-0700", "commit_id":"b19eb89", "prompts":{ "username":["text","Username"], "password":["password","Password"] } }The response tells you when the UAA was built, the git commit id from GitHub and the information it needs at its login endpoint to authenticate a user.
The code is also deployed with its default configuration as a Cloud Foundry app called devuaa: http://devuaa.cloudfoundry.com. You can use this deployment for testing if you don’t want to deploy it yourself. Out of the box, the UAA runs with an in-memory back end, and one user account (username: marissa, password: koala). To build the server yourself and see it working locally you can clone the project and follow the instructions in the README on GitHub.
The normal flow for a web application wishing to act on behalf of a user is the Authorization Code Flow. Here is a sequence diagram of the interactions when the user is already authenticated:
Sequence diagram, auth-code-flow, with an already authenticated user (steps 2-4)
User->Client: GET /peek
participant AuthServer
activate User
activate Client
Client->User: 302: location=auth/authorize
deactivate User
deactivate Client
User->AuthServer: GET /authorize
activate User
activate AuthServer
AuthServer->User: {messages: "Do you approve?"}
deactivate User
deactivate AuthServer
User->AuthServer: approve
activate User
activate AuthServer
AuthServer->User: 302: location=client/handle_code?code=dkshfjg
deactivate User
deactivate AuthServer
User->Client: GET /handle_code?code=dkshfjg
activate User
activate Client
Client->AuthServer: POST: /token?code=dkshfjg
activate AuthServer
AuthServer->Client: 200: {access_token:CNMBVCXKVY}
deactivate AuthServer
Client->ResourceServer: GET /resource(access_token)
activate ResourceServer
ResourceServer->Client: 200: response
deactivate ResourceServer
Client->User: 200: result
deactivate Client
deactivate User
Out of the box, the UAA also has an OAuth2 client called app, so you can see part of the OAuth2 Authorization Code Flow by visiting this link in your browser. Log in as marissa and you might see the user approval page where marissa confirms that she allows the Client known as ‘app’ to access her profile data (scope=openid).
You might not see that page because someone else may already have been there and approved the access and obtained an access token, so the server will not need to prompt again. The access token is a memo for the approval, so if no access token was granted, then you will see the approval page. Approve the grant by pressing the “Authorize” button and you should see the browser bounce back to http://localhost/nolink (intentionally non-existent) with a query parameter containing an authorization code.
Getting an access token is another step (which the Client application would normally take), exchanging the authorization code for the access token on the Token Endpoint at https://devuaa.cloudfoundry.com/oauth/token. There is no UI for the Token Endpoint, so nothing to see in the browser, but if you visit that location you should be prompted for authentication details because the Token Endpoint uses HTTP Basic to authenticate Client applications.
The command line client that most people use with Cloud Foundry is vmc. For historic and practical reasons, vmc collects user credentials directly on the command line, so it’s not a browser flow. The UAA advertises what credentials it requires on its /login endpoint, and vmc collects the data and sends it, getting a token in return. OAuth2 has a Resource Owner Password grant type that could have been used for the legacy Cloud Foundry, but is too restrictive for future purposes because it is limited to username-password authentication. Instead of using that, we used the Implicit Flow with a couple enhancements. This is how it works:
Sequence diagram, vmc-implicit-flow:
title Implicit Grant, Automatic Approval Client
participant User
User->Client: login
activate User
activate Client
Client->AuthServer: {client_id: vmc, credentials={...}}
activate AuthServer
AuthServer->AuthServer: authenticate and create_token
AuthServer->Client: 302, Location=urn:redirect#access_token=HGFDSASJHG
deactivate AuthServer
Client->User: access_token
For a detailed description of all the features of the UAA in version 1.0 see the UAA Reference Blog Post.
Login Server
The UAA can and does handle authentication of users with Cloud Foundry accounts. It only knows how to do username-password authentication, and only for registered users, which is fine for basic use cases, e.g., for vmc users who are accustomed to logging in with a password. To go beyond that, for instance to allow users to authenticate with social network accounts, or with an external identity provider like VMware Horizon, or an enterprise directory, you have two choices. Either 1) fork the UAA and modify the authentication filters and login UI, or 2) deploy another component that can handle authentication and delegate everything else to the UAA. We call 2) a Login Server, and that is the design we will be adopting soon in cloudfoundry.com. There are two sample apps (one in Java and one in Ruby) that show you how to implement a Login Server in the samples directory of the UAA.
Conclusion
The UAA handles all the user-facing security concerns in Cloud Foundry, and also provides some back-end services for other components in the platform, as well as some that can be used by a user’s own applications. Its primary role is as an OAuth2 Authorization Server, but many other services are provided in connection with user accounts and client registrations. We will soon be providing more detailed examples of how to use the UAA in the form of some more articles on the cloudfoundry.org and cloudfoundry.com blog sites. The range of services supported by the UAA and its registered clients is also expanding so watch out for blogs on new features.
