Skip to content

HTTPS clone URL

Subversion checkout URL

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