Skip to content
Newer
Older
100644 506 lines (365 sloc) 17.7 KB
39b9174 @tekul Minor edit to README.md (review test)
tekul authored Dec 6, 2011
1 <link href="https://raw.github.com/clownfart/Markdown-CSS/master/markdown.css" rel="stylesheet"></link>
3c3c502 @tekul Update README and scripts to illustrate the implicit flow login/token…
tekul authored Oct 28, 2011
2 # CloudFoundry User Account and Authentication (UAA) Server
ace5777 @daleolds start of UAA
daleolds authored Oct 11, 2011
3
126fd01 @dsyer CFID-265: tidy client config and add docs
dsyer authored May 29, 2012
4 The UAA is the identity management service for Cloud Foundry. It's
5 primary role is as an OAuth2 provider, issuing tokens for client
6 applications to use when they act on behalf of Cloud Foundry users.
7 It can also authenticate users with their Cloud Foundry credentials,
8 and can act as an SSO service using those credentials (or others). It
9 has endpoints for managing user accounts and for registering OAuth2
10 clients, as well as various other management functions.
11
d117c68 @dsyer Add useful listings to README
dsyer authored Jan 5, 2012
12 ## Co-ordinates
13
67f369f @tekul CFID-101: Use Apache http client in LegacyAuthenticationManager.
tekul authored Jan 20, 2012
14 * Team:
d117c68 @dsyer Add useful listings to README
dsyer authored Jan 5, 2012
15 * Dale Olds (`olds@vmware.com`)
16 * Dave Syer (`dsyer@vmware.com`)
17 * Luke Taylor (`ltaylor@vmware.com`)
18 * Joel D'Sa (`jdsa@vmware.com`)
c68ad47 @tekul CFID-374: Add password strength API to UAA API doc.
tekul authored Aug 1, 2012
19 * Vidya Valmikinathan
20 * Technical forum: [vcap-dev google group](https://groups.google.com/a/cloudfoundry.org/forum/?fromgroups#!forum/vcap-dev)
f2a6532 @dsyer Fix link to docs in README to work with github
dsyer authored Jun 7, 2012
21 * Docs: [docs/](https://github.com/cloudfoundry/uaa/tree/master/docs)
d117c68 @dsyer Add useful listings to README
dsyer authored Jan 5, 2012
22
650b10c @dsyer Initial draft - uaa with hard-coded user database
dsyer authored Oct 26, 2011
23 ## Quick Start
ace5777 @daleolds start of UAA
daleolds authored Oct 12, 2011
24
ab32020 @dsyer Update README
dsyer authored Oct 27, 2011
25 If this works you are in business:
ace5777 @daleolds start of UAA
daleolds authored Oct 12, 2011
26
8cefad2 @tekul Minor update to README.
tekul authored Feb 4, 2013
27 $ git clone git://github.com/cloudfoundry/uaa.git
ab32020 @dsyer Update README
dsyer authored Oct 27, 2011
28 $ cd uaa
29 $ mvn install
39b9174 @tekul Minor edit to README.md (review test)
tekul authored Dec 6, 2011
30
00cf04c @dsyer Simplify integration test incantation
dsyer authored Nov 22, 2011
31 Each module has a `mvn tomcat:run` target to run individually, or you
32 could import them as projects into STS (use 2.8.0 or better if you
33 can). The apps all work together the apps running on the same port
3471d8f @bmidgley documentation updates uaac etc
bmidgley authored Dec 6, 2012
34 (8080) as `/uaa`, `/app` and `/api`.
35
36 You will need Maven 3.0.4 or newer.
650b10c @dsyer Initial draft - uaa with hard-coded user database
dsyer authored Oct 26, 2011
37
96aa258 Update README to include Bug filing info per Deepika
Chloe Jackson authored Jul 19, 2012
38 ### Deploy to Cloud Foundry
bb43295 @dsyer Add vmc push instructions
dsyer authored Jul 9, 2012
39
40 You can also build the app and push it to Cloud Foundry, e.g.
41
3471d8f @bmidgley documentation updates uaac etc
bmidgley authored Dec 6, 2012
42 $ mvn package install
bb43295 @dsyer Add vmc push instructions
dsyer authored Jul 9, 2012
43 $ vmc push myuaa --path uaa/target
44
45 (If you do that, choose a unique application id, not 'myuaa'.)
46
47 ### Demo of command line usage on local server
650b10c @dsyer Initial draft - uaa with hard-coded user database
dsyer authored Oct 26, 2011
48
73e67fa @andypiper clarified documentation and explained how to run gem against cloud fo…
andypiper authored Apr 10, 2012
49 First run the UAA server as described above:
650b10c @dsyer Initial draft - uaa with hard-coded user database
dsyer authored Oct 26, 2011
50
3c3c502 @tekul Update README and scripts to illustrate the implicit flow login/token…
tekul authored Oct 28, 2011
51 $ cd uaa
00cf04c @dsyer Simplify integration test incantation
dsyer authored Nov 22, 2011
52 $ mvn tomcat:run
650b10c @dsyer Initial draft - uaa with hard-coded user database
dsyer authored Oct 26, 2011
53
73e67fa @andypiper clarified documentation and explained how to run gem against cloud fo…
andypiper authored Apr 10, 2012
54 Then start another terminal and from the project base directory, ask
07d4762 @dsyer CFID-41, CFID-214: again don't make any assumptions about the database
dsyer authored Mar 26, 2012
55 the login endpoint to tell you about the system:
56
57 $ curl -H "Accept: application/json" localhost:8080/uaa/login
58 {
59 "timestamp":"2012-03-28T18:25:49+0100",
60 "commit_id":"111274e",
61 "prompts":{"username":["text","Username"],
62 "password":["password","Password"]
63 }
64 }
65
66 Then you can try logging in with the UAA ruby gem. Make sure you have
67 ruby 1.9, and bundler installed, then
650b10c @dsyer Initial draft - uaa with hard-coded user database
dsyer authored Oct 26, 2011
68
73e67fa @andypiper clarified documentation and explained how to run gem against cloud fo…
andypiper authored Apr 10, 2012
69 $ cd gem/; bundle
3471d8f @bmidgley documentation updates uaac etc
bmidgley authored Dec 6, 2012
70 $ ./bin/uaac target http://localhost:8080/uaa
71 $ ./bin/uaac token get marissa koala
650b10c @dsyer Initial draft - uaa with hard-coded user database
dsyer authored Oct 26, 2011
72
ff93493 @dsyer CFID-76: Tidy up login and add some rdocs
dsyer authored Feb 5, 2012
73 (or leave out the username / password to be prompted).
650b10c @dsyer Initial draft - uaa with hard-coded user database
dsyer authored Oct 26, 2011
74
fb10cbe @dsyer CFID-233,CFID-214: changes in SECOAUTH require updates to config, and…
dsyer authored Apr 13, 2012
75 This authenticates and obtains an access token from the server using
76 the OAuth2 implicit grant, similar to the approach intended for a
def3acb @dsyer Update README for uaac (new gem)
dsyer authored Jun 7, 2012
77 client like VMC. The token is stored in `~/.uuac.yml`, so dig into
78 that file and pull out the access token for your `vmc` target (or use
79 `--verbose` on the login command line above to see it logged to your
80 console).
650b10c @dsyer Initial draft - uaa with hard-coded user database
dsyer authored Oct 26, 2011
81
def3acb @dsyer Update README for uaac (new gem)
dsyer authored Jun 7, 2012
82 Then you can login as a resource server and retrieve the token
83 details:
84
85 $ ./bin/uaac target http://localhost:8080/uaa app
86 $ ./bin/uaac login token [token-value-from-above]
ff93493 @dsyer CFID-76: Tidy up login and add some rdocs
dsyer authored Feb 5, 2012
87
def3acb @dsyer Update README for uaac (new gem)
dsyer authored Jun 7, 2012
88 You will be prompted for the client secret (`appclientsecret`), and
89 then you should see your username and the client id of the original
90 token grant on stdout, e.g.
91
c68ad47 @tekul CFID-374: Add password strength API to UAA API doc.
tekul authored Aug 1, 2012
92 id: 6e1ac414-f446-4869-9b41-41f1f41b96df
def3acb @dsyer Update README for uaac (new gem)
dsyer authored Jun 7, 2012
93 resource-ids:
94 - tokens
95 - openid
96 - cloud_controller
97 - password
98 expires-at: 1339120767
99 scope:
100 - read
101 - write
102 - openid
103 - password
104 email: marissa@test.org
105 client-authorities:
106 - ROLE_UNTRUSTED
107 expires-in: 43158
108 user-authorities:
109 - uaa.user
110 user-id: marissa
111 client-id: vmc
112 token-id: 90162e5c-228d-4620-b457-83e2d591eedf
73e67fa @andypiper clarified documentation and explained how to run gem against cloud fo…
andypiper authored Apr 10, 2012
113
bb43295 @dsyer Add vmc push instructions
dsyer authored Jul 9, 2012
114 ### Demo of command line usage on cloudfoundry.com
73e67fa @andypiper clarified documentation and explained how to run gem against cloud fo…
andypiper authored Apr 10, 2012
115
def3acb @dsyer Update README for uaac (new gem)
dsyer authored Jun 7, 2012
116 The same command line example should work against a UAA running on
117 cloudfoundry.com (except for the token decoding bit because you won't
118 have the client secret). In this case, there is no need to run a local
119 uaa server, so simply ask the external login endpoint to tell you
120 about the system:
73e67fa @andypiper clarified documentation and explained how to run gem against cloud fo…
andypiper authored Apr 10, 2012
121
122 $ curl -H "Accept: application/json" uaa.cloudfoundry.com/login
123 {
124 "prompts":{"username":["text","Username"],
125 "password":["password","Password"]
126 }
127 }
128
129 You can then try logging in with the UAA ruby gem. Make sure you have ruby 1.9, and bundler installed, then
130
131 $ cd gem/; bundle
def3acb @dsyer Update README for uaac (new gem)
dsyer authored Jun 7, 2012
132 $ ./bin/uaac target uaa.cloudfoundry.com vmc
133 $ ./bin/uaac login implicit [yourusername] [yourpassword]
73e67fa @andypiper clarified documentation and explained how to run gem against cloud fo…
andypiper authored Apr 10, 2012
134
135 (or leave out the username / password to be prompted).
136
137 This authenticates and obtains an access token from the server using the OAuth2 implicit
def3acb @dsyer Update README for uaac (new gem)
dsyer authored Jun 7, 2012
138 grant, the same as used by a client like VMC.
650b10c @dsyer Initial draft - uaa with hard-coded user database
dsyer authored Oct 26, 2011
139
6bab6c9 @dsyer Put tomcat in a profile (tomcat)
dsyer authored Nov 14, 2011
140 ## Integration tests
141
142 With all apps deployed into a running server on port 8080 the tests
143 will include integration tests (a check is done before each test that
144 the app is running). You can deploy them in your IDE or using the
fb10cbe @dsyer CFID-233,CFID-214: changes in SECOAUTH require updates to config, and…
dsyer authored Apr 13, 2012
145 command line with `mvn tomcat:run` and then run the tests as normal.
6bab6c9 @dsyer Put tomcat in a profile (tomcat)
dsyer authored Nov 14, 2011
146
00cf04c @dsyer Simplify integration test incantation
dsyer authored Nov 22, 2011
147 For individual modules, or for the whole project, you can also run
fb10cbe @dsyer CFID-233,CFID-214: changes in SECOAUTH require updates to config, and…
dsyer authored Apr 13, 2012
148 integration tests and the server from the command line in one go with
6bab6c9 @dsyer Put tomcat in a profile (tomcat)
dsyer authored Nov 14, 2011
149
917374e @dsyer CFID-228: extract common JAR (now requires Maven 3 for tomcat)
dsyer authored Mar 30, 2012
150 $ mvn test -P integration
6bab6c9 @dsyer Put tomcat in a profile (tomcat)
dsyer authored Nov 14, 2011
151
28afa21 @dsyer Remove or tidy jsps and update README
dsyer authored Nov 15, 2011
152 (This might require an initial `mvn install` from the parent directory
153 to get the wars in your local repo first.)
154
fb10cbe @dsyer CFID-233,CFID-214: changes in SECOAUTH require updates to config, and…
dsyer authored Apr 13, 2012
155 To make the tests work in various environments you can modify the
156 configuration of the server and the tests (e.g. the admin client)
157 using a variety of mechanisms. The simplest is to provide additional
158 Maven profiles on the command line, e.g.
159
160 $ (cd uaa; mvn test -P vcap)
161
162 will run the integration tests against a uaa server running in a local
163 vcap, so for example the service URL is set to `uaa.vcap.me` (by
164 default). There are several Maven profiles to play with, and they can
165 be used to run the server, or the tests or both:
166
167 * `local`: runs the server on the ROOT context `http://localhost:8080/`
168
169 * `vcap`: also runs the server on the ROOT context and points the
170 tests at `uaa.vcap.me`.
171
172 * `devuaa`: points the tests at `http://devuaa.cloudfoundry.com` (an
173 instance of UAA deployed on cloudfoundry).
174
175 All these profiles set the `CLOUD_FOUNDRY_CONFIG_PATH` to pick up a
176 `uaa.yml` and (if appropriate) set the context root for running the
177 server (see below for more detail on that).
178
e962246 @dsyer CFID-105: tweak tests and update README for BVT changes
dsyer authored Jan 27, 2012
179 ### BVTs
180
181 There is a really simple cucumber feature spec (`--tag @uaa`) to
07d4762 @dsyer CFID-41, CFID-214: again don't make any assumptions about the database
dsyer authored Mar 26, 2012
182 verify that the UAA server is there. There is also a rake task to
e962246 @dsyer CFID-105: tweak tests and update README for BVT changes
dsyer authored Jan 27, 2012
183 launch the integration tests from the `uaa` submodule in `vcap`.
184 Typical usage for a local (`uaa.vcap.me`) instance:
185
186 $ cd vcap/tests
187 $ rake bvt:run_uaa
188
fb10cbe @dsyer CFID-233,CFID-214: changes in SECOAUTH require updates to config, and…
dsyer authored Apr 13, 2012
189 You can change the most common important settings with environment
190 variables (see below), or with a custom `uaa.yml`. N.B. `MAVEN_OPTS`
191 cannot be used to set JVM system properties for the tests, but it can
192 be used to set memory limits for the process etc.
193
194 ### Custom YAML Configuration
195
07d4762 @dsyer CFID-41, CFID-214: again don't make any assumptions about the database
dsyer authored Mar 26, 2012
196 To modify the runtime parameters you can provide a `uaa.yml`, e.g.
e962246 @dsyer CFID-105: tweak tests and update README for BVT changes
dsyer authored Jan 27, 2012
197
198 $ cat > /tmp/uaa.yml
199 uaa:
200 host: uaa.appcloud21.dev.mozycloud
201 test:
202 username: dev@cloudfoundry.org # defaults to vcap_tester@vmware.com
203 password: changeme
204 email: dev@cloudfoundry.org
fb10cbe @dsyer CFID-233,CFID-214: changes in SECOAUTH require updates to config, and…
dsyer authored Apr 13, 2012
205
206 then from `vcap-tests`
207
e962246 @dsyer CFID-105: tweak tests and update README for BVT changes
dsyer authored Jan 27, 2012
208 $ CLOUD_FOUNDRY_CONFIG_PATH=/tmp rake bvt:run_uaa
07d4762 @dsyer CFID-41, CFID-214: again don't make any assumptions about the database
dsyer authored Mar 26, 2012
209
fb10cbe @dsyer CFID-233,CFID-214: changes in SECOAUTH require updates to config, and…
dsyer authored Apr 13, 2012
210 or from `uaa/uaa`
e962246 @dsyer CFID-105: tweak tests and update README for BVT changes
dsyer authored Jan 27, 2012
211
fb10cbe @dsyer CFID-233,CFID-214: changes in SECOAUTH require updates to config, and…
dsyer authored Apr 13, 2012
212 $ CLOUD_FOUNDRY_CONFIG_PATH=/tmp mvn test
07d4762 @dsyer CFID-41, CFID-214: again don't make any assumptions about the database
dsyer authored Mar 26, 2012
213
fb10cbe @dsyer CFID-233,CFID-214: changes in SECOAUTH require updates to config, and…
dsyer authored Apr 13, 2012
214 The integration tests look for a Yaml file in the following locations
215 (later entries override earlier ones), and the webapp does the same
216 when it starts up so you can use the same config file for both:
217
218 classpath:uaa.yml
219 file:${CLOUD_FOUNDRY_CONFIG_PATH}/uaa.yml
220 file:${UAA_CONFIG_FILE}
221 ${UAA_CONFIG_URL}
222
223 ### Using Maven with Cloud Foundry or VCAP
224
225 To test against a vcap instance use the Maven profile `vcap` (it
226 switches off some of the tests that create random client and user
227 accounts):
07d4762 @dsyer CFID-41, CFID-214: again don't make any assumptions about the database
dsyer authored Mar 26, 2012
228
229 $ (cd uaa; mvn test -P vcap)
fb10cbe @dsyer CFID-233,CFID-214: changes in SECOAUTH require updates to config, and…
dsyer authored Apr 13, 2012
230
07d4762 @dsyer CFID-41, CFID-214: again don't make any assumptions about the database
dsyer authored Mar 26, 2012
231 To change the target server it should suffice to set
f1d1a89 @dsyer CFID-230: update UAA docs
dsyer authored Apr 2, 2012
232 `VCAP_BVT_TARGET` (the tests prefix it with `uaa.` to form the
917374e @dsyer CFID-228: extract common JAR (now requires Maven 3 for tomcat)
dsyer authored Mar 30, 2012
233 server url), e.g.
234
fb10cbe @dsyer CFID-233,CFID-214: changes in SECOAUTH require updates to config, and…
dsyer authored Apr 13, 2012
235 $ VCAP_BVT_TARGET=appcloud21.dev.mozycloud mvn test -P vcap
236
237 You can also override some of the other most important default
238 settings using environment variables. The defaults as usual come from
239 `uaa.yml` but tests will search first in an environment variable:
e962246 @dsyer CFID-105: tweak tests and update README for BVT changes
dsyer authored Jan 27, 2012
240
fb10cbe @dsyer CFID-233,CFID-214: changes in SECOAUTH require updates to config, and…
dsyer authored Apr 13, 2012
241 * `UAA_ADMIN_CLIENT_ID` the client id for bootstrapping client
242 registrations needed for the rest of the tests.
e962246 @dsyer CFID-105: tweak tests and update README for BVT changes
dsyer authored Jan 27, 2012
243
3314a09 @tekul Fix some doc typos
tekul authored Aug 7, 2012
244 * `UAA_ADMIN_CLIENT_SECRET` the client secret for bootstrapping client
fb10cbe @dsyer CFID-233,CFID-214: changes in SECOAUTH require updates to config, and…
dsyer authored Apr 13, 2012
245 registrations
246
3314a09 @tekul Fix some doc typos
tekul authored Aug 7, 2012
247 All other settings from `uaa.yml` can be overridden individually as
fb10cbe @dsyer CFID-233,CFID-214: changes in SECOAUTH require updates to config, and…
dsyer authored Apr 13, 2012
248 system properties. Running in an IDE this is easy just using whatever
249 features allow you to modify the JVM in test runs, but using Maven you
250 have to use the `argLine` property to get settings passed onto the
251 test JVM, e.g.
252
253 $ mvn -DargLine=-Duaa.test.username=foo test
254
255 will create an account with `userName=foo` for testing (instead using
256 the default setting from `uaa.yml`).
257
258 If you prefer environment variables to system properties you can use a
259 custom `uaa.yml` with placeholders for your environment variables,
260 e.g.
261
262 uaa:
263 test:
264 username: ${UAA_TEST_USERNAME:marissa}
e962246 @dsyer CFID-105: tweak tests and update README for BVT changes
dsyer authored Jan 27, 2012
265
fb10cbe @dsyer CFID-233,CFID-214: changes in SECOAUTH require updates to config, and…
dsyer authored Apr 13, 2012
266 will look for an environment variable (or system property)
267 `UAA_TEST_USERNAME` before defaulting to `marissa`. This is the trick
268 used to expose `UAA_ADMIN_CLIENT_SECRET` etc. in the standard
269 configuration.
e962246 @dsyer CFID-105: tweak tests and update README for BVT changes
dsyer authored Jan 27, 2012
270
3c3c502 @tekul Update README and scripts to illustrate the implicit flow login/token…
tekul authored Oct 28, 2011
271 ## Inventory
650b10c @dsyer Initial draft - uaa with hard-coded user database
dsyer authored Oct 26, 2011
272
60e128a @dsyer Add postgres support and and check with PLATFORM=postgresql
dsyer authored Dec 1, 2011
273 There are actually several projects here, the main `uaa` server application and some samples:
650b10c @dsyer Initial draft - uaa with hard-coded user database
dsyer authored Oct 26, 2011
274
917374e @dsyer CFID-228: extract common JAR (now requires Maven 3 for tomcat)
dsyer authored Mar 30, 2012
275 0. `common` is a module containing a JAR with all the business logic. It is used in
276 the webapps below.
277
3c3c502 @tekul Update README and scripts to illustrate the implicit flow login/token…
tekul authored Oct 28, 2011
278 1. `uaa` is the actual UAA server
650b10c @dsyer Initial draft - uaa with hard-coded user database
dsyer authored Oct 26, 2011
279
0c65ef3 @joeldsa Changed the name of the gem to cf-uaa-client
joeldsa authored Feb 15, 2012
280 2. `gem` is a ruby gem (`cf-uaa-client`) for interacting with the UAA server
ff93493 @dsyer CFID-76: Tidy up login and add some rdocs
dsyer authored Feb 5, 2012
281
282 3. `api` (sample) is an OAuth2 resource service which returns a mock list of deployed apps
650b10c @dsyer Initial draft - uaa with hard-coded user database
dsyer authored Oct 26, 2011
283
ff93493 @dsyer CFID-76: Tidy up login and add some rdocs
dsyer authored Feb 5, 2012
284 4. `app` (sample) is a user application that uses both of the above
650b10c @dsyer Initial draft - uaa with hard-coded user database
dsyer authored Oct 26, 2011
285
126fd01 @dsyer CFID-265: tidy client config and add docs
dsyer authored May 29, 2012
286 5. `login` (sample) is an application that performs authentication for the UAA acting as a back end service
287
3c3c502 @tekul Update README and scripts to illustrate the implicit flow login/token…
tekul authored Oct 28, 2011
288 In CloudFoundry terms
650b10c @dsyer Initial draft - uaa with hard-coded user database
dsyer authored Oct 26, 2011
289
3c3c502 @tekul Update README and scripts to illustrate the implicit flow login/token…
tekul authored Oct 28, 2011
290 * `uaa` provides an authentication service plus authorized delegation for
291 back-end services and apps (by issuing OAuth2 access tokens).
650b10c @dsyer Initial draft - uaa with hard-coded user database
dsyer authored Oct 26, 2011
292
f6a4503 @joeldsa Remove legacy application examples from the README
joeldsa authored Nov 26, 2012
293 * `api` is a service that provides resources that other applications may
294 wish to access on behalf of the resource owner (the end user).
295
296 * `app` is a webapp that needs single sign on and access to the `api`
297 service on behalf of users.
650b10c @dsyer Initial draft - uaa with hard-coded user database
dsyer authored Oct 26, 2011
298
126fd01 @dsyer CFID-265: tidy client config and add docs
dsyer authored May 29, 2012
299 * `login` is where Cloud Foundry administrators set up their
300 authentication sources, e.g. LDAP/AD, SAML, OpenID (Google etc.) or
76ada2b @dsyer [cfid-337] Remove login sample
dsyer authored Nov 21, 2012
301 social. The cloudfoundry.com platform uses a different
302 implementation of the
303 [login server](https://github.com/cloudfoundry/login-server).
650b10c @dsyer Initial draft - uaa with hard-coded user database
dsyer authored Oct 26, 2011
304
92647e4 @dsyer Upgrade to Spring 3.1
dsyer authored Dec 15, 2011
305 ## UAA Server
306
3c3c502 @tekul Update README and scripts to illustrate the implicit flow login/token…
tekul authored Oct 28, 2011
307 The authentication service is `uaa`. It's a plain Spring MVC webapp.
308 Deploy as normal in Tomcat or your container of choice, or execute
afc88bb @dsyer CFID-257: Tidy README and API docs and add extra instructions for ins…
dsyer authored Apr 19, 2012
309 `mvn tomcat:run` to run it directly from `uaa` directory in the source
310 tree (make sure the common jar is installed first using `mvn install`
311 from the common subdirectory or from the top level directory). When
312 running with maven it listens on port 8080.
650b10c @dsyer Initial draft - uaa with hard-coded user database
dsyer authored Oct 26, 2011
313
afc88bb @dsyer CFID-257: Tidy README and API docs and add extra instructions for ins…
dsyer authored Apr 19, 2012
314 The UAA Server supports the APIs defined in the UAA-APIs document. To summarise:
650b10c @dsyer Initial draft - uaa with hard-coded user database
dsyer authored Oct 26, 2011
315
3c3c502 @tekul Update README and scripts to illustrate the implicit flow login/token…
tekul authored Oct 28, 2011
316 1. The OAuth2 /authorize and /token endpoints
650b10c @dsyer Initial draft - uaa with hard-coded user database
dsyer authored Oct 26, 2011
317
3c3c502 @tekul Update README and scripts to illustrate the implicit flow login/token…
tekul authored Oct 28, 2011
318 2. A /login_info endpoint to allow querying for required login prompts
650b10c @dsyer Initial draft - uaa with hard-coded user database
dsyer authored Oct 26, 2011
319
3c3c502 @tekul Update README and scripts to illustrate the implicit flow login/token…
tekul authored Oct 28, 2011
320 3. A /check_token endpoint, to allow resource servers to obtain information about
321 an access token submitted by an OAuth2 client.
650b10c @dsyer Initial draft - uaa with hard-coded user database
dsyer authored Oct 26, 2011
322
92647e4 @dsyer Upgrade to Spring 3.1
dsyer authored Dec 15, 2011
323 4. SCIM user provisioning endpoint
650b10c @dsyer Initial draft - uaa with hard-coded user database
dsyer authored Oct 26, 2011
324
92647e4 @dsyer Upgrade to Spring 3.1
dsyer authored Dec 15, 2011
325 5. OpenID connect endpoints to support authentication /userinfo and
326 /check_id (todo). Implemented roughly enough to get it working (so
327 /app authenticates here), but not to meet the spec.
e578bc0 @dsyer CFID-36: tidy up and add some docs
dsyer authored Nov 9, 2011
328
329 Authentication can be performed by command line clients by submitting
60e128a @dsyer Add postgres support and and check with PLATFORM=postgresql
dsyer authored Dec 1, 2011
330 credentials directly to the `/authorize` endpoint (as described in
e578bc0 @dsyer CFID-36: tidy up and add some docs
dsyer authored Nov 9, 2011
331 UAA-API doc). There is an `ImplicitAccessTokenProvider` in Spring
92647e4 @dsyer Upgrade to Spring 3.1
dsyer authored Dec 15, 2011
332 Security OAuth that can do the heavy lifting if your client is Java.
333
334 By default `uaa` will launch with a context root `/uaa`. There is a
afc88bb @dsyer CFID-257: Tidy README and API docs and add extra instructions for ins…
dsyer authored Apr 19, 2012
335 Maven profile `local` to launch with context root `/`, and another
336 called `vcap` to launch at `/` with a postgresql backend.
92647e4 @dsyer Upgrade to Spring 3.1
dsyer authored Dec 15, 2011
337
ff268de @dsyer CFID-96: remove private profile and initialise empty database with ad…
dsyer authored Jan 18, 2012
338 ### Configuration
339
340 There is a `uaa.yml` in the application which provides defaults to the
341 placeholders in the Spring XML. Wherever you see
342 `${placeholder.name}` in the XML there is an opportunity to override
343 it either by providing a System property (`-D` to JVM) with the same
afc88bb @dsyer CFID-257: Tidy README and API docs and add extra instructions for ins…
dsyer authored Apr 19, 2012
344 name, or a custom `uaa.yml` (as described above).
ff268de @dsyer CFID-96: remove private profile and initialise empty database with ad…
dsyer authored Jan 18, 2012
345
07d4762 @dsyer CFID-41, CFID-214: again don't make any assumptions about the database
dsyer authored Mar 26, 2012
346 All passwords and client secrets in the config files are plain text,
347 but they will be inserted into the UAA database encrypted with BCrypt.
ff268de @dsyer CFID-96: remove private profile and initialise empty database with ad…
dsyer authored Jan 18, 2012
348
92647e4 @dsyer Upgrade to Spring 3.1
dsyer authored Dec 15, 2011
349 ### User Account Data
350
07d4762 @dsyer CFID-41, CFID-214: again don't make any assumptions about the database
dsyer authored Mar 26, 2012
351 The default is to use an in-memory RDBMS user store that is
352 pre-populated with a single test users: `marissa` has password
353 `koala`.
92647e4 @dsyer Upgrade to Spring 3.1
dsyer authored Dec 15, 2011
354
07d4762 @dsyer CFID-41, CFID-214: again don't make any assumptions about the database
dsyer authored Mar 26, 2012
355 To use Postgresql for user data, activate one of the Spring profiles
356 `hsqldb` or `postgresql`.
650b10c @dsyer Initial draft - uaa with hard-coded user database
dsyer authored Oct 26, 2011
357
07d4762 @dsyer CFID-41, CFID-214: again don't make any assumptions about the database
dsyer authored Mar 26, 2012
358 The active profiles can be configured in `uaa.yml` using
359
360 spring_profiles: postgresql
361
362 or by passing the `spring.profiles.active` parameter to the JVM. For,
363 example to run with an embedded HSQL database:
8c2d455 @tekul Added spring profile usage info to readme
tekul authored Dec 19, 2011
364
07d4762 @dsyer CFID-41, CFID-214: again don't make any assumptions about the database
dsyer authored Mar 26, 2012
365 mvn -Dspring.profiles.active=hsqldb tomcat:run
8c2d455 @tekul Added spring profile usage info to readme
tekul authored Dec 19, 2011
366
367 Or to use PostgreSQL instead of HSQL:
368
07d4762 @dsyer CFID-41, CFID-214: again don't make any assumptions about the database
dsyer authored Mar 26, 2012
369 mvn -Dspring.profiles.active=postgresql tomcat:run
67f369f @tekul CFID-101: Use Apache http client in LegacyAuthenticationManager.
tekul authored Jan 20, 2012
370
07d4762 @dsyer CFID-41, CFID-214: again don't make any assumptions about the database
dsyer authored Mar 26, 2012
371 To bootstrap a microcloud type environment you need an admin client.
ff268de @dsyer CFID-96: remove private profile and initialise empty database with ad…
dsyer authored Jan 18, 2012
372 For this there is a database initializer component that inserts an
07d4762 @dsyer CFID-41, CFID-214: again don't make any assumptions about the database
dsyer authored Mar 26, 2012
373 admin client. If the default profile is active (i.e. not
374 `postgresql`) there is also a `vmc` client so that the gem login works
375 out of the box. You can override the default settings and add
376 additional clients in `uaa.yml`:
377
378 oauth:
379 clients:
380 admin:
381 authorized-grant-types: client_credentials
382 scope: read,write,password
f1d1a89 @dsyer CFID-230: update UAA docs
dsyer authored Apr 2, 2012
383 authorities: ROLE_CLIENT,ROLE_ADIN
07d4762 @dsyer CFID-41, CFID-214: again don't make any assumptions about the database
dsyer authored Mar 26, 2012
384 id: admin
385 secret: adminclientsecret
386 resource-ids: clients
387
388 The admin client can be used to create additional clients (but not to
389 do anything much else). A client with read/write access to the `scim`
390 resource will be needed to create user accounts. The integration
391 tests take care of this automatically, inserting client and user
392 accounts as necessary to make the tests work.
8c2d455 @tekul Added spring profile usage info to readme
tekul authored Dec 19, 2011
393
3c3c502 @tekul Update README and scripts to illustrate the implicit flow login/token…
tekul authored Oct 28, 2011
394 ## The API Application
650b10c @dsyer Initial draft - uaa with hard-coded user database
dsyer authored Oct 26, 2011
395
3c3c502 @tekul Update README and scripts to illustrate the implicit flow login/token…
tekul authored Oct 28, 2011
396 An example resource server. It hosts a service which returns
397 a list of mock applications under `/apps`.
650b10c @dsyer Initial draft - uaa with hard-coded user database
dsyer authored Oct 26, 2011
398
00cf04c @dsyer Simplify integration test incantation
dsyer authored Nov 22, 2011
399 Run it using `mvn tomcat:run` from the `api` directory (once all other
400 tomcat processes have been shutdown). This will deploy the app to a
401 Tomcat manager on port 8080.
650b10c @dsyer Initial draft - uaa with hard-coded user database
dsyer authored Oct 26, 2011
402
403 ## The App Application
404
39b9174 @tekul Minor edit to README.md (review test)
tekul authored Dec 6, 2011
405 This is a user interface app (primarily aimed at browsers) that uses
e578bc0 @dsyer CFID-36: tidy up and add some docs
dsyer authored Nov 9, 2011
406 OpenId Connect for authentication (i.e. SSO) and OAuth2 for access
407 grants. It authenticates with the Auth service, and then accesses
00cf04c @dsyer Simplify integration test incantation
dsyer authored Nov 22, 2011
408 resources in the API service. Run it with `mvn tomcat:run` from the
409 `app` directory (once all other tomcat processes have been shutdown).
650b10c @dsyer Initial draft - uaa with hard-coded user database
dsyer authored Oct 26, 2011
410
126fd01 @dsyer CFID-265: tidy client config and add docs
dsyer authored May 29, 2012
411 The application can operate in multiple different profiles according
412 to the location (and presence) of the UAA server and the Login
413 application. By default it will look for a UAA on
414 `localhost:8080/uaa`, but you can change this by setting an
415 environment variable (or System property) called `UAA_PROFILE`. In
416 the application source code (`src/main/resources`) you will find
417 multiple properties files pre-configured with different likely
418 locations for those servers. They are all in the form
419 `application-<UAA_PROFILE>.properties` and the naming convention
420 adopted is that the `UAA_PROFILE` is `local` for the localhost
421 deployment, `vcap` for a `vcap.me` deployment, `staging` for a staging
422 deployment (inside VMware VPN), etc. The profile names are double
423 barrelled (e.g. `local-vcap` when the login server is in a different
424 location than the UAA server).
425
650b10c @dsyer Initial draft - uaa with hard-coded user database
dsyer authored Oct 26, 2011
426 ### Use Cases
427
ab32020 @dsyer Update README
dsyer authored Oct 27, 2011
428 1. See all apps
650b10c @dsyer Initial draft - uaa with hard-coded user database
dsyer authored Oct 26, 2011
429
39b9174 @tekul Minor edit to README.md (review test)
tekul authored Dec 6, 2011
430 GET /app/apps
650b10c @dsyer Initial draft - uaa with hard-coded user database
dsyer authored Oct 26, 2011
431
126fd01 @dsyer CFID-265: tidy client config and add docs
dsyer authored May 29, 2012
432 browser is redirected through a series of authentication and
433 access grant steps (which could be slimmed down to implicit steps
434 not requiring user at some point), and then the photos are shown.
650b10c @dsyer Initial draft - uaa with hard-coded user database
dsyer authored Oct 26, 2011
435
ab32020 @dsyer Update README
dsyer authored Oct 27, 2011
436 2. See the currently logged in user details, a bag of attributes
650b10c @dsyer Initial draft - uaa with hard-coded user database
dsyer authored Oct 26, 2011
437 grabbed from the open id provider
438
ab32020 @dsyer Update README
dsyer authored Oct 27, 2011
439 GET /app
126fd01 @dsyer CFID-265: tidy client config and add docs
dsyer authored May 29, 2012
440
441 ## The Login Application
442
443 A user interface for authentication. The UAA can also authenticate
444 user accounts, but only if it manages them itself, and it only
445 provides a basic UI. The Login app can be branded and customized for
446 non-native authentication and for more complicate UI flows, like user
447 registration and password reset.
448
449 The login application is actually itself an OAuth2 endpoint provider,
450 but delegates those features to the UAA server. Configuration for the
451 login application therefore consists of locating the UAA through its
452 OAuth2 endpoint URLs, and registering the login application itself as
453 a client of the UAA. There is a `login.yml` for the UAA locations,
454 e.g. for a local `vcap` instance:
455
456 uaa:
457 url: http://uaa.vcap.me
458 token:
459 url: http://uaa.vcap.me/oauth/token
460 login:
461 url: http://uaa.vcap.me/login.do
462
463 and there is an environment variable (or Java System property),
464 `LOGIN_SECRET` for the client secret that the app uses when it
465 authenticates itself with the UAA. The Login app is registered by
466 default in the UAA only if there are no active Spring profiles (so not
3314a09 @tekul Fix some doc typos
tekul authored Aug 7, 2012
467 at all in `vcap`). In the UAA you can find the registration in the
126fd01 @dsyer CFID-265: tidy client config and add docs
dsyer authored May 29, 2012
468 `oauth-clients.xml` config file. Here's a summary:
469
c68ad47 @tekul CFID-374: Add password strength API to UAA API doc.
tekul authored Aug 1, 2012
470 id: login
471 secret: loginsecret
126fd01 @dsyer CFID-265: tidy client config and add docs
dsyer authored May 29, 2012
472 authorized-grant-types: client_credentials
c68ad47 @tekul CFID-374: Add password strength API to UAA API doc.
tekul authored Aug 1, 2012
473 authorities: ROLE_LOGIN
126fd01 @dsyer CFID-265: tidy client config and add docs
dsyer authored May 29, 2012
474 resource-ids: oauth
475
476 ### Use Cases
477
478 1. Authenticate
479
480 GET /login
481
482 The sample app presents a form login interface for the backend
483 UAA, and also an OpenID widget so the user can authenticate using
484 Google etc. credentials.
485
486 2. Approve OAuth2 token grant
487
488 GET /oauth/authorize?client_id=app&response_type=code...
489
490 Standard OAuth2 Authorization Endpoint. Client credentials and
491 all other features are handled by the UAA in the back end, and the
492 login application is used to render the UI (see
493 `access_confirmation.jsp`).
494
495 3. Obtain access token
496
497 POST /oauth/token
498
499 Standard OAuth2 Authorization Endpoint passed through to the UAA.
96aa258 Update README to include Bug filing info per Deepika
Chloe Jackson authored Jul 19, 2012
500
501 ## File a Bug
502
503 To file a bug against Cloud Foundry Open Source and its components, sign up and use our
504 bug tracking system: [http://cloudfoundry.atlassian.net](http://cloudfoundry.atlassian.net)
126fd01 @dsyer CFID-265: tidy client config and add docs
dsyer authored May 29, 2012
505
Something went wrong with that request. Please try again.