Skip to content

HTTPS clone URL

Subversion checkout URL

You can clone with HTTPS or Subversion.

Download ZIP
Newer
Older
100644 227 lines (155 sloc) 8.034 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
6 * Team:
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
2c2d2c2 @dsyer Update README for new ports
dsyer authored
38 $ ./login.sh "localhost:8080/uaa"
650b10c @dsyer Initial draft - uaa with hard-coded user database
dsyer authored
39
3c3c502 @tekul Update README and scripts to illustrate the implicit flow login/token…
tekul authored
40 And hit return twice to accept the default username and password.
650b10c @dsyer Initial draft - uaa with hard-coded user database
dsyer authored
41
3c3c502 @tekul Update README and scripts to illustrate the implicit flow login/token…
tekul authored
42 This authenticates and obtains an access token from the server using the OAuth2 implicit
43 grant, similar to the approach intended for a client like VMC. The token is
44 stored in the file `.access_token`.
650b10c @dsyer Initial draft - uaa with hard-coded user database
dsyer authored
45
00cf04c @dsyer Simplify integration test incantation
dsyer authored
46 Now kill the `uaa` server and run the `api` server (which starts the
47 `uaa` server as well):
39b9174 @tekul Minor edit to README.md (review test)
tekul authored
48
60e128a @dsyer Add postgres support and and check with PLATFORM=postgresql
dsyer authored
49 $ cd samples/api
00cf04c @dsyer Simplify integration test incantation
dsyer authored
50 $ mvn tomcat:run
650b10c @dsyer Initial draft - uaa with hard-coded user database
dsyer authored
51
3c3c502 @tekul Update README and scripts to illustrate the implicit flow login/token…
tekul authored
52 And then (from the base directory) execute:
650b10c @dsyer Initial draft - uaa with hard-coded user database
dsyer authored
53
f274eb9 @dsyer Update README for Tomcat
dsyer authored
54 $ ./get.sh http://localhost:8080/api/apps
650b10c @dsyer Initial draft - uaa with hard-coded user database
dsyer authored
55
3c3c502 @tekul Update README and scripts to illustrate the implicit flow login/token…
tekul authored
56 which should return a JSON array of (pretend) running applications.
650b10c @dsyer Initial draft - uaa with hard-coded user database
dsyer authored
57
6bab6c9 @dsyer Put tomcat in a profile (tomcat)
dsyer authored
58 ## Integration tests
59
60 With all apps deployed into a running server on port 8080 the tests
61 will include integration tests (a check is done before each test that
62 the app is running). You can deploy them in your IDE or using the
00cf04c @dsyer Simplify integration test incantation
dsyer authored
63 command line with `mvn tomcat:run`.
6bab6c9 @dsyer Put tomcat in a profile (tomcat)
dsyer authored
64
00cf04c @dsyer Simplify integration test incantation
dsyer authored
65 For individual modules, or for the whole project, you can also run
66 integration tests from the command line in one go with
6bab6c9 @dsyer Put tomcat in a profile (tomcat)
dsyer authored
67
00cf04c @dsyer Simplify integration test incantation
dsyer authored
68 $ mvn integration-test
6bab6c9 @dsyer Put tomcat in a profile (tomcat)
dsyer authored
69
28afa21 @dsyer Remove or tidy jsps and update README
dsyer authored
70 (This might require an initial `mvn install` from the parent directory
71 to get the wars in your local repo first.)
72
3c3c502 @tekul Update README and scripts to illustrate the implicit flow login/token…
tekul authored
73 ## Inventory
650b10c @dsyer Initial draft - uaa with hard-coded user database
dsyer authored
74
60e128a @dsyer Add postgres support and and check with PLATFORM=postgresql
dsyer authored
75 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
76
3c3c502 @tekul Update README and scripts to illustrate the implicit flow login/token…
tekul authored
77 1. `uaa` is the actual UAA server
650b10c @dsyer Initial draft - uaa with hard-coded user database
dsyer authored
78
60e128a @dsyer Add postgres support and and check with PLATFORM=postgresql
dsyer authored
79 2. `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
80
60e128a @dsyer Add postgres support and and check with PLATFORM=postgresql
dsyer authored
81 3. `app` (sample) is a user application that uses both of the above
650b10c @dsyer Initial draft - uaa with hard-coded user database
dsyer authored
82
3c3c502 @tekul Update README and scripts to illustrate the implicit flow login/token…
tekul authored
83 In CloudFoundry terms
650b10c @dsyer Initial draft - uaa with hard-coded user database
dsyer authored
84
3c3c502 @tekul Update README and scripts to illustrate the implicit flow login/token…
tekul authored
85 * `uaa` provides an authentication service plus authorized delegation for
86 back-end services and apps (by issuing OAuth2 access tokens).
650b10c @dsyer Initial draft - uaa with hard-coded user database
dsyer authored
87
3c3c502 @tekul Update README and scripts to illustrate the implicit flow login/token…
tekul authored
88 * `api` is `api.cloudfoundry.com` - it's a service which provides resources
89 which other applications may wish to access on behalf of the resource
90 owner (the end user).
650b10c @dsyer Initial draft - uaa with hard-coded user database
dsyer authored
91
3c3c502 @tekul Update README and scripts to illustrate the implicit flow login/token…
tekul authored
92 * `app` is `code.cloudfoundry.com` or `studio.cloudfoundry.com` - a
93 webapp that needs single sign on and access to the `api` service on
94 behalf of users.
650b10c @dsyer Initial draft - uaa with hard-coded user database
dsyer authored
95
92647e4 @dsyer Upgrade to Spring 3.1
dsyer authored
96 ## UAA Server
97
3c3c502 @tekul Update README and scripts to illustrate the implicit flow login/token…
tekul authored
98 The authentication service is `uaa`. It's a plain Spring MVC webapp.
99 Deploy as normal in Tomcat or your container of choice, or execute
f274eb9 @dsyer Update README for Tomcat
dsyer authored
100 `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
101 When running with maven it listen on port 8080.
650b10c @dsyer Initial draft - uaa with hard-coded user database
dsyer authored
102
3c3c502 @tekul Update README and scripts to illustrate the implicit flow login/token…
tekul authored
103 It supports the APIs defined in the UAA-APIs document. To summarise:
650b10c @dsyer Initial draft - uaa with hard-coded user database
dsyer authored
104
3c3c502 @tekul Update README and scripts to illustrate the implicit flow login/token…
tekul authored
105 1. The OAuth2 /authorize and /token endpoints
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 2. A /login_info endpoint to allow querying for required login prompts
650b10c @dsyer Initial draft - uaa with hard-coded user database
dsyer authored
108
3c3c502 @tekul Update README and scripts to illustrate the implicit flow login/token…
tekul authored
109 3. A /check_token endpoint, to allow resource servers to obtain information about
110 an access token submitted by an OAuth2 client.
650b10c @dsyer Initial draft - uaa with hard-coded user database
dsyer authored
111
92647e4 @dsyer Upgrade to Spring 3.1
dsyer authored
112 4. SCIM user provisioning endpoint
650b10c @dsyer Initial draft - uaa with hard-coded user database
dsyer authored
113
92647e4 @dsyer Upgrade to Spring 3.1
dsyer authored
114 5. OpenID connect endpoints to support authentication /userinfo and
115 /check_id (todo). Implemented roughly enough to get it working (so
116 /app authenticates here), but not to meet the spec.
e578bc0 @dsyer CFID-36: tidy up and add some docs
dsyer authored
117
118 Authentication can be performed by command line clients by submitting
60e128a @dsyer Add postgres support and and check with PLATFORM=postgresql
dsyer authored
119 credentials directly to the `/authorize` endpoint (as described in
e578bc0 @dsyer CFID-36: tidy up and add some docs
dsyer authored
120 UAA-API doc). There is an `ImplicitAccessTokenProvider` in Spring
92647e4 @dsyer Upgrade to Spring 3.1
dsyer authored
121 Security OAuth that can do the heavy lifting if your client is Java.
122
123 By default `uaa` will launch with a context root `/uaa`. There is a
124 Maven profile `vcap` to launch with context root `/`.
125
ff268de @dsyer CFID-96: remove private profile and initialise empty database with ad…
dsyer authored
126 ### Configuration
127
128 There is a `uaa.yml` in the application which provides defaults to the
129 placeholders in the Spring XML. Wherever you see
130 `${placeholder.name}` in the XML there is an opportunity to override
131 it either by providing a System property (`-D` to JVM) with the same
132 name, or an environment-specific `uaa.yml` under
133 `env['CLOUD_FOUNDRY_CONFIG_PATH']/uaa.yml`. When vcap is deployed the
134 `CLOUD_FOUNDRY_CONFIG_PATH` is defined according to the way it was
135 installed.
136
137 All passwords and client secrets in the config files must be encypted
138 using BCrypt. In Java you can do it like this (with
139 `spring-securty-crypto` on the classpath):
140
141 String password = BCrypt.hashpw("plaintext");
142
143 In ruby you can do it like this:
144
145 require 'bcrypt'
146 password = BCrypt::Password.create('plaintext')
147
92647e4 @dsyer Upgrade to Spring 3.1
dsyer authored
148 ### User Account Data
149
150 The default is to use an in-memory, hash-based user store that is
151 pre-populated with some test users: e.g. `dale` has password
152 `password` and `marissa` has password `koala`.
153
ff268de @dsyer CFID-96: remove private profile and initialise empty database with ad…
dsyer authored
154 To use a RDBMS for user data, activate the Spring profiles `jdbc` and
5dde792 @dsyer Some housekeeping:
dsyer authored
155 one of `hsqldb` or `postgresql`. The opposite is `!jdbc` which needs
156 to be specified explicitly if any other profiles are active. The
157 `hsqldb` profile will start up with an in-memory RDBMS by default.
650b10c @dsyer Initial draft - uaa with hard-coded user database
dsyer authored
158
8c2d455 @tekul Added spring profile usage info to readme
tekul authored
159 The active profiles can be configured by passing the
160 `spring.profiles.active` parameter to the JVM. For, example to run
161 with an embedded HSQL database:
162
ff268de @dsyer CFID-96: remove private profile and initialise empty database with ad…
dsyer authored
163 mvn -Dspring.profiles.active=jdbc,hsqldb,!legacy tomcat:run
8c2d455 @tekul Added spring profile usage info to readme
tekul authored
164
165 Or to use PostgreSQL instead of HSQL:
166
ff268de @dsyer CFID-96: remove private profile and initialise empty database with ad…
dsyer authored
167 mvn -Dspring.profiles.active=jdbc,postgresql,!legacy tomcat:run
7a309ad @dsyer Add tests and README for \!private profile
dsyer authored
168
ff268de @dsyer CFID-96: remove private profile and initialise empty database with ad…
dsyer authored
169 To bootstrap a microcloud type environment you need an admin user.
170 For this there is a database initializer component that inserts an
171 admin user if it finds an empty database on startup. Override the
172 default settings (username/password=admin/admin) in `uaa.yml`:
173
174 bootstrap:
175 admin:
176 username: foo
177 password: $2a$10$yHj...
178 email: admin@test.com
179 family_name: Piper
180 given_name: Peter
181
182 (the password has to be bcrypted).
183
184 ### Legacy Mode
185
186 There is a legacy mode where the CF.com cloud controller is used for
187 the authentication and token generation. To use this, launch the app
188 with Spring profile `legacy` (a Maven profile with the same name is
189 provided for convenience as well). The opposite is `!legacy` which
190 needs to be specified explicitly if any other profiles are active.
191 The cloud controller login URL defaults to
192 `http://api.cloudfoundry.com/users/{username}/tokens` - to override it
193 provide a System property or `uaa.yml` entry for
194 `cloud.controller.login_url`.
8c2d455 @tekul Added spring profile usage info to readme
tekul authored
195
3c3c502 @tekul Update README and scripts to illustrate the implicit flow login/token…
tekul authored
196 ## The API Application
650b10c @dsyer Initial draft - uaa with hard-coded user database
dsyer authored
197
3c3c502 @tekul Update README and scripts to illustrate the implicit flow login/token…
tekul authored
198 An example resource server. It hosts a service which returns
199 a list of mock applications under `/apps`.
650b10c @dsyer Initial draft - uaa with hard-coded user database
dsyer authored
200
00cf04c @dsyer Simplify integration test incantation
dsyer authored
201 Run it using `mvn tomcat:run` from the `api` directory (once all other
202 tomcat processes have been shutdown). This will deploy the app to a
203 Tomcat manager on port 8080.
650b10c @dsyer Initial draft - uaa with hard-coded user database
dsyer authored
204
205 ## The App Application
206
39b9174 @tekul Minor edit to README.md (review test)
tekul authored
207 This is a user interface app (primarily aimed at browsers) that uses
e578bc0 @dsyer CFID-36: tidy up and add some docs
dsyer authored
208 OpenId Connect for authentication (i.e. SSO) and OAuth2 for access
209 grants. It authenticates with the Auth service, and then accesses
00cf04c @dsyer Simplify integration test incantation
dsyer authored
210 resources in the API service. Run it with `mvn tomcat:run` from the
211 `app` directory (once all other tomcat processes have been shutdown).
650b10c @dsyer Initial draft - uaa with hard-coded user database
dsyer authored
212
213 ### Use Cases
214
ab32020 @dsyer Update README
dsyer authored
215 1. See all apps
650b10c @dsyer Initial draft - uaa with hard-coded user database
dsyer authored
216
39b9174 @tekul Minor edit to README.md (review test)
tekul authored
217 GET /app/apps
650b10c @dsyer Initial draft - uaa with hard-coded user database
dsyer authored
218
219 browser is redirected through a series of authentication and access
220 grant steps (which could be slimmed down to implicit steps not
221 requiring user at some point), and then the photos are shown.
222
ab32020 @dsyer Update README
dsyer authored
223 2. See the currently logged in user details, a bag of attributes
650b10c @dsyer Initial draft - uaa with hard-coded user database
dsyer authored
224 grabbed from the open id provider
225
ab32020 @dsyer Update README
dsyer authored
226 GET /app
Something went wrong with that request. Please try again.