Skip to content

HTTPS clone URL

Subversion checkout URL

You can clone with
or
.
Download ZIP
Newer
Older
100644 189 lines (126 sloc) 6.753 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
126 ### User Account Data
127
128 The default is to use an in-memory, hash-based user store that is
129 pre-populated with some test users: e.g. `dale` has password
130 `password` and `marissa` has password `koala`.
131
132 To use a RDBMS for user data activate the Spring profiles `jdbc` and
133 one of `hsqldb` or `postgresql`. The `hsqldb` profile will start up
134 with an in-memory RDBMS by default. Warning: the database will start
135 empty, so no users can log in until the first account is created.
650b10c @dsyer Initial draft - uaa with hard-coded user database
dsyer authored
136
8c2d455 @tekul Added spring profile usage info to readme
tekul authored
137 The active profiles can be configured by passing the
138 `spring.profiles.active` parameter to the JVM. For, example to run
139 with an embedded HSQL database:
140
141 mvn -Dspring.profiles.active=default,jdbc tomcat:run
142
143 Or to use PostgreSQL instead of HSQL:
144
145 mvn -Dspring.profiles.active=default,jdbc,postgresql tomcat:run
7a309ad @dsyer Add tests and README for \!private profile
dsyer authored
146
147 To launch in a microcloud type environment you need the SCIM user
148 endpoints to be unsecure so that a user can create an account and set
149 its password to bootstrap the system. For this use the Spring profile
150 `private`. The opposite is `!private` which needs to be specified
3313107 @dsyer CFID-80: add Legacy* components for authentication with CF.com
dsyer authored
151 explicitly if the any other profiles are active.
152
153 To launch in legacy mode with the CF.com cloud controller as the
154 authentication and token source use profile `legacy`. The opposite is
155 `!legacy` which needs to be specified explicitly if the any other
156 profiles are active.
8c2d455 @tekul Added spring profile usage info to readme
tekul authored
157
3c3c502 @tekul Update README and scripts to illustrate the implicit flow login/token…
tekul authored
158 ## The API Application
650b10c @dsyer Initial draft - uaa with hard-coded user database
dsyer authored
159
3c3c502 @tekul Update README and scripts to illustrate the implicit flow login/token…
tekul authored
160 An example resource server. It hosts a service which returns
161 a list of mock applications under `/apps`.
650b10c @dsyer Initial draft - uaa with hard-coded user database
dsyer authored
162
00cf04c @dsyer Simplify integration test incantation
dsyer authored
163 Run it using `mvn tomcat:run` from the `api` directory (once all other
164 tomcat processes have been shutdown). This will deploy the app to a
165 Tomcat manager on port 8080.
650b10c @dsyer Initial draft - uaa with hard-coded user database
dsyer authored
166
167 ## The App Application
168
39b9174 @tekul Minor edit to README.md (review test)
tekul authored
169 This is a user interface app (primarily aimed at browsers) that uses
e578bc0 @dsyer CFID-36: tidy up and add some docs
dsyer authored
170 OpenId Connect for authentication (i.e. SSO) and OAuth2 for access
171 grants. It authenticates with the Auth service, and then accesses
00cf04c @dsyer Simplify integration test incantation
dsyer authored
172 resources in the API service. Run it with `mvn tomcat:run` from the
173 `app` directory (once all other tomcat processes have been shutdown).
650b10c @dsyer Initial draft - uaa with hard-coded user database
dsyer authored
174
175 ### Use Cases
176
ab32020 @dsyer Update README
dsyer authored
177 1. See all apps
650b10c @dsyer Initial draft - uaa with hard-coded user database
dsyer authored
178
39b9174 @tekul Minor edit to README.md (review test)
tekul authored
179 GET /app/apps
650b10c @dsyer Initial draft - uaa with hard-coded user database
dsyer authored
180
181 browser is redirected through a series of authentication and access
182 grant steps (which could be slimmed down to implicit steps not
183 requiring user at some point), and then the photos are shown.
184
ab32020 @dsyer Update README
dsyer authored
185 2. See the currently logged in user details, a bag of attributes
650b10c @dsyer Initial draft - uaa with hard-coded user database
dsyer authored
186 grabbed from the open id provider
187
ab32020 @dsyer Update README
dsyer authored
188 GET /app
Something went wrong with that request. Please try again.