Skip to content

HTTPS clone URL

Subversion checkout URL

You can clone with
or
.
Download ZIP
Newer
Older
100644 201 lines (150 sloc) 6.996 kB
19ea06b @dsyer [cfid-118] document autologin api
dsyer authored
1 - [Login Server APIs](#login-server-apis)
2 - [Overview](#overview)
3 - [Login Form: ``GET /login``](#login-form-get-login)
4 - [Form Login: `POST /login.do`](#form-login-post-logindo)
5 - [Logout: `GET /logout.do`](#logout-get-logoutdo)
6 - [OAuth2 Endpoints](#oauth2-endpoints)
7 - [Start Authorization: `GET /oauth/authorize`](#start-authorization-get-oauthauthorize)
8 - [Obtain Authorization Code: `POST /oauth/authorize`](#obtain-authorization-code-post-oauthauthorize)
9 - [Token Endpoint: `POST /oauth/token`](#token-endpoint-post-oauthtoken)
10 - [Login Info: `GET /login`](#login-info-get-login)
11 - [Healthz: `GET /healthz`](#healthz-get-healthz)
12 - [Varz: `GET /varz`](#varz-get-varz)
13 - [Autologin](#autologin)
14 - [Obtain Autologin Code: `POST /autologin`](#obtain-autologin-code-post-autologin)
15
16 # Login Server APIs
17
18 ## Overview
19
20 The Login Server:
21
1627d14 @bmidgley doc typo fixes
bmidgley authored
22 * is separate from the UAA but needs to be connected to one via HTTP(S)
19ea06b @dsyer [cfid-118] document autologin api
dsyer authored
23 * provides SSO for web applications in the Cloud Foundry platform
24 * manages and provides a branded HTML UI for authentication and OAuth
25 approval
26 * provides some other features via JSON APIs
27
28 ## Login Form: ``GET /login``
29
30 Request: `GET /login?error={error}`
31 Response Body: form with all the relevant prompts
32 Response Codes: `200 - Success`
33
34 ## Form Login: `POST /login.do`
35
36 Browser POSTs to `/login.do` with user credentials (same as UAA).
37 Login Server returns a cookie that can be used to authenticate future
1627d14 @bmidgley doc typo fixes
bmidgley authored
38 requests (until the session expires or the user logs out).
19ea06b @dsyer [cfid-118] document autologin api
dsyer authored
39
40 ## Logout: `GET /logout.do`
41
42 The Login Server is a Single Sign On server for the Cloud Foundry
43 platform (and possibly user apps as well), so if a user logs out he
1627d14 @bmidgley doc typo fixes
bmidgley authored
44 logs out of all the apps. Users need to be reminded of the
19ea06b @dsyer [cfid-118] document autologin api
dsyer authored
45 consequences of their actions, so the recommendation for application
46 authors is to
47
48 * provide a local logout feature specific to the client application
49 and use that to clear state in the client
50 * on the success page for that logout provide a link to the Login
51 Server logout endpoint with a message telling the user what will
52 happen if he clicks it
53 * provide a redirect in the link to the logout endpoint (see below) so
54 that the user come back to a familiar place when logged out,
55 otherwise he will just get the logged out success page from the
56 Login Server
57
58 Request: `GET /logout.do?redirect=http://myclient/loggedout`
59 Request Headers: `Cookie: JSESSIONID=8765FDUAYSFT7897`
60 Response Codes:
61
62 200 - OK (if no redirect supplied)
63 302 - FOUND (if redirect supplied)
64
65 ## OAuth2 Endpoints
66
67 The standard authorize and token endpoints are available on the Login
68 Server. They are passed through the request to the UAA, getting JSON
69 responses from the UAA and re-rendering them if the user requested
70 HTML.
71
72 ### Start Authorization: `GET /oauth/authorize`
73
74 Client applications usually send a redirect to User's browser with the
1627d14 @bmidgley doc typo fixes
bmidgley authored
75 request URI appropriate to the Client. Exactly the same as the UAA,
19ea06b @dsyer [cfid-118] document autologin api
dsyer authored
76 but the response is rendered differently.
77
78 Request: example
79
80 GET /oauth/authorize?response_type=code&
81 redirect_uri=https://myclient/callback&
82 client_id=myclient&
83 state=RANDOM
84
85 The request must be authenticated as a user, so usually a session
86 cookie (`JSESSIONID`) is required, having been obtained previously
87 through the Login page.
88
89 ### Obtain Authorization Code: `POST /oauth/authorize`
90
91 Exactly the same as the UAA. When user approves the browser sends
92 `user_oauth_approval=true` (or false) and the Login Server sends back
93 an authorization code (if one was previously requested).
94
95 ### Token Endpoint: `POST /oauth/token`
96
97 Obtain an access token, typically either with an authorization code or
98 client credentials. Exactly the same as the UAA.
99
100 ## Login Info: `GET /login`
101
102 Reports basic information about the build (version and git commit id)
103 and also passes through the information about prompts from the UAA.
104 Unauthenticated.
105
106 ## Healthz: `GET /healthz`
107
108 Returns "ok" in the response body if the server is up and running
109
110 ## Varz: `GET /varz`
111
112 Reports basic management information about the Login Server and the
113 JVM it runs in (memory usage etc.). Secured with HTTP Basic
114 authentication using credentials that are advertised on NATS in Cloud
115 Foundry (for a standalone instance the default is
116 `varz:varzclientsecret`).
117
118 Request: `GET /varz`
119 Response Body:
120
121 {
122 "type": "Login",
123 "links": {
124 "JMImplementation": "http://localhost:8080/uaa/varz/JMImplementation",
125 "spring.application": "http://localhost:8080/uaa/varz/spring.application",
126 "com.sun.management": "http://localhost:8080/uaa/varz/com.sun.management",
127 "Catalina": "http://localhost:8080/uaa/varz/Catalina",
128 "env": "http://localhost:8080/uaa/varz/env",
129 "java.lang": "http://localhost:8080/uaa/varz/java.lang",
130 "java.util.logging": "http://localhost:8080/uaa/varz/java.util.logging"
131 },
132 "mem": 19173496,
133 "memory": {
134 "verbose": false,
135 "non_heap_memory_usage": {
136 "max": 184549376,
137 "committed": 30834688,
138 "init": 19136512,
139 "used": 30577744
140 },
141 "object_pending_finalization_count": 0,
142 "heap_memory_usage": {
143 "max": 902299648,
144 "committed": 84475904,
145 "init": 63338496,
146 "used": 19173496
147 }
148 },
149 "spring.profiles.active": []
150 }
151
152 ## Autologin
153
154 For user-facing account management UIs (e.g. portal) that need to set
1627d14 @bmidgley doc typo fixes
bmidgley authored
155 or reset users' passwords it is convenient to be able to log them in
19ea06b @dsyer [cfid-118] document autologin api
dsyer authored
156 immediately, rather than waiting for them to come back to the Login
157 Server and enter the new password explicitly.
158
1627d14 @bmidgley doc typo fixes
bmidgley authored
159 1. Client POSTs user credentials to `/autologin`
19ea06b @dsyer [cfid-118] document autologin api
dsyer authored
160
161 2. Login Server responds with autologin code (short-lived, one-time)
162
163 3. Client builds redirect URI to Login Server `/authorize` endpoint
164 (normal OAuth2 auth code flow) appending the code
165
166 4. Client sends redirect to User
167
168 5. User's browser initiates auth code flow
169
170 6. Login Server redeems autologin code and exchanges it for an
171 authenticated user (as if the user had authenticated with the Login
172 Server manually)
173
174 7. User's browser now has SSO cookie for Login Server, and remains
175 logged in for the duration of that session.
176
177 ### Obtain Autologin Code: `POST /autologin`
178
179 Gets a short-lived code that can be exchanged for an authentication at
5a70a2c @dsyer [cfid-165] Fix confg and docs to clarify /autologin
dsyer authored
180 the Login Server `/oauth/authorize` UI. The client authenticates
181 itself with its secret using an HTTP Basic header.
19ea06b @dsyer [cfid-118] document autologin api
dsyer authored
182
183 Request: `POST /autologin`
184 Request Body: Form encoded user credentials
185
186 username=<username>&password=<password>
187
188 Request Headers:
189
5a70a2c @dsyer [cfid-165] Fix confg and docs to clarify /autologin
dsyer authored
190 Authorization: Basic <...>
19ea06b @dsyer [cfid-118] document autologin api
dsyer authored
191
192 Response Body:
193
194 { "code"="aiuynklj", "path"="/oauth/authorize" }
195
196 By default the password is required and is checked using the
197 `login.do` endpoint at the UAA, but could be made optional or changed
198 to other authentication credentials with a configuration change in the
199 Login Server (by adding a different `AuthenticationManager` to the
200 `AutologinController`).
Something went wrong with that request. Please try again.