Skip to content

HTTPS clone URL

Subversion checkout URL

You can clone with
or
.
Download ZIP
Newer
Older
100644 166 lines (107 sloc) 5.71 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
650b10c @dsyer Initial draft - uaa with hard-coded user database
dsyer authored
4 ## Quick Start
ace5777 @daleolds start of UAA
daleolds authored
5
ab32020 @dsyer Update README
dsyer authored
6 If this works you are in business:
ace5777 @daleolds start of UAA
daleolds authored
7
600eda2 @ciberch Update README.md
ciberch authored
8 $ git clone git@github.com:vmware-ac/uaa.git
ab32020 @dsyer Update README
dsyer authored
9 $ cd uaa
10 $ mvn install
39b9174 @tekul Minor edit to README.md (review test)
tekul authored
11
00cf04c @dsyer Simplify integration test incantation
dsyer authored
12 Each module has a `mvn tomcat:run` target to run individually, or you
13 could import them as projects into STS (use 2.8.0 or better if you
14 can). The apps all work together the apps running on the same port
15 (8080) as `/uaa`, `/app` and `/api`.
650b10c @dsyer Initial draft - uaa with hard-coded user database
dsyer authored
16
3c3c502 @tekul Update README and scripts to illustrate the implicit flow login/token…
tekul authored
17 ### Demo of command line usage
650b10c @dsyer Initial draft - uaa with hard-coded user database
dsyer authored
18
3c3c502 @tekul Update README and scripts to illustrate the implicit flow login/token…
tekul authored
19 First run the uaa server as described above:
650b10c @dsyer Initial draft - uaa with hard-coded user database
dsyer authored
20
3c3c502 @tekul Update README and scripts to illustrate the implicit flow login/token…
tekul authored
21 $ cd uaa
00cf04c @dsyer Simplify integration test incantation
dsyer authored
22 $ mvn tomcat:run
650b10c @dsyer Initial draft - uaa with hard-coded user database
dsyer authored
23
3c3c502 @tekul Update README and scripts to illustrate the implicit flow login/token…
tekul authored
24 Then start another terminal and from the project base directory, run:
650b10c @dsyer Initial draft - uaa with hard-coded user database
dsyer authored
25
2c2d2c2 @dsyer Update README for new ports
dsyer authored
26 $ ./login.sh "localhost:8080/uaa"
650b10c @dsyer Initial draft - uaa with hard-coded user database
dsyer authored
27
3c3c502 @tekul Update README and scripts to illustrate the implicit flow login/token…
tekul authored
28 And hit return twice to accept the default username and password.
650b10c @dsyer Initial draft - uaa with hard-coded user database
dsyer authored
29
3c3c502 @tekul Update README and scripts to illustrate the implicit flow login/token…
tekul authored
30 This authenticates and obtains an access token from the server using the OAuth2 implicit
31 grant, similar to the approach intended for a client like VMC. The token is
32 stored in the file `.access_token`.
650b10c @dsyer Initial draft - uaa with hard-coded user database
dsyer authored
33
00cf04c @dsyer Simplify integration test incantation
dsyer authored
34 Now kill the `uaa` server and run the `api` server (which starts the
35 `uaa` server as well):
39b9174 @tekul Minor edit to README.md (review test)
tekul authored
36
60e128a @dsyer Add postgres support and and check with PLATFORM=postgresql
dsyer authored
37 $ cd samples/api
00cf04c @dsyer Simplify integration test incantation
dsyer authored
38 $ mvn tomcat:run
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 then (from the base directory) execute:
650b10c @dsyer Initial draft - uaa with hard-coded user database
dsyer authored
41
f274eb9 @dsyer Update README for Tomcat
dsyer authored
42 $ ./get.sh http://localhost:8080/api/apps
650b10c @dsyer Initial draft - uaa with hard-coded user database
dsyer authored
43
3c3c502 @tekul Update README and scripts to illustrate the implicit flow login/token…
tekul authored
44 which should return a JSON array of (pretend) running applications.
650b10c @dsyer Initial draft - uaa with hard-coded user database
dsyer authored
45
6bab6c9 @dsyer Put tomcat in a profile (tomcat)
dsyer authored
46 ## Integration tests
47
48 With all apps deployed into a running server on port 8080 the tests
49 will include integration tests (a check is done before each test that
50 the app is running). You can deploy them in your IDE or using the
00cf04c @dsyer Simplify integration test incantation
dsyer authored
51 command line with `mvn tomcat:run`.
6bab6c9 @dsyer Put tomcat in a profile (tomcat)
dsyer authored
52
00cf04c @dsyer Simplify integration test incantation
dsyer authored
53 For individual modules, or for the whole project, you can also run
54 integration tests from the command line in one go with
6bab6c9 @dsyer Put tomcat in a profile (tomcat)
dsyer authored
55
00cf04c @dsyer Simplify integration test incantation
dsyer authored
56 $ mvn integration-test
6bab6c9 @dsyer Put tomcat in a profile (tomcat)
dsyer authored
57
28afa21 @dsyer Remove or tidy jsps and update README
dsyer authored
58 (This might require an initial `mvn install` from the parent directory
59 to get the wars in your local repo first.)
60
3c3c502 @tekul Update README and scripts to illustrate the implicit flow login/token…
tekul authored
61 ## Inventory
650b10c @dsyer Initial draft - uaa with hard-coded user database
dsyer authored
62
60e128a @dsyer Add postgres support and and check with PLATFORM=postgresql
dsyer authored
63 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
64
3c3c502 @tekul Update README and scripts to illustrate the implicit flow login/token…
tekul authored
65 1. `uaa` is the actual UAA server
650b10c @dsyer Initial draft - uaa with hard-coded user database
dsyer authored
66
60e128a @dsyer Add postgres support and and check with PLATFORM=postgresql
dsyer authored
67 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
68
60e128a @dsyer Add postgres support and and check with PLATFORM=postgresql
dsyer authored
69 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
70
3c3c502 @tekul Update README and scripts to illustrate the implicit flow login/token…
tekul authored
71 In CloudFoundry terms
650b10c @dsyer Initial draft - uaa with hard-coded user database
dsyer authored
72
3c3c502 @tekul Update README and scripts to illustrate the implicit flow login/token…
tekul authored
73 * `uaa` provides an authentication service plus authorized delegation for
74 back-end services and apps (by issuing OAuth2 access tokens).
650b10c @dsyer Initial draft - uaa with hard-coded user database
dsyer authored
75
3c3c502 @tekul Update README and scripts to illustrate the implicit flow login/token…
tekul authored
76 * `api` is `api.cloudfoundry.com` - it's a service which provides resources
77 which other applications may wish to access on behalf of the resource
78 owner (the end user).
650b10c @dsyer Initial draft - uaa with hard-coded user database
dsyer authored
79
3c3c502 @tekul Update README and scripts to illustrate the implicit flow login/token…
tekul authored
80 * `app` is `code.cloudfoundry.com` or `studio.cloudfoundry.com` - a
81 webapp that needs single sign on and access to the `api` service on
82 behalf of users.
650b10c @dsyer Initial draft - uaa with hard-coded user database
dsyer authored
83
92647e4 @dsyer Upgrade to Spring 3.1
dsyer authored
84 ## UAA Server
85
3c3c502 @tekul Update README and scripts to illustrate the implicit flow login/token…
tekul authored
86 The authentication service is `uaa`. It's a plain Spring MVC webapp.
87 Deploy as normal in Tomcat or your container of choice, or execute
f274eb9 @dsyer Update README for Tomcat
dsyer authored
88 `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
89 When running with maven it listen on port 8080.
650b10c @dsyer Initial draft - uaa with hard-coded user database
dsyer authored
90
3c3c502 @tekul Update README and scripts to illustrate the implicit flow login/token…
tekul authored
91 It supports the APIs defined in the UAA-APIs document. To summarise:
650b10c @dsyer Initial draft - uaa with hard-coded user database
dsyer authored
92
3c3c502 @tekul Update README and scripts to illustrate the implicit flow login/token…
tekul authored
93 1. The OAuth2 /authorize and /token endpoints
650b10c @dsyer Initial draft - uaa with hard-coded user database
dsyer authored
94
3c3c502 @tekul Update README and scripts to illustrate the implicit flow login/token…
tekul authored
95 2. A /login_info endpoint to allow querying for required login prompts
650b10c @dsyer Initial draft - uaa with hard-coded user database
dsyer authored
96
3c3c502 @tekul Update README and scripts to illustrate the implicit flow login/token…
tekul authored
97 3. A /check_token endpoint, to allow resource servers to obtain information about
98 an access token submitted by an OAuth2 client.
650b10c @dsyer Initial draft - uaa with hard-coded user database
dsyer authored
99
92647e4 @dsyer Upgrade to Spring 3.1
dsyer authored
100 4. SCIM user provisioning endpoint
650b10c @dsyer Initial draft - uaa with hard-coded user database
dsyer authored
101
92647e4 @dsyer Upgrade to Spring 3.1
dsyer authored
102 5. OpenID connect endpoints to support authentication /userinfo and
103 /check_id (todo). Implemented roughly enough to get it working (so
104 /app authenticates here), but not to meet the spec.
e578bc0 @dsyer CFID-36: tidy up and add some docs
dsyer authored
105
106 Authentication can be performed by command line clients by submitting
60e128a @dsyer Add postgres support and and check with PLATFORM=postgresql
dsyer authored
107 credentials directly to the `/authorize` endpoint (as described in
e578bc0 @dsyer CFID-36: tidy up and add some docs
dsyer authored
108 UAA-API doc). There is an `ImplicitAccessTokenProvider` in Spring
92647e4 @dsyer Upgrade to Spring 3.1
dsyer authored
109 Security OAuth that can do the heavy lifting if your client is Java.
110
111 By default `uaa` will launch with a context root `/uaa`. There is a
112 Maven profile `vcap` to launch with context root `/`.
113
114 ### User Account Data
115
116 The default is to use an in-memory, hash-based user store that is
117 pre-populated with some test users: e.g. `dale` has password
118 `password` and `marissa` has password `koala`.
119
120 To use a RDBMS for user data activate the Spring profiles `jdbc` and
121 one of `hsqldb` or `postgresql`. The `hsqldb` profile will start up
122 with an in-memory RDBMS by default. Warning: the database will start
123 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
124
8c2d455 @tekul Added spring profile usage info to readme
tekul authored
125 The active profiles can be configured by passing the
126 `spring.profiles.active` parameter to the JVM. For, example to run
127 with an embedded HSQL database:
128
129 mvn -Dspring.profiles.active=default,jdbc tomcat:run
130
131 Or to use PostgreSQL instead of HSQL:
132
133 mvn -Dspring.profiles.active=default,jdbc,postgresql tomcat:run
134
3c3c502 @tekul Update README and scripts to illustrate the implicit flow login/token…
tekul authored
135 ## The API Application
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 An example resource server. It hosts a service which returns
138 a list of mock applications under `/apps`.
650b10c @dsyer Initial draft - uaa with hard-coded user database
dsyer authored
139
00cf04c @dsyer Simplify integration test incantation
dsyer authored
140 Run it using `mvn tomcat:run` from the `api` directory (once all other
141 tomcat processes have been shutdown). This will deploy the app to a
142 Tomcat manager on port 8080.
650b10c @dsyer Initial draft - uaa with hard-coded user database
dsyer authored
143
144 ## The App Application
145
39b9174 @tekul Minor edit to README.md (review test)
tekul authored
146 This is a user interface app (primarily aimed at browsers) that uses
e578bc0 @dsyer CFID-36: tidy up and add some docs
dsyer authored
147 OpenId Connect for authentication (i.e. SSO) and OAuth2 for access
148 grants. It authenticates with the Auth service, and then accesses
00cf04c @dsyer Simplify integration test incantation
dsyer authored
149 resources in the API service. Run it with `mvn tomcat:run` from the
150 `app` directory (once all other tomcat processes have been shutdown).
650b10c @dsyer Initial draft - uaa with hard-coded user database
dsyer authored
151
152 ### Use Cases
153
ab32020 @dsyer Update README
dsyer authored
154 1. See all apps
650b10c @dsyer Initial draft - uaa with hard-coded user database
dsyer authored
155
39b9174 @tekul Minor edit to README.md (review test)
tekul authored
156 GET /app/apps
650b10c @dsyer Initial draft - uaa with hard-coded user database
dsyer authored
157
158 browser is redirected through a series of authentication and access
159 grant steps (which could be slimmed down to implicit steps not
160 requiring user at some point), and then the photos are shown.
161
ab32020 @dsyer Update README
dsyer authored
162 2. See the currently logged in user details, a bag of attributes
650b10c @dsyer Initial draft - uaa with hard-coded user database
dsyer authored
163 grabbed from the open id provider
164
ab32020 @dsyer Update README
dsyer authored
165 GET /app
Something went wrong with that request. Please try again.