You signed in with another tab or window. Reload to refresh your session.You signed out in another tab or window. Reload to refresh your session.You switched accounts on another tab or window. Reload to refresh your session.Dismiss alert
This example describes an example OAuth2 workflow using the _Authorization Code Grant_ flow as per [section 4.1 of the OAuth2 specification](https://tools.ietf.org/html/rfc6749#section-4.1). Uris of required endpoints are assumed to have been obtained from the authentication resource as described in [section 3.2 of the BCF API specification](https://github.com/BuildingSMART/BCF-API#321-obtaining-authentication-information).
4
+
5
+
For this example, it is assumed that the client has been registered with the server in advance and has been issued valid credentials in the form of `client_id` and `client_secret`.
6
+
7
+
## Client Request
8
+
9
+
To initiate the workflow, the client sends the user to the **"oauth2\_auth_url"** with the following parameters added:
10
+
11
+
|parameter|value|
12
+
|-------------|------|
13
+
|response_type|`code` as string literal|
14
+
|client_id|your client id|
15
+
|state|unique user defined value|
16
+
17
+
Example URL:
18
+
19
+
GET https://example.com/bcf/oauth2/auth?response_type=code&client_id=<your_client_id>&state=<user_defined_string>
20
+
21
+
_On Windows operating systems, it is possible to open the systems default browser by using the url to start a new process._
The BCF API server will ask the user to confirm that the client may access resources on his behalf. On authorization, the server redirects to an url that has been defined by the client author in advance. The generated `code` parameter will be appended as query parameter. Additionally, the `state` parameter is included in the redirection, it may be used to match server responses to client requests issued by your application.
28
+
29
+
If the user denies client access, there will be an `error` query parameter in the redirection indicating an error reason as described in [section 4.1.2.1 of the OAuth2 specification](https://tools.ietf.org/html/rfc6749#section-4.1.2.1).
30
+
31
+
## Token Request
32
+
33
+
With the obtained _authorization code_, the client is able to request an access token from the server. The **"oauth2\_token_url"** from the authentication resource is used to send token requests to, for example:
34
+
35
+
POST https://example.com/bcf/oauth2/token
36
+
37
+
**Parameters**
38
+
39
+
|parameter|type|description|
40
+
|---------|----|-----------|
41
+
|access_token|string|The issued OAuth2 token|
42
+
|token_type|string|Always `bearer`|
43
+
|expires_in|integer|The lifetime of the access token in seconds|
The POST request should be done via HTTP Basic Authorization with your applications `client_id` as the username and your `client_secret` as the password.
47
+
48
+
**Example Request**
49
+
50
+
POST https://example.com/bcf/oauth2/token?grant_type=authorization_code&code=<your_access_code>
51
+
52
+
The access token will be returned as JSON in the response body and is an arbitrary string, guaranteed to not exceed 255 characters length.
The process to retrieve a refresh token is exactly the same as retrieving a token via the code workflow except the `refresh_token` is sent instead of the `code` parameter and the `refresh_token` grant type is used.
68
+
69
+
**Example Request**
70
+
71
+
POST https://example.com/bcf/oauth2/token?grant_type=refresh_token&refresh_token=<your_refresh_token>
72
+
73
+
The access token will be returned as JSON in the response body and is an arbitrary string, guaranteed to not exceed 255 characters length.
The refresh token can only be used once to retrieve a token and a new refresh token.
87
+
88
+
## Requesting Resources
89
+
90
+
When requesting other resources the access token must be passed via the `Authorization` header using the `Bearer` scheme (e.g. `Authorization: Bearer Zjk1YjYyNDQtOTgwMy0xMWU0LWIxMDAtMTIzYjkzZjc1Y2Jh`).
@@ -299,22 +296,31 @@ Authentication is based on the [OAuth 2.0 Protocol](http://tools.ietf.org/html/d
299
296
300
297
**Resource URL (public resource)**
301
298
302
-
GET /bcf/auth
299
+
GET /bcf/{version}/auth
303
300
304
301
**Parameters**
305
302
306
303
|Parameter|Type|Description|Required|
307
304
|---------|----|-----------|--------|
308
-
|oauth2_auth_url|string|URL to authorisation page|false|
305
+
|oauth2_auth_url|string|URL to authorization page (used for Authorization Code Grant and Implicit Grant OAuth2 flows)|false|
309
306
|oauth2_token_url|string|URL for token requests|false|
310
307
|oauth2_dynamic_client_reg_url|string|URL for automated client registration|false|
311
308
|http_basic_supported|boolean|Indicates if Http Basic Authentication is supported|false|
309
+
|supported_oauth2_flows|string[]|array of supported OAuth2 flows|
312
310
313
311
If `oauth2_auth_url` is present, then `oauth2_token_url` must also be present and vice versa. If properties are not present in the response, clients should assume that the functionality is not supported by the server, e.g. a missing `http_basic_supported` property would indicate that Http basic authentication is not available on the server.
314
312
313
+
OAuth2 flows are described in detail in the [OAuth2 specification](https://tools.ietf.org/html/rfc6749). BCF API servers may support the following workflows:
The [OAuth2 Client Credentials Grant (section 4.4)](https://tools.ietf.org/html/rfc6749#section-4.4) is not supported since it does not contain any user identity.
319
+
Also the [Extension Grants (section 4.5)](https://tools.ietf.org/html/rfc6749#section-4.5) are not supported.
320
+
315
321
**Example Request**
316
322
317
-
GET /bcf/auth
323
+
GET /bcf/2.1/auth
318
324
319
325
**Example Response**
320
326
@@ -324,120 +330,33 @@ If `oauth2_auth_url` is present, then `oauth2_token_url` must also be present an
You can use the state parameter to transport custom information.
350
-
351
-
**Open a browser window or redirect the user to this resource.** This redirects back to the specified redirect URI with the provided state and the authorization code as a query parameter if the user allows your app to access the account, the value "access_denied" in the error query parameter if the user denies access.
The POST request can be done via HTTP Basic Authorization with your applications `client_id` as the username and your `client_secret` as the password.
371
-
372
-
**Example Request**
373
-
374
-
POST https://example.com/bcf/oauth2/token?grant_type=authorization_code&code=<your_access_code>
375
-
376
-
Alternatively all parameters may be passed in the token request body instead of using Url parameters. The expected `Content-Type` for this request is `application/x-www-form-urlencoded`.
The process to retrieve a refresh token is exactly the same as retrieving a token via the code workflow except the `refresh_token` is sent instead of the `code` parameter and the `refresh_token` grant type is used.
400
-
401
-
**Example Request**
343
+
An example for the OAuth2 Authorization Grant workflow [can be found here](OAuth2Examples.md).
402
344
403
-
POST https://example.com/bcf/oauth2/token?grant_type=refresh_token&refresh_token=<your_refresh_token>
404
-
405
-
Alternatively all parameters may be passed in the token request body instead of using Url parameters.
The following part describes the optional dynamic registration process of a client. BCF-Servers may offer additional processes registering clients, for example allowing a client application developer to register his client on the servers website.
433
352
434
-
The resource Url for this service is server specific and is returned as `oauth2_dynamic_client_reg_url` in the `GET /bcf/auth` resource.
353
+
The resource url for this service is server specific and is returned as `oauth2_dynamic_client_reg_url` in the `GET /bcf/{version}/auth` resource.
435
354
436
355
Register a new client :
437
356
438
357
**Parameters**
439
358
440
-
JSON encoded body using the "application/json" content type.
359
+
JSON encoded body using the `application/json` content type.
441
360
442
361
|parameter|type|description|
443
362
|---------|----|-----------|
@@ -466,10 +385,6 @@ JSON encoded body using the "application/json" content type.
When requesting other resources the access token must be passed via the `Authorization` header using the Bearer scheme (e.g. `Authorization: Bearer Zjk1YjYyNDQtOTgwMy0xMWU0LWIxMDAtMTIzYjkzZjc1Y2Jh`).
0 commit comments