Browse files

CFID-265: tidy client config and add docs

Change-Id: Ibfc638b451b99e7ef7b59873218342d057e500bf
  • Loading branch information...
dsyer committed May 29, 2012
1 parent c7464e7 commit 126fd01242c21e318b01d7a548bc7d1b2d847ccb
@@ -1,6 +1,14 @@
<link href="" rel="stylesheet"></link>
# CloudFoundry User Account and Authentication (UAA) Server
+The UAA is the identity management service for Cloud Foundry. It's
+primary role is as an OAuth2 provider, issuing tokens for client
+applications to use when they act on behalf of Cloud Foundry users.
+It can also authenticate users with their Cloud Foundry credentials,
+and can act as an SSO service using those credentials (or others). It
+has endpoints for managing user accounts and for registering OAuth2
+clients, as well as various other management functions.
## Co-ordinates
* Team:
@@ -9,7 +17,7 @@
* Luke Taylor (``)
* Joel D'Sa (``)
* Team mailing list: ``
-* Docs: docs/
+* Docs: [docs/](
## Quick Start
@@ -244,6 +252,8 @@ the webapps below.
4. `app` (sample) is a user application that uses both of the above
+5. `login` (sample) is an application that performs authentication for the UAA acting as a back end service
In CloudFoundry terms
* `uaa` provides an authentication service plus authorized delegation for
@@ -256,6 +266,10 @@ In CloudFoundry terms
* `app` is `` or `` - a
webapp that needs single sign on and access to the `api` service on
behalf of users.
+* `login` is where Cloud Foundry administrators set up their
+ authentication sources, e.g. LDAP/AD, SAML, OpenID (Google etc.) or
+ social.
## UAA Server
@@ -363,17 +377,93 @@ grants. It authenticates with the Auth service, and then accesses
resources in the API service. Run it with `mvn tomcat:run` from the
`app` directory (once all other tomcat processes have been shutdown).
+The application can operate in multiple different profiles according
+to the location (and presence) of the UAA server and the Login
+application. By default it will look for a UAA on
+`localhost:8080/uaa`, but you can change this by setting an
+environment variable (or System property) called `UAA_PROFILE`. In
+the application source code (`src/main/resources`) you will find
+multiple properties files pre-configured with different likely
+locations for those servers. They are all in the form
+`application-<UAA_PROFILE>.properties` and the naming convention
+adopted is that the `UAA_PROFILE` is `local` for the localhost
+deployment, `vcap` for a `` deployment, `staging` for a staging
+deployment (inside VMware VPN), etc. The profile names are double
+barrelled (e.g. `local-vcap` when the login server is in a different
+location than the UAA server).
### Use Cases
1. See all apps
GET /app/apps
- browser is redirected through a series of authentication and access
- grant steps (which could be slimmed down to implicit steps not
- requiring user at some point), and then the photos are shown.
+ browser is redirected through a series of authentication and
+ access grant steps (which could be slimmed down to implicit steps
+ not requiring user at some point), and then the photos are shown.
2. See the currently logged in user details, a bag of attributes
grabbed from the open id provider
GET /app
+## The Login Application
+A user interface for authentication. The UAA can also authenticate
+user accounts, but only if it manages them itself, and it only
+provides a basic UI. The Login app can be branded and customized for
+non-native authentication and for more complicate UI flows, like user
+registration and password reset.
+The login application is actually itself an OAuth2 endpoint provider,
+but delegates those features to the UAA server. Configuration for the
+login application therefore consists of locating the UAA through its
+OAuth2 endpoint URLs, and registering the login application itself as
+a client of the UAA. There is a `login.yml` for the UAA locations,
+e.g. for a local `vcap` instance:
+ uaa:
+ url:
+ token:
+ url:
+ login:
+ url:
+and there is an environment variable (or Java System property),
+`LOGIN_SECRET` for the client secret that the app uses when it
+authenticates itself with the UAA. The Login app is registered by
+default in the UAA only if there are no active Spring profiles (so not
+at all in `vcap`). In the UAA you can find the registation in the
+`oauth-clients.xml` config file. Here's a summary:
+ id: login
+ secret: loginsecret
+ authorized-grant-types: client_credentials
+ authorities: ROLE_LOGIN
+ resource-ids: oauth
+### Use Cases
+1. Authenticate
+ GET /login
+ The sample app presents a form login interface for the backend
+ UAA, and also an OpenID widget so the user can authenticate using
+ Google etc. credentials.
+2. Approve OAuth2 token grant
+ GET /oauth/authorize?client_id=app&response_type=code...
+ Standard OAuth2 Authorization Endpoint. Client credentials and
+ all other features are handled by the UAA in the back end, and the
+ login application is used to render the UI (see
+ `access_confirmation.jsp`).
+3. Obtain access token
+ POST /oauth/token
+ Standard OAuth2 Authorization Endpoint passed through to the UAA.
@@ -12,9 +12,9 @@
@@ -133,7 +133,7 @@
<entry key="id" value="login" />
<entry key="secret" value="loginsecret" />
<entry key="authorized-grant-types" value="client_credentials" />
- <entry key="authorities" value="ROLE_CLIENT,ROLE_RESOURCE" />
+ <entry key="authorities" value="ROLE_LOGIN" />
<entry key="resource-ids" value="oauth" />

0 comments on commit 126fd01

Please sign in to comment.