Skip to content

HTTPS clone URL

Subversion checkout URL

You can clone with
or
.
Download ZIP
Newer
Older
100644 259 lines (180 sloc) 9.472 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
d117c68 @dsyer Add useful listings to README
dsyer authored
4 ## Co-ordinates
5
67f369f @tekul CFID-101: Use Apache http client in LegacyAuthenticationManager.
tekul authored
6 * Team:
d117c68 @dsyer Add useful listings to README
dsyer authored
7 * Dale Olds (`olds@vmware.com`)
8 * Dave Syer (`dsyer@vmware.com`)
9 * Luke Taylor (`ltaylor@vmware.com`)
10 * Joel D'Sa (`jdsa@vmware.com`)
11 * Team mailing list: `cfid@vmware.com`
12 * Repository: [http://github.com/vmware-ac/uaa](http://github.com/vmware-ac/uaa)
13 * Issue tracker: [https://issuetracker.springsource.com/browse/CFID](https://issuetracker.springsource.com/browse/CFID)
14 * Docs: [http://github.com/vmware-ac/uaa/wiki](http://github.com/vmware-ac/uaa/wiki)
15
650b10c @dsyer Initial draft - uaa with hard-coded user database
dsyer authored
16 ## Quick Start
ace5777 @daleolds start of UAA
daleolds authored
17
ab32020 @dsyer Update README
dsyer authored
18 If this works you are in business:
ace5777 @daleolds start of UAA
daleolds authored
19
600eda2 @ciberch Update README.md
ciberch authored
20 $ git clone git@github.com:vmware-ac/uaa.git
ab32020 @dsyer Update README
dsyer authored
21 $ cd uaa
22 $ mvn install
39b9174 @tekul Minor edit to README.md (review test)
tekul authored
23
00cf04c @dsyer Simplify integration test incantation
dsyer authored
24 Each module has a `mvn tomcat:run` target to run individually, or you
25 could import them as projects into STS (use 2.8.0 or better if you
26 can). The apps all work together the apps running on the same port
27 (8080) as `/uaa`, `/app` and `/api`.
650b10c @dsyer Initial draft - uaa with hard-coded user database
dsyer authored
28
3c3c502 @tekul Update README and scripts to illustrate the implicit flow login/token…
tekul authored
29 ### Demo of command line usage
650b10c @dsyer Initial draft - uaa with hard-coded user database
dsyer authored
30
3c3c502 @tekul Update README and scripts to illustrate the implicit flow login/token…
tekul authored
31 First run the uaa server as described above:
650b10c @dsyer Initial draft - uaa with hard-coded user database
dsyer authored
32
3c3c502 @tekul Update README and scripts to illustrate the implicit flow login/token…
tekul authored
33 $ cd uaa
00cf04c @dsyer Simplify integration test incantation
dsyer authored
34 $ mvn tomcat:run
650b10c @dsyer Initial draft - uaa with hard-coded user database
dsyer authored
35
3c3c502 @tekul Update README and scripts to illustrate the implicit flow login/token…
tekul authored
36 Then start another terminal and from the project base directory, run:
650b10c @dsyer Initial draft - uaa with hard-coded user database
dsyer authored
37
ff93493 @dsyer CFID-76: Tidy up login and add some rdocs
dsyer authored
38 $ ./gem/bin/uaa target localhost:8080/uaa
39 $ ./gem/bin/uaa login marissa koala
650b10c @dsyer Initial draft - uaa with hard-coded user database
dsyer authored
40
ff93493 @dsyer CFID-76: Tidy up login and add some rdocs
dsyer authored
41 (or leave out the username / password to be prompted).
650b10c @dsyer Initial draft - uaa with hard-coded user database
dsyer authored
42
3c3c502 @tekul Update README and scripts to illustrate the implicit flow login/token…
tekul authored
43 This authenticates and obtains an access token from the server using the OAuth2 implicit
44 grant, similar to the approach intended for a client like VMC. The token is
ff93493 @dsyer CFID-76: Tidy up login and add some rdocs
dsyer authored
45 returned in stdout, so copy paste the value into this next command:
650b10c @dsyer Initial draft - uaa with hard-coded user database
dsyer authored
46
ff93493 @dsyer CFID-76: Tidy up login and add some rdocs
dsyer authored
47 $ ./gem/bin --client_id=app --client_secret=appclientsecret decode <token>
48
49 and you should see your username and the client id of the original
50 token grant on stdout.
650b10c @dsyer Initial draft - uaa with hard-coded user database
dsyer authored
51
6bab6c9 @dsyer Put tomcat in a profile (tomcat)
dsyer authored
52 ## Integration tests
53
54 With all apps deployed into a running server on port 8080 the tests
55 will include integration tests (a check is done before each test that
56 the app is running). You can deploy them in your IDE or using the
00cf04c @dsyer Simplify integration test incantation
dsyer authored
57 command line with `mvn tomcat:run`.
6bab6c9 @dsyer Put tomcat in a profile (tomcat)
dsyer authored
58
00cf04c @dsyer Simplify integration test incantation
dsyer authored
59 For individual modules, or for the whole project, you can also run
60 integration tests from the command line in one go with
6bab6c9 @dsyer Put tomcat in a profile (tomcat)
dsyer authored
61
00cf04c @dsyer Simplify integration test incantation
dsyer authored
62 $ mvn integration-test
6bab6c9 @dsyer Put tomcat in a profile (tomcat)
dsyer authored
63
28afa21 @dsyer Remove or tidy jsps and update README
dsyer authored
64 (This might require an initial `mvn install` from the parent directory
65 to get the wars in your local repo first.)
66
e962246 @dsyer CFID-105: tweak tests and update README for BVT changes
dsyer authored
67 ### BVTs
68
69 There is a really simple cucumber feature spec (`--tag @uaa`) to
70 verify that the UAS server is there. There is also a rake task to
71 launch the integration tests from the `uaa` submodule in `vcap`.
72 Typical usage for a local (`uaa.vcap.me`) instance:
73
74 $ cd vcap/tests
75 $ rake bvt:run_uaa
76
77 To modify the runtime parameters you can provide a `uaa.yml` and set the
78 env var `CLOUD_FOUNDRY_CONFIG_PATH`, e.g.
79
80 $ cat > /tmp/uaa.yml
81 uaa:
82 host: uaa.appcloud21.dev.mozycloud
83 test:
84 username: dev@cloudfoundry.org # defaults to vcap_tester@vmware.com
85 password: changeme
86 email: dev@cloudfoundry.org
87 $ CLOUD_FOUNDRY_CONFIG_PATH=/tmp rake bvt:run_uaa
88
89 The tests will usually fail on the first run because of the 1 sec
90 granularity of the timestamp on the tokens in the cloud_controller (so
91 duplicate tokens will be rejected by the server). When you run the
92 second and subsequent times they should pass because new token values
93 will be obtained from the server.
94
95 You can also change individual properties on the command line with
96 `UAA_ARGS`, which are passed on to the mvn command line, or with
97 MAVEN_OPTS which are passed on to the shell executing mvn, e.g.
98
99 $ UAA_ARGS=-Duaa=uaa.appcloud21.dev.mozycloud rake bvt:run_uaa
100
101 N.B. MAVEN_OPTS cannot be used to set JVM system properties for the tests, but it can be used to set memory limits for the process etc.
102
3c3c502 @tekul Update README and scripts to illustrate the implicit flow login/token…
tekul authored
103 ## Inventory
650b10c @dsyer Initial draft - uaa with hard-coded user database
dsyer authored
104
60e128a @dsyer Add postgres support and and check with PLATFORM=postgresql
dsyer authored
105 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
106
3c3c502 @tekul Update README and scripts to illustrate the implicit flow login/token…
tekul authored
107 1. `uaa` is the actual UAA server
650b10c @dsyer Initial draft - uaa with hard-coded user database
dsyer authored
108
ff93493 @dsyer CFID-76: Tidy up login and add some rdocs
dsyer authored
109 2. `gem` is a ruby gem (`cloudfoundry-uaa`) for interacting with the UAA server
110
111 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
112
ff93493 @dsyer CFID-76: Tidy up login and add some rdocs
dsyer authored
113 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
114
3c3c502 @tekul Update README and scripts to illustrate the implicit flow login/token…
tekul authored
115 In CloudFoundry terms
650b10c @dsyer Initial draft - uaa with hard-coded user database
dsyer authored
116
3c3c502 @tekul Update README and scripts to illustrate the implicit flow login/token…
tekul authored
117 * `uaa` provides an authentication service plus authorized delegation for
118 back-end services and apps (by issuing OAuth2 access tokens).
650b10c @dsyer Initial draft - uaa with hard-coded user database
dsyer authored
119
3c3c502 @tekul Update README and scripts to illustrate the implicit flow login/token…
tekul authored
120 * `api` is `api.cloudfoundry.com` - it's a service which provides resources
121 which other applications may wish to access on behalf of the resource
122 owner (the end user).
650b10c @dsyer Initial draft - uaa with hard-coded user database
dsyer authored
123
3c3c502 @tekul Update README and scripts to illustrate the implicit flow login/token…
tekul authored
124 * `app` is `code.cloudfoundry.com` or `studio.cloudfoundry.com` - a
125 webapp that needs single sign on and access to the `api` service on
126 behalf of users.
650b10c @dsyer Initial draft - uaa with hard-coded user database
dsyer authored
127
92647e4 @dsyer Upgrade to Spring 3.1
dsyer authored
128 ## UAA Server
129
3c3c502 @tekul Update README and scripts to illustrate the implicit flow login/token…
tekul authored
130 The authentication service is `uaa`. It's a plain Spring MVC webapp.
131 Deploy as normal in Tomcat or your container of choice, or execute
f274eb9 @dsyer Update README for Tomcat
dsyer authored
132 `mvn tomcat:run` to run it directly from `uaa` directory in the source tree.
3c3c502 @tekul Update README and scripts to illustrate the implicit flow login/token…
tekul authored
133 When running with maven it listen on port 8080.
650b10c @dsyer Initial draft - uaa with hard-coded user database
dsyer authored
134
3c3c502 @tekul Update README and scripts to illustrate the implicit flow login/token…
tekul authored
135 It supports the APIs defined in the UAA-APIs document. To summarise:
650b10c @dsyer Initial draft - uaa with hard-coded user database
dsyer authored
136
3c3c502 @tekul Update README and scripts to illustrate the implicit flow login/token…
tekul authored
137 1. The OAuth2 /authorize and /token endpoints
650b10c @dsyer Initial draft - uaa with hard-coded user database
dsyer authored
138
3c3c502 @tekul Update README and scripts to illustrate the implicit flow login/token…
tekul authored
139 2. A /login_info endpoint to allow querying for required login prompts
650b10c @dsyer Initial draft - uaa with hard-coded user database
dsyer authored
140
3c3c502 @tekul Update README and scripts to illustrate the implicit flow login/token…
tekul authored
141 3. A /check_token endpoint, to allow resource servers to obtain information about
142 an access token submitted by an OAuth2 client.
650b10c @dsyer Initial draft - uaa with hard-coded user database
dsyer authored
143
92647e4 @dsyer Upgrade to Spring 3.1
dsyer authored
144 4. SCIM user provisioning endpoint
650b10c @dsyer Initial draft - uaa with hard-coded user database
dsyer authored
145
92647e4 @dsyer Upgrade to Spring 3.1
dsyer authored
146 5. OpenID connect endpoints to support authentication /userinfo and
147 /check_id (todo). Implemented roughly enough to get it working (so
148 /app authenticates here), but not to meet the spec.
e578bc0 @dsyer CFID-36: tidy up and add some docs
dsyer authored
149
150 Authentication can be performed by command line clients by submitting
60e128a @dsyer Add postgres support and and check with PLATFORM=postgresql
dsyer authored
151 credentials directly to the `/authorize` endpoint (as described in
e578bc0 @dsyer CFID-36: tidy up and add some docs
dsyer authored
152 UAA-API doc). There is an `ImplicitAccessTokenProvider` in Spring
92647e4 @dsyer Upgrade to Spring 3.1
dsyer authored
153 Security OAuth that can do the heavy lifting if your client is Java.
154
155 By default `uaa` will launch with a context root `/uaa`. There is a
156 Maven profile `vcap` to launch with context root `/`.
157
ff268de @dsyer CFID-96: remove private profile and initialise empty database with ad…
dsyer authored
158 ### Configuration
159
160 There is a `uaa.yml` in the application which provides defaults to the
161 placeholders in the Spring XML. Wherever you see
162 `${placeholder.name}` in the XML there is an opportunity to override
163 it either by providing a System property (`-D` to JVM) with the same
164 name, or an environment-specific `uaa.yml` under
165 `env['CLOUD_FOUNDRY_CONFIG_PATH']/uaa.yml`. When vcap is deployed the
166 `CLOUD_FOUNDRY_CONFIG_PATH` is defined according to the way it was
167 installed.
168
169 All passwords and client secrets in the config files must be encypted
170 using BCrypt. In Java you can do it like this (with
171 `spring-securty-crypto` on the classpath):
172
173 String password = BCrypt.hashpw("plaintext");
174
175 In ruby you can do it like this:
176
177 require 'bcrypt'
178 password = BCrypt::Password.create('plaintext')
179
92647e4 @dsyer Upgrade to Spring 3.1
dsyer authored
180 ### User Account Data
181
182 The default is to use an in-memory, hash-based user store that is
183 pre-populated with some test users: e.g. `dale` has password
184 `password` and `marissa` has password `koala`.
185
ff268de @dsyer CFID-96: remove private profile and initialise empty database with ad…
dsyer authored
186 To use a RDBMS for user data, activate the Spring profiles `jdbc` and
5dde792 @dsyer Some housekeeping:
dsyer authored
187 one of `hsqldb` or `postgresql`. The opposite is `!jdbc` which needs
188 to be specified explicitly if any other profiles are active. The
189 `hsqldb` profile will start up with an in-memory RDBMS by default.
650b10c @dsyer Initial draft - uaa with hard-coded user database
dsyer authored
190
8c2d455 @tekul Added spring profile usage info to readme
tekul authored
191 The active profiles can be configured by passing the
192 `spring.profiles.active` parameter to the JVM. For, example to run
193 with an embedded HSQL database:
194
ff268de @dsyer CFID-96: remove private profile and initialise empty database with ad…
dsyer authored
195 mvn -Dspring.profiles.active=jdbc,hsqldb,!legacy tomcat:run
8c2d455 @tekul Added spring profile usage info to readme
tekul authored
196
197 Or to use PostgreSQL instead of HSQL:
198
ff268de @dsyer CFID-96: remove private profile and initialise empty database with ad…
dsyer authored
199 mvn -Dspring.profiles.active=jdbc,postgresql,!legacy tomcat:run
67f369f @tekul CFID-101: Use Apache http client in LegacyAuthenticationManager.
tekul authored
200
ff268de @dsyer CFID-96: remove private profile and initialise empty database with ad…
dsyer authored
201 To bootstrap a microcloud type environment you need an admin user.
202 For this there is a database initializer component that inserts an
203 admin user if it finds an empty database on startup. Override the
204 default settings (username/password=admin/admin) in `uaa.yml`:
205
206 bootstrap:
207 admin:
208 username: foo
209 password: $2a$10$yHj...
210 email: admin@test.com
211 family_name: Piper
212 given_name: Peter
213
214 (the password has to be bcrypted).
215
216 ### Legacy Mode
217
218 There is a legacy mode where the CF.com cloud controller is used for
219 the authentication and token generation. To use this, launch the app
220 with Spring profile `legacy` (a Maven profile with the same name is
221 provided for convenience as well). The opposite is `!legacy` which
222 needs to be specified explicitly if any other profiles are active.
223 The cloud controller login URL defaults to
224 `http://api.cloudfoundry.com/users/{username}/tokens` - to override it
225 provide a System property or `uaa.yml` entry for
67f369f @tekul CFID-101: Use Apache http client in LegacyAuthenticationManager.
tekul authored
226 `cloud_controller.login_url`.
8c2d455 @tekul Added spring profile usage info to readme
tekul authored
227
3c3c502 @tekul Update README and scripts to illustrate the implicit flow login/token…
tekul authored
228 ## The API Application
650b10c @dsyer Initial draft - uaa with hard-coded user database
dsyer authored
229
3c3c502 @tekul Update README and scripts to illustrate the implicit flow login/token…
tekul authored
230 An example resource server. It hosts a service which returns
231 a list of mock applications under `/apps`.
650b10c @dsyer Initial draft - uaa with hard-coded user database
dsyer authored
232
00cf04c @dsyer Simplify integration test incantation
dsyer authored
233 Run it using `mvn tomcat:run` from the `api` directory (once all other
234 tomcat processes have been shutdown). This will deploy the app to a
235 Tomcat manager on port 8080.
650b10c @dsyer Initial draft - uaa with hard-coded user database
dsyer authored
236
237 ## The App Application
238
39b9174 @tekul Minor edit to README.md (review test)
tekul authored
239 This is a user interface app (primarily aimed at browsers) that uses
e578bc0 @dsyer CFID-36: tidy up and add some docs
dsyer authored
240 OpenId Connect for authentication (i.e. SSO) and OAuth2 for access
241 grants. It authenticates with the Auth service, and then accesses
00cf04c @dsyer Simplify integration test incantation
dsyer authored
242 resources in the API service. Run it with `mvn tomcat:run` from the
243 `app` directory (once all other tomcat processes have been shutdown).
650b10c @dsyer Initial draft - uaa with hard-coded user database
dsyer authored
244
245 ### Use Cases
246
ab32020 @dsyer Update README
dsyer authored
247 1. See all apps
650b10c @dsyer Initial draft - uaa with hard-coded user database
dsyer authored
248
39b9174 @tekul Minor edit to README.md (review test)
tekul authored
249 GET /app/apps
650b10c @dsyer Initial draft - uaa with hard-coded user database
dsyer authored
250
251 browser is redirected through a series of authentication and access
252 grant steps (which could be slimmed down to implicit steps not
253 requiring user at some point), and then the photos are shown.
254
ab32020 @dsyer Update README
dsyer authored
255 2. See the currently logged in user details, a bag of attributes
650b10c @dsyer Initial draft - uaa with hard-coded user database
dsyer authored
256 grabbed from the open id provider
257
ab32020 @dsyer Update README
dsyer authored
258 GET /app
Something went wrong with that request. Please try again.