-
Notifications
You must be signed in to change notification settings - Fork 3
/
oauth.html
550 lines (454 loc) · 37.5 KB
/
oauth.html
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
211
212
213
214
215
216
217
218
219
220
221
222
223
224
225
226
227
228
229
230
231
232
233
234
235
236
237
238
239
240
241
242
243
244
245
246
247
248
249
250
251
252
253
254
255
256
257
258
259
260
261
262
263
264
265
266
267
268
269
270
271
272
273
274
275
276
277
278
279
280
281
282
283
284
285
286
287
288
289
290
291
292
293
294
295
296
297
298
299
300
301
302
303
304
305
306
307
308
309
310
311
312
313
314
315
316
317
318
319
320
321
322
323
324
325
326
327
328
329
330
331
332
333
334
335
336
337
338
339
340
341
342
343
344
345
346
347
348
349
350
351
352
353
354
355
356
357
358
359
360
361
362
363
364
365
366
367
368
369
370
371
372
373
374
375
376
377
378
379
380
381
382
383
384
385
386
387
388
389
390
391
392
393
394
395
396
397
398
399
400
401
402
403
404
405
406
407
408
409
410
411
412
413
414
415
416
417
418
419
420
421
422
423
424
425
426
427
428
429
430
431
432
433
434
435
436
437
438
439
440
441
442
443
444
445
446
447
448
449
450
451
452
453
454
455
456
457
458
459
460
461
462
463
464
465
466
467
468
469
470
471
472
473
474
475
476
477
478
479
480
481
482
483
484
485
486
487
488
489
490
491
492
493
494
495
496
497
498
499
500
501
502
503
504
505
506
507
508
509
510
511
512
513
514
515
516
517
518
519
520
521
522
523
524
525
526
527
528
529
530
531
532
533
534
535
536
537
538
539
540
541
542
543
544
545
546
547
548
549
550
<!DOCTYPE html>
<html lang="en">
<head>
<meta charset="utf-8">
<meta http-equiv="X-UA-Compatible" content="IE=edge">
<meta name="viewport" content="width=device-width, shrink-to-fit=no, initial-scale=1">
<meta name="description" content="Circuit Developer Community - Authorization Examples">
<meta name="author" content="Roger Urscheler">
<link rel="shortcut icon" type="image/png" href="images/oauth-logo.jpeg"/>
<title>Circuit API Authorization Examples</title>
<link href="css/bootstrap.min.css" rel="stylesheet">
<link href="css/style.css" rel="stylesheet">
<script>
if (window.location.host == 'circuit.github.io' && window.location.protocol != 'https:') {
window.location.protocol = 'https:';
}
</script>
</head>
<body>
<div id="wrapper">
<!-- Sidebar -->
<div id="sidebar-wrapper"></div>
<!-- Page Content -->
<div id="page-content-wrapper">
<div class="container-fluid">
<div class="row">
<div class="col-lg-12">
<h1>OAuth 2.0</h1>
<p>Circuit uses OAuth 2.0 for authentication and authorization and supports most common OAuth 2.0 scenarios such as Bots, server and client-side Web Apps. Mobile client SDKs are in the works, but in the meantime can use the REST API with an open source OAuth library.</p>
<p>This page is intended to provide an overview of the different OAuth types and help you in choosing the right type for your app. A complete Developer Portal with tutorials, examples and documentation is coming soon.</p>
<p>
<div><a href="#authorization_code">Authorization Code Grant</a></div>
<div><a href="#implicit">Implicit Grant</a></div>
<div><a href="#client_credentials">Client Credentials Grant</a></div>
<!--<div><a href="#resource_owner">Resource Owner Password Credentials Grant</a></div>-->
<div><a href="#refresh_token">Refresh Token Flow</a></div>
<div><a href="#renew_token">Renew a Token</a></div>
<div><a href="#revoke_token">Revoke a Token</a></div>
</p>
<div class="bs-callout bs-callout-primary">
<p>The <code>client_id</code> and <code>client_secret</code> in the examples shown on this page are invalid. You need to request your own app to get a client_id and optionally client_secret for your domain.</p>
</div>
<h3>Which OAuth 2.0 grant type do I need?</h3>
<p>Are you building a:</p>
<ul>
<li><b>Bot</b>, then you require a <a href="#client_credentials">Client Credentials</a> OAuth app</li>
<li><b>Client-side JavaScript Web App</b>, then you require an <a href="#implicit">Implicit</a> OAuth app</li>
<li><b>Server-side Web App</b>, then you require an <a href="#authorization_code">Authorization Code</a> OAuth app</li>
</ul>
<p>Read the descriptions in the <a href="#grant_types">OAuth 2.0 Grant Types</a> section for more information on the 3 different grant types supported by Circuit.</p>
<h3 id="registration">OAuth 2.0 App Registration</h3>
<p>Tenant admninistrator can now create OAuth apps on the Circuit webclient. See <a href="/index.html">Getting Started</a> page for details.</p>
</div>
</div>
<div class="row" id="grant_types">
<h2>OAuth 2.0 Grant Types</h2>
</div>
<div class="row" id="authorization_code">
<h3>Authorization Code Grant</h3>
<p>The authorization code grant type is optimized for server-side applications, where source code is not publicly exposed, and Client Secret confidentiality can be maintained. This is a redirection-based flow, which means that the application must be capable of interacting with the user's web browser to open the Circuit OAuth authorization page.</p>
<p>Rather than implementing the OAuth flow manually as shown in this example, it is recommended to use an OAuth library. There are many open source libraries available on github and npm such as <a href="https://www.npmjs.com/package/oauth" target="_blank">oauth</a>, <a href="https://www.npmjs.com/package/simple-oauth2" target="_blank">simple-oauth2</a> or <a href="https://www.npmjs.com/package/passport-oauth2" target="_blank">passport-oauth2</a>.</p>
<p>For more details on Authorization Code Grant refer to <a href="https://tools.ietf.org/html/rfc6749#section-4.1" target="_blank">rfc6749 section 4.1</a>.</p>
<h4>Authorization Code Flow</h4>
<p>Once your app is registered you are provided with a <code>client_id</code> and <code>client_secret</code>. The client_id identifies your app. The client_secret is like a password, so keep it confidential. Using these credentials your app can get an OAuth access token on behalf of a user, as long as the user grants your app access.</p>
<h5>Step 1: Application Requests Authorization Code</h5>
<p>On page load, or on a user action (e.g. login button) your app needs to redirect the browser to Circuit's <code>/oauth/authorize</code> endpoint. Rather than a redirect, apps usually open a new window instead as seen in the images of Step 2.</p>
<p>The request requires the following parameters:</p>
<table class="table table-condensed">
<thead>
<tr>
<th>Parameter</th>
<th>Value</th>
<th>Description</th>
</tr>
</thead>
<tbody>
<tr>
<td><code>response_type</code></td>
<td><code>code</code></td>
<td>Causes the Circuit endpoint to return an authorization code. Web server apps should use <b>code</b>.</td>
</tr>
<tr>
<td><code>client_id</code></td>
<td>The client_id obtained when requesting the OAuth app.</td>
<td>Identifies the client that is making the request. The value passed in this parameter must exactly match the client_id obtained.</td>
</tr>
<tr>
<td><code>redirect_uri</code></td>
<td>Url to be redirected after access is granted by user.</td>
<td>Complete Url including protocol and port if applicable. Host (protocol, domain and port) must match one of the domains of requested OAuth app. E.g. https://my-cool-app.com/oauthcallback in which case https://my-cool-app.com had to be requested on app creation.</td>
</tr>
<tr>
<td><code>scope</code></td>
<td>Comma-delimited set of permissions that the application requests.</td>
<td>The values passed in this parameter are listed on the consent screen that is shown to the user. Supported scopes are: <code>ALL, READ_USER_PROFILE, WRITE_USER_PROFILE, READ_CONVERSATIONS, WRITE_CONVERSATIONS, READ_USER, CALLS</code></td>
</tr>
<tr>
<td><code>state</code></td>
<td>Any string</td>
<td>Provides any state that might be useful to your application upon receipt of the response. The Circuit Server roundtrips this parameter, so your application receives the same value it sent. To mitigate against cross-site request forgery (CSRF), it is strongly recommended to include an anti-forgery token in the state, and confirm it in the response. This parameter is not required but strongly recommended for above mentioned security reasons.</td>
</tr>
<tr>
<td><code>login_hint</code></td>
<td>email</td>
<td>Optional. If your application knows which user is trying to authenticate, it can use this parameter to provide a hint to the Circuit Authentication Server. The server uses the hint to simplify the login flow by prefilling the email field in the sign-in form.</td>
</tr>
<tr>
<td><code>prompt</code></td>
<td>comma delimited string</td>
<td>Optional. A comma-delimited (no spaces), case-sensitive list of options for the oauth window.
<ul>
<li><code>disable_email</code>: Disable email field (only applicable if login_hint is provided)</li>
<li><code>disable_switch</code>: Disable ability to switch the account from to Oauth popup</li>
<li><code>disable_caching</code>: Hide the "private computer" checkbox.</li>
</ul>
</td>
</tr>
</tbody>
</table>
<h6>Example request:</h6>
<pre><code>https://circuitsandbox.net/oauth/authorize?response_type=code&client_id=aee562d3d6a947efa04438a996f34c80&redirect_uri=https%3A%2F%my-cool-app.com%oauthcallback&scope=READ_USER_PROFILE,READ_CONVERSATIONS&state=fa04438a996f</code></pre>
<h5>Step 2: User grants access</h5>
<p>The browser will now show the OAuth permission/consent page (with prior login if not already logged in). This page is asking the user to give your app permissions to act on the user's behalf. The app name and author are shown on that page to identify the app, as well as the requested permissions.</p>
<div class="oauth-image" style="display: flex;flex-flow: row nowrap;">
<img class="img-responsive" src="/images/login-page.jpg" alt="">
<img class="img-responsive" src="/images/consent-page.jpg" alt="">
</div>
<h5>Step 3: Application receives Authorization Code</h5>
<p>Once the user grants access, the permission page is redirected to the <code>redirect_uri</code> with the <code>code</code> and <code>state</code> as url parameters. Your application should verify that the <code>state</code> parameter matches the request to prevent CSRF attacks. The <code>code</code> will be used in the next step to request an access token.</p>
<p>Note: If the consent page was opened in a new window your application is responsible to close it and pass the parameters to the parent window (your app). </p>
<h6>Example successful response:</h6>
<pre><code>https://my-cool-app.com/oauthcallback?code=c6153bbf147c1fcc5f05ebbabee2d396&state=fa04438a996f</code></pre>
<h6>Example unsuccessful response:</h6>
<pre><code>todo</code></pre>
<h5>Step 4: Application requests Access Token</h5>
<p>The <code>code</code> received in the previous step is short lived (60 sec). The application needs to exchange this code with an access token in that timeframe.</p>
<p>For this the application sends a POST request to the <code>/oauth/token</code> endpoint with the following form data:</p>
<table class="table table-condensed">
<thead>
<tr>
<th>Field</th>
<th>Description</th>
</tr>
</thead>
<tbody>
<tr>
<td><code>code</code></td>
<td>The authorization code returned from the previous step.</td>
</tr>
<tr>
<td><code>client_id</code></td>
<td>The client_id obtained when requesting the OAuth app.</td>
</tr>
<tr>
<td><code>client_secret</code></td>
<td>The client_secret obtained when requesting the OAuth app.</td>
</tr>
<tr>
<td><code>redirect_uri</code></td>
<td>One of the domains registered requesting the OAuth app, or simply the same redirect_uri used in the /oauth/authorize request.</td>
</tr>
<tr>
<td><code>grant_type</code></td>
<td>As defined in the OAuth 2.0 specification, this field must contain a value of <code>authorization_code</code></td>
</tr>
</tbody>
</table>
<h6>Example request:</h6>
<pre><code>POST /oauth/token HTTP/1.1
Host: circuitsandbox.net
Content-Type: application/x-www-form-urlencoded
client_id=aee562d3d6a947efa04438a996f34c80&
client_secret=7fb9eec31b7d45ffaeb9398b93454cfd&
redirect_uri=https://my-cool-app.com/oauthcallback&
grant_type=authorization_code&
code=c6153bbf147c1fcc5f05ebbabee2d396</code></pre>
<p><i>Line breaks for readability of form fields</i></p>
<h5>Step 5: Application Receives Access Token</h5>
<p>If the authorization is valid, the Circuit Server will send a response containing the access token (and optionally, a refresh token) to the application.</p>
<h6>Example successful response:</h6>
<pre><code>{"access_token":"a542f71d785d40b9924c8d07b518629a","token_type":"Bearer","scope":["READ_USER_PROFILE","READ_CONVERSATIONS"]}</code></pre>
<h5>Step 6: Perform API calls on user's behalf</h5>
<p>With the obtained token the application can perform REST API calls, or use the JS SDK in node.js or even in the browser. But if you app is a client-side web app, you are much better of to use the JS SDK to handle all the above, and use the implicit grant explained below.</p>
<p>For REST API calls, the OAuth access token (aka Bearer token) should be included in the HTTP Authorization header.</p>
<h6>Example curl request to fetch conversation on behalf of user:</h6>
<pre><code>curl -i "https://circuitsandbox.net/rest/v2/conversations" -H "Authorization: Bearer a542f71d785d40b9924c8d07b518629a"</code></pre>
<h4>Code examples</h4>
<ul>
<li>Simple server-side web app in node.js is listed on the <a href="rest.html">REST API</a> page with its source code on <a href="https://github.com/circuit/webserver-example" target="_blank">github</a>.</li>
<li>Server-side node.js web app using <a href="https://www.npmjs.com/package/simple-oauth2" target="_blank">simple-oauth2</a> to handle OAuth flow on <a href="https://github.com/circuit/node-linkify" target="_blank">github</a>. This app also uses the JS SDK to update text messages.</li>
</ul>
</div>
<div class="row" id="implicit">
<h3>Implicit Grant</h3>
<p>The implicit grant type is used for client-side web applications (i.e. applications that run in a web browser), where the client secret confidentiality is not guaranteed. The implicit grant type is also a redirection-based flow but the access token is given to the client-side JavaScript application, so it may be exposed to the user and other applications on the user's device. Also, this flow does not authenticate the identity of the application, and relies on the redirect uri (upon requesting the app) to serve this purpose.</p>
<p>The implicit grant type does not support refresh tokens.</p>
<p>For more details on Implicit Grant refer to <a href="https://tools.ietf.org/html/rfc6749#section-4.2" target="_blank">rfc6749 section 4.2</a>.</p>
<h4>JavaScript SDK</h4>
<p>Rather than implementing this flow manually in your JavaScript application, you might want to use the JS SDK which abstracts this flow for you. Using the JS SDK the logon is as simple as this:</p>
<pre class="prettyprint">
let client = new Circuit.Client({
client_id: 'your app key',
scope: 'READ_USER_PROFILE,READ_CONVERSATIONS'
});
client.logon()
.then(user => console.log('Successfully authenticated as ' + user.displayName))
.catch(console.error);</pre>
<h4>Implicit Flow</h4>
<p>Once your app is registered you are provided with a <code>client_id</code>. The client_id identifies your app. Using the client_id your app can get an OAuth access token on behalf of a user, as long as the user is willing to give your app access.</p>
<h5>Step 1: Application Requests Authorization Code</h5>
<p>On page load, or on a user action (e.g. login button) your app (the browser) needs to redirect to Circuit's <code>/oauth/authorize</code> endpoint. Rather than a redirect apps usually opt to open a new window instead. The request requires the following parameters:</p>
<table class="table table-condensed">
<thead>
<tr>
<th>Parameter</th>
<th>Value</th>
<th>Description</th>
</tr>
</thead>
<tbody>
<tr>
<td><code>response_type</code></td>
<td><code>token</code></td>
<td>Causes the Circuit endpoint to return an access token. Client-side web apps should use <b>token</b>.</td>
</tr>
<tr>
<td><code>client_id</code></td>
<td>The client_id obtained when requesting the OAuth app.</td>
<td>Identifies the client that is making the request. The value passed in this parameter must exactly match the client_id obtained.</td>
</tr>
<tr>
<td><code>redirect_uri</code></td>
<td>Url to be redirected after access is granted by user.</td>
<td>Complete Url including protocol and port if applicable. Host (protocol, domain and port) must match one of the domains of requested OAuth app. E.g. https://my-cool-app.com/oauthcallback in which case https://my-cool-app.com had to be requested on app creation.</td>
</tr>
<tr>
<td><code>scope</code></td>
<td>Comma-delimited set of permissions that the application requests.</td>
<td>The values passed in this parameter are listed on the consent screen that is shown to the user. Supported scopes are: <code>ALL, READ_USER_PROFILE, WRITE_USER_PROFILE, READ_CONVERSATIONS, WRITE_CONVERSATIONS, READ_USER, CALLS</code></td>
</tr>
<tr>
<td><code>state</code></td>
<td>Any string</td>
<td>Provides any state that might be useful to your application upon receipt of the response. The Circuit Server roundtrips this parameter, so your application receives the same value it sent. To mitigate against cross-site request forgery (CSRF), it is strongly recommended to include an anti-forgery token in the state, and confirm it in the response.</td>
</tr>
<tr>
<td><code>login_hint</code></td>
<td>email</td>
<td>Optional. If your application knows which user is trying to authenticate, it can use this parameter to provide a hint to the Circuit Authentication Server. The server uses the hint to simplify the login flow by prefilling the email field in the sign-in form.</td>
</tr>
<tr>
<td><code>prompt</code></td>
<td>comma delimited string</td>
<td>Optional. A comma-delimited (no spaces), case-sensitive list of options for the oauth window.
<ul>
<li><code>disable_email</code>: Disable email field (only applicable if login_hint is provided)</li>
<li><code>disable_switch</code>: Disable ability to switch the account from to Oauth popup</li>
<li><code>disable_caching</code>: Hide the "private computer" checkbox.</li>
</ul>
</td>
</tr>
</tbody>
</table>
<h6>Example request:</h6>
<pre><code>https://circuitsandbox.net/oauth/authorize?client_id=aee562d3d6a947efa04438a996f34c80&redirect_uri=https%3A%2F%2Foutput.jsbin.com%2Fcesuxu%2F17&response_type=token&scope=READ_USER_PROFILE,READ_CONVERSATIONS&state=fa04438a996f</code></pre>
<h5>Step 2: User grants access</h5>
<p>The browser will now show the OAuth permission/consent page (with prior login if not already logged in). This page is asking the user to give your app permissions to act on the user's behalf. The app name and author are shown on that page to identify the app, as well as the requested permissions.</p>
<div class="oauth-image" style="display: flex;flex-flow: row nowrap;">
<img class="img-responsive" src="/images/login-page.jpg" alt="">
<img class="img-responsive" src="/images/consent-page.jpg" alt="">
</div>
<h5>Step 3: Application receives Access Token</h5>
<p>Once the user grants access, the permission page is redirected to the <code>redirect_uri</code> with the <code>access_token</code> and <code>state</code> as url parameters. Your application should verify that the <code>state</code> parameter matches the request to prevent CSRF attacks. The <code>access_token</code> can now be used by your client-side app to perform API calls on the user's behalf.<br>
Note: If the consent page was opened in a new window your application is responsible to close it and pass the parameters to the parent window (your app). </p>
<h6>Example successful response:</h6>
<pre><code>https://my-cool-app.com/oauthcallback#access_token=a542f71d785d40b9924c8d07b518629a&state=fa04438a996f</code></pre>
<h5>Step 4: Perform API calls on user's behalf</h5>
<p>With the obtained token the application can perform REST API calls, or even use the JS SDK using the token. But if you are using the JS SDK then you can skip all the above steps and let the SDK do that work for you.</p>
<p>For REST API calls, the OAuth access token (aka Bearer token) should be included in the HTTP Authorization header.</p>
<h6>Example curl request to fetch conversation on behalf of user:</h6>
<pre><code>curl -i "https://circuitsandbox.net/rest/v2/conversations" -H "Authorization: Bearer a542f71d785d40b9924c8d07b518629a"</code></pre>
<h4>Code examples</h4>
<p>A simple client-side web app OAuth example is listed on the <a href="rest.html">REST API</a> page with its source code on <a href="https://github.com/circuit/js-sdk/blob/master/oauthrest.html" target="_blank">github</a>.</p>
</div>
<div class="row" id="client_credentials">
<h3>Client Credentials Grant</h3>
<p>The client credentials grant type provides an application a way to access its own service account. Examples of when this might be useful include Bot applications that can be added as participant in conversations.</p>
<p>The Client Credentials Grant should only be used in a server-side application to keep the secret confidential. The JavaScript SDK also supports this gratn type, but should only be used by server-side node.js applications.</p>
<p>For more details on Client Credentials Grant refer to <a href="https://tools.ietf.org/html/rfc6749#section-4.4" target="_blank">rfc6749 section 4.4</a>.</p>
<h4>Client Credentials Flow</h4>
<p>Since this flow is acting on its own behalf rather than on another user's behalf, this flow is very simple.</p>
<p>The application requests an access token by sending its credentials (<code>client_id</code> and <code>client_secret</code>) to the Circuit server.</p>
<table class="table table-condensed">
<thead>
<tr>
<th>Parameter</th>
<th>Value</th>
<th>Description</th>
</tr>
</thead>
<tbody>
<tr>
<td><code>grant_type</code></td>
<td><code>client_credentials</code></td>
<td>Causes the Circuit endpoint to return an access token for the client_id and client_secret.</td>
</tr>
<tr>
<td><code>client_id</code></td>
<td>The client_id obtained when requesting the OAuth app.</td>
<td>Identifies the client that is making the request. The value passed in this parameter must exactly match the client_id obtained. Sent in body, or in Authorization Header.</td>
</tr>
<tr>
<td><code>client_secret</code></td>
<td>The client_secret obtained when requesting the OAuth app.</td>
<td>Secret to authenticate and authorize the app.</td>
</tr>
<tr>
<td><code>scope</code></td>
<td>Comma-delimited set of permissions that the application requests.</td>
<td>The values passed in this parameter are listed on the consent screen that is shown to the user. Supported scopes are: <code>ALL, READ_USER_PROFILE, WRITE_USER_PROFILE, READ_CONVERSATIONS, WRITE_CONVERSATIONS, READ_USER, CALLS</code></td>
</tr>
</tbody>
</table>
<h6>Example request:</h6>
<pre><code>POST /oauth/token HTTP/1.1
Host: circuitsandbox.net
Content-Type: application/x-www-form-urlencoded
client_id=aee562d3d6a947efa04438a996f34c80&
client_secret=7fb9eec31b7d45ffaeb9398b93454cfd&
grant_type=
&
scope=READ_USER_PROFILE</code></pre>
<p><i>Line breaks for readability of form fields</i></p>
<h6>Example request (client_id and secret in Authorization Header):</h6>
<pre><code>POST /oauth/token HTTP/1.1
Host: circuitsandbox.net
Content-Type: application/x-www-form-urlencoded
Authorization: Basic "btoa(client_id:client_secret)"
grant_type=client_credentials&scope=READ_USER_PROFILE</code></pre>
<h6>Example successful response:</h6>
<pre><code>{"access_token":"a542f71d785d40b9924c8d07b518629a","token_type":"Bearer","scope":["READ_USER_PROFILE","READ_CONVERSATIONS"]}</code></pre>
<p>With the obtained token the application can perform API calls.</p>
<p>For REST API calls, the OAuth access token (aka Bearer token) should be included in the HTTP Authorization header.</p>
<h6>Example curl request to fetch the applications conversations:</h6>
<pre><code>curl -i "https://circuitsandbox.net/rest/v2/conversations" -H "Authorization: Bearer a542f71d785d40b9924c8d07b518629a"</code></pre>
</div>
<!--
<div class="row" id="resource_owner">
<h3>Resource Owner Password Credentials Grant</h3>
<p>With the resource owner password credentials grant type, the user provides their service credentials (username and password) directly to the application, which uses the credentials to obtain an access token from the service. This grant type should only be enabled on the authorization server if <b>other flows are not viable</b>. Also, it should only be used if the application is <b>trusted</b> by the user (e.g. it is owned by the service, or the user's desktop OS).</p>
<p>For more details on Resource Owner Password Credentials Grant refer to <a href="https://tools.ietf.org/html/rfc6749#section-4.3" target="_blank">rfc6749 section 4.3</a>.</p>
<h4>Resource Owner Password Credentials Flow</h4>
<p>After the user provides credentials to the application, the application requests an access token from the authorization server using a POST request.</p>
<table class="table table-condensed">
<thead>
<tr>
<th>Parameter</th>
<th>Value</th>
<th>Description</th>
</tr>
</thead>
<tbody>
<tr>
<td><code>grant_type</code></td>
<td><code>password</code></td>
<td>Causes the Circuit endpoint to return an access token for the provided credentials and client_id.</td>
</tr>
<tr>
<td><code>scope</code></td>
<td>Comma-delimited set of permissions that the application requests.</td>
<td>The values passed in this parameter are listed on the consent screen that is shown to the user. Supported scopes are: <code>ALL, READ_USER_PROFILE, WRITE_USER_PROFILE, READ_CONVERSATIONS, WRITE_CONVERSATIONS, READ_USER, CALLS</code>. Sent in formdata of body</td>
</tr>
<tr>
<td><code>username</code></td>
<td>The username (email) of the Circuit user</td>
<td>Sent in formdata of body.</td>
</tr>
<tr>
<td><code>password</code></td>
<td>The password of the Circuit user.</td>
<td>Sent in formdata of body.</td>
</tr>
<tr>
<td><code>client_id</code></td>
<td>The client_id obtained when requesting the OAuth app.</td>
<td>Identifies the client that is making the request. The value passed in this parameter must exactly match the client_id obtained. <br>Sent in Authorization Header as Basic Authentication (base64 encoded), either by itself or together with client_secret.</td>
</tr>
<tr>
<td><code>client_secret</code></td>
<td>Require if the client_secret was obtained when requesting the OAuth app, otherwise client_secret is omitted.</td>
<td>Sent in Authorization Header as Basic Authentication (base64 encoded). Only applicable if application was requested with client_secret.</td>
</tr>
</tbody>
</table>
<h6>Example request:</h6>
<pre><code>POST /oauth/token HTTP/1.1
Host: circuitsandbox.net
Content-Type: application/x-www-form-urlencoded
Authorization: Basic "btoa(client_id:client_secret)"
username=roger.urscheler@atos.net&password=P@ssw0rd&grant_type=password</code></pre>
<h6>Example request using curl with only client_id:</h6>
<pre><code>curl https://circuitsandbox.net/oauth/token --user aee562d3d6a947efa04438a996f34c80 -d 'grant_type=password&username=roger.urscheler@atos.net&password=P@ssw0rd&scope=ALL'</code></pre>
<h6>Example successful response:</h6>
<pre><code>{"access_token":"a542f71d785d40b9924c8d07b518629a","token_type":"Bearer","scope":[]}</code></pre>
<p>With the obtained token the application can perform API calls.</p>
<p>For REST API calls, the OAuth access token (aka Bearer token) should be included in the HTTP Authorization header.</p>
<h6>Example curl request to fetch the applications conversations:</h6>
<pre><code>curl -i "https://circuitsandbox.net/rest/v2/conversations" -H "Authorization: Bearer a542f71d785d40b9924c8d07b518629a"</code></pre>
</div>
-->
<div class="row" id="refresh_token">
<h3>Refresh Token Flow</h3>
<p>After an access token expires, using it to make a request from the API will result in an "Invalid Token Error". At this point, if a refresh token was included when the original access token was issued, it can be used to request a fresh access token from the authorization server. This is only applicable to the Authorization Code Grant.</p>
<p>Use REST API. Not available in JS SDK.</p>
<p>For more details on Token Refresh refer to <a href="https://tools.ietf.org/html/rfc6749#section-6" target="_blank">rfc6749 section 6</a>.</p>
</div>
<div class="row" id="renew_token">
<h3>Renew token</h3>
<p>The JS SDK allows apps to renew the access token prior to its expiry using the API <code><a href="https://circuitsandbox.net/sdk/classes/Client.html#method_renewToken">renewToken</a></code>.</p>
<p>This is applicable to Implicit and Client Credentials Grant.</p>
<p>For Client Credentials grant the token can also be automatically renewed by setting the configuration parameter <code><a href="https://circuitsandbox.net/sdk/classes/Client.html">autoRenewToken</a></code>.</p>
</div>
<div class="row" id="revoke_token">
<h3>Revoke a Token</h3>
<p>Users can revoke tokens created on their behalf on their Circuit web client at "Settings > Security > Connected Apps".</p>
<p>Applications can revoke token using the JS SDK API <code><a href="https://circuitsandbox.net/sdk/classes/Client.html#method_revokeToken">revokeToken</a></code>.</p>
<br><br>
</div>
<div class="row" style="height:1000px">
<!-- leave some room for anchors to jump to the right place -->
</div>
<!-- /.row -->
</div>
</div>
</div>
<!-- /#wrapper -->
<script src="js/jquery.js"></script>
<script src="js/bootstrap.min.js"></script>
<script src="https://cdn.rawgit.com/google/code-prettify/master/loader/run_prettify.js"></script>
<script>
$(function(){
$("#sidebar-wrapper").load("/sidebar.html");
});
</script>
<script>
(function(i,s,o,g,r,a,m){i['GoogleAnalyticsObject']=r;i[r]=i[r]||function(){
(i[r].q=i[r].q||[]).push(arguments)},i[r].l=1*new Date();a=s.createElement(o),
m=s.getElementsByTagName(o)[0];a.async=1;a.src=g;m.parentNode.insertBefore(a,m)
})(window,document,'script','https://www.google-analytics.com/analytics.js','ga');
ga('create', 'UA-67318539-2', 'auto');
ga('send', 'pageview');
</script>
</body>
</html>