From 1c5bee4c1474633319b7d5675f55b8c992f1dbcb Mon Sep 17 00:00:00 2001 From: Georg Dangl Date: Thu, 22 Dec 2016 14:59:48 +0100 Subject: [PATCH 1/3] Removing BCF API OAuth2 specifics Decided to reference the official OAuth2 specification to indicate that the BCF API does not deviate from the regular OAuth2 specification. The authorization code flow has been moved to an example file. --- OAuth2Examples.md | 90 ++++++++++++ README.md | 135 ++++-------------- Schemas_draft-03/Authentication/auth_GET.json | 7 + .../Authentication/token_GET.json | 24 ---- 4 files changed, 122 insertions(+), 134 deletions(-) create mode 100644 OAuth2Examples.md delete mode 100644 Schemas_draft-03/Authentication/token_GET.json diff --git a/OAuth2Examples.md b/OAuth2Examples.md new file mode 100644 index 0000000..10c466a --- /dev/null +++ b/OAuth2Examples.md @@ -0,0 +1,90 @@ +# BCF API OAuth2 Example + +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). + +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`. + +## Client Request + +To initiate the workflow, the client sends the user to the **"oauth2\_auth_url"** with the following parameters added: + +|parameter|value| +|-------------|------| +|response_type|`code` as string literal| +|client_id|your client id| +|state|unique user defined value| + +Example URL: + + GET https://example.com/bcf/oauth2/auth?response_type=code&client_id=&state= + +_On Windows operating systems, it is possible to open the systems default browser by using the url to start a new process._ + +Example redirected URL: + + https://YourWebsite.com/retrieveCode?code=&state= + +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. + +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). + +## Token Request + +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: + + POST https://example.com/bcf/oauth2/token + +**Parameters** + +|parameter|type|description| +|---------|----|-----------| +|access_token|string|The issued OAuth2 token| +|token_type|string|Always `bearer`| +|expires_in|integer|The lifetime of the access token in seconds| +|refresh_token|string|The issued OAuth2 refresh token, one-time-usable only| + +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. + +**Example Request** + + POST https://example.com/bcf/oauth2/token?grant_type=authorization_code&code= + +The access token will be returned as JSON in the response body and is an arbitrary string, guaranteed to not exceed 255 characters length. + +**Example Response** + + Response Code: 201 - Created + Body: + { + "access_token": "Zjk1YjYyNDQtOTgwMy0xMWU0LWIxMDAtMTIzYjkzZjc1Y2Jh", + "token_type": "bearer", + "expires_in": "3600", + "refresh_token": "MTRiMjkzZTYtOTgwNC0xMWU0LWIxMDAtMTIzYjkzZjc1Y2Jh" + } + +## Refresh Token Request + +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. + +**Example Request** + + POST https://example.com/bcf/oauth2/token?grant_type=refresh_token&refresh_token= + +The access token will be returned as JSON in the response body and is an arbitrary string, guaranteed to not exceed 255 characters length. + +**Example Response** + + Response Code: 201 - Created + Body: + { + "access_token": "Zjk1YjYyNDQtOTgwMy0xMWU0LWIxMDAtMTIzYjkzZjc1Y2Jh", + "token_type": "bearer", + "expires_in": "3600", + "refresh_token": "MTRiMjkzZTYtOTgwNC0xMWU0LWIxMDAtMTIzYjkzZjc1Y2Jh" + } + +The refresh token can only be used once to retrieve a token and a new refresh token. + +## Requesting Resources + +When requesting other resources the access token must be passed via the `Authorization` header using the `Bearer` scheme (e.g. `Authorization: Bearer Zjk1YjYyNDQtOTgwMy0xMWU0LWIxMDAtMTIzYjkzZjc1Y2Jh`). \ No newline at end of file diff --git a/README.md b/README.md index ee06040..bd5b29a 100644 --- a/README.md +++ b/README.md @@ -29,11 +29,8 @@ * [3.1 Versions Service](#31-versions-service) * [3.2 Authentication Services](#32-authentication-services) + [3.2.1 Obtaining Authentication Information](#321-obtaining-authentication-information) - + [3.2.2 OAuth2 Protocol Flow - Client Request](#322-oauth2-protocol-flow---client-request) - + [3.2.3 OAuth2 Protocol Flow - Token Request](#323-oauth2-protocol-flow---token-request) - + [3.2.4 OAuth2 Protocol Flow - Refresh Token Request](#324-oauth2-protocol-flow---refresh-token-request) - + [3.2.5 OAuth2 Protocol Flow - Dynamic Client Registration](#325-oauth2-protocol-flow---dynamic-client-registration) - + [3.2.6 OAuth2 Protocol Flow - Requesting Resources](#326-oauth2-protocol-flow---requesting-resources) + + [3.2.2 OAuth2 Example](#322-oauth2-example) + + [3.2.3 OAuth2 Protocol Flow - Dynamic Client Registration](#323-oauth2-protocol-flow---dynamic-client-registration) * [3.3 User Services](#33-user-services) + [3.3.1 Get current user](#331-get-current-user) - [4. BCF Services](#4-bcf-services) @@ -299,22 +296,31 @@ Authentication is based on the [OAuth 2.0 Protocol](http://tools.ietf.org/html/d **Resource URL (public resource)** - GET /bcf/auth + GET /bcf/{version}/auth **Parameters** |Parameter|Type|Description|Required| |---------|----|-----------|--------| -|oauth2_auth_url|string|URL to authorisation page|false| +|oauth2_auth_url|string|URL to authorisation page (used for Authorization Code Grant and Implicit Grant OAuth2 flows)|false| |oauth2_token_url|string|URL for token requests|false| |oauth2_dynamic_client_reg_url|string|URL for automated client registration|false| |http_basic_supported|boolean|Indicates if Http Basic Authentication is supported|false| +|supported_oauth2_flows|string[]|array of supported OAuth2 flows| 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. +OAuth2 flows are described in detail in the [OAuth2 specification](https://tools.ietf.org/html/rfc6749). BCF API servers may support the following workflows: +* `authorization_code_grant` - [4.1 - Authorization Code Grant](https://tools.ietf.org/html/rfc6749#section-4.1) +* `implicit_grant` - [4.2 - Implicit Grant](https://tools.ietf.org/html/rfc6749#section-4.2) +* `resource_owner_password_credentials_grant` - [4.3 - Resource Owner Password Credentials Grant](https://tools.ietf.org/html/rfc6749#section-4.3) +* `extension_grants` - [4.5 - Extension Grants](https://tools.ietf.org/html/rfc6749#section-4.5) + +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 an user identity. + **Example Request** - GET /bcf/auth + GET /bcf/2.1/auth **Example Response** @@ -324,106 +330,19 @@ If `oauth2_auth_url` is present, then `oauth2_token_url` must also be present an "oauth2_auth_url": "https://example.com/bcf/oauth2/auth", "oauth2_token_url": "https://example.com/bcf/oauth2/token", "oauth2_dynamic_client_reg_url": "https://example.com/bcf/oauth2/reg", - "http_basic_supported": true - } - -### 3.2.2 OAuth2 Protocol Flow - Client Request - -The Client uses the **"oauth2\_auth_url"** and adds the following parameters to it. - -|parameter|value| -|-------------|------| -|response_type|`code` as string literal| -|client_id|your client id| -|state|unique user defined value| - -Example URL: - - GET https://example.com/bcf/oauth2/auth?response_type=code&client_id=&state= - -Example redirected URL: - - https://YourWebsite.com/retrieveCode?code=&state= - -Tip: -You can use the state parameter to transport custom information. - -**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. - -### 3.2.3 OAuth2 Protocol Flow - Token Request - -[token_GET.json](Schemas_draft-03/Authentication/token_GET.json) - -The Client uses the **"oauth2\_token_url"** to request a token. Example: - - POST https://example.com/bcf/oauth2/token - -**Parameters** - -|parameter|type|description| -|---------|----|-----------| -|access_token|string|The issued OAuth2 token| -|token_type|string|Always `bearer`| -|expires_in|integer|The lifetime of the access token in seconds| -|refresh_token|string|The issued OAuth2 refresh token, one-time-usable only| - -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. - -**Example Request** - - POST https://example.com/bcf/oauth2/token?grant_type=authorization_code&code= - -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`. - - POST https://example.com/bcf/oauth2/token - Body: - grant_type=authorization_code&code=&client_id=&client_secret= - -The access token will be returned as JSON in the response body and is an arbitrary string, guaranteed to not exceed 255 characters length. - -**Example Response** - - Response Code: 201 - Created - Body: - { - "access_token": "Zjk1YjYyNDQtOTgwMy0xMWU0LWIxMDAtMTIzYjkzZjc1Y2Jh", - "token_type": "bearer", - "expires_in": "3600", - "refresh_token": "MTRiMjkzZTYtOTgwNC0xMWU0LWIxMDAtMTIzYjkzZjc1Y2Jh" + "http_basic_supported": true, + "supported_oauth2_flows": [ + "authorization_code_grant", + "implicit_grant", + "resource_owner_password_credentials_grant" + ] } -### 3.2.4 OAuth2 Protocol Flow - Refresh Token Request - -[token_GET.json](Schemas_draft-03/Authentication/token_GET.json) +### 3.2.2 OAuth2 Example -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. - -**Example Request** +An example for the OAuth2 Authorization Grant workflow [can be found here](OAuth2Examples.md). - POST https://example.com/bcf/oauth2/token?grant_type=refresh_token&refresh_token= - -Alternatively all parameters may be passed in the token request body instead of using Url parameters. - - POST https://example.com/bcf/oauth2/token - Body: - grant_type=refresh_token&refresh_token=&client_id=&client_secret= - -The access token will be returned as JSON in the response body and is an arbitrary string, guaranteed to not exceed 255 characters length. - -**Example Response** - - Response Code: 201 - Created - Body: - { - "access_token": "Zjk1YjYyNDQtOTgwMy0xMWU0LWIxMDAtMTIzYjkzZjc1Y2Jh", - "token_type": "bearer", - "expires_in": "3600", - "refresh_token": "MTRiMjkzZTYtOTgwNC0xMWU0LWIxMDAtMTIzYjkzZjc1Y2Jh" - } - -The refresh token can only be used once to retrieve a token and a new refresh token. - -### 3.2.5 OAuth2 Protocol Flow - Dynamic Client Registration +### 3.2.3 OAuth2 Protocol Flow - Dynamic Client Registration [dynRegClient\_POST.json](Schemas_draft-03/Authentication/dynRegClient_POST.json) @@ -431,13 +350,13 @@ The refresh token can only be used once to retrieve a token and a new refresh to 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. -The resource Url for this service is server specific and is returned as `oauth2_dynamic_client_reg_url` in the `GET /bcf/auth` resource. +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. Register a new client : **Parameters** -JSON encoded body using the "application/json" content type. +JSON encoded body using the `application/json` content type. |parameter|type|description| |---------|----|-----------| @@ -466,10 +385,6 @@ JSON encoded body using the "application/json" content type. "client_secret": "ZWFzdXJlLg==" } -### 3.2.6 OAuth2 Protocol Flow - Requesting Resources - -When requesting other resources the access token must be passed via the `Authorization` header using the Bearer scheme (e.g. `Authorization: Bearer Zjk1YjYyNDQtOTgwMy0xMWU0LWIxMDAtMTIzYjkzZjc1Y2Jh`). - ---------- ## 3.3 User Services diff --git a/Schemas_draft-03/Authentication/auth_GET.json b/Schemas_draft-03/Authentication/auth_GET.json index 935d66e..85e60b2 100644 --- a/Schemas_draft-03/Authentication/auth_GET.json +++ b/Schemas_draft-03/Authentication/auth_GET.json @@ -17,6 +17,13 @@ "http_basic_supported": { "type": ["boolean", "null"] + }, + "supported_oauth2_flows": { + "type": ["array", + "null"], + "items": { + "type": ["string"] + } } } } \ No newline at end of file diff --git a/Schemas_draft-03/Authentication/token_GET.json b/Schemas_draft-03/Authentication/token_GET.json deleted file mode 100644 index 2824b3a..0000000 --- a/Schemas_draft-03/Authentication/token_GET.json +++ /dev/null @@ -1,24 +0,0 @@ -{ - "$schema": "http://json-schema.org/draft-03/schema#", - "title": "token_GET", - "description": "Access Token in BCF REST API.", - "type": "object", - "properties": { - "access_token": { - "type": "string", - "required": true - }, - "token_type": { - "type": "string", - "required": true - }, - "expires_in": { - "type": "integer", - "required": true - }, - "refresh_token": { - "type": "string", - "required": true - } - } -} \ No newline at end of file From 39f58a5e61b98162ab15fa134ab0dcd71de465ae Mon Sep 17 00:00:00 2001 From: Georg Dangl Date: Mon, 16 Jan 2017 11:00:15 +0100 Subject: [PATCH 2/3] Add proposed fixes by jasollien --- README.md | 4 ++-- Schemas_draft-03/Authentication/auth_GET.json | 2 +- 2 files changed, 3 insertions(+), 3 deletions(-) diff --git a/README.md b/README.md index bd5b29a..0bea789 100644 --- a/README.md +++ b/README.md @@ -302,7 +302,7 @@ Authentication is based on the [OAuth 2.0 Protocol](http://tools.ietf.org/html/d |Parameter|Type|Description|Required| |---------|----|-----------|--------| -|oauth2_auth_url|string|URL to authorisation page (used for Authorization Code Grant and Implicit Grant OAuth2 flows)|false| +|oauth2_auth_url|string|URL to authorization page (used for Authorization Code Grant and Implicit Grant OAuth2 flows)|false| |oauth2_token_url|string|URL for token requests|false| |oauth2_dynamic_client_reg_url|string|URL for automated client registration|false| |http_basic_supported|boolean|Indicates if Http Basic Authentication is supported|false| @@ -316,7 +316,7 @@ OAuth2 flows are described in detail in the [OAuth2 specification](https://tools * `resource_owner_password_credentials_grant` - [4.3 - Resource Owner Password Credentials Grant](https://tools.ietf.org/html/rfc6749#section-4.3) * `extension_grants` - [4.5 - Extension Grants](https://tools.ietf.org/html/rfc6749#section-4.5) -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 an user identity. +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. **Example Request** diff --git a/Schemas_draft-03/Authentication/auth_GET.json b/Schemas_draft-03/Authentication/auth_GET.json index 85e60b2..c7f8e24 100644 --- a/Schemas_draft-03/Authentication/auth_GET.json +++ b/Schemas_draft-03/Authentication/auth_GET.json @@ -26,4 +26,4 @@ } } } -} \ No newline at end of file +} From 059e00ab7de1741dfb1a99ea1418e84fdd238c4f Mon Sep 17 00:00:00 2001 From: Georg Dangl Date: Mon, 16 Jan 2017 11:51:54 +0100 Subject: [PATCH 3/3] Remove extension grants --- README.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/README.md b/README.md index 0bea789..4478dcb 100644 --- a/README.md +++ b/README.md @@ -314,9 +314,9 @@ OAuth2 flows are described in detail in the [OAuth2 specification](https://tools * `authorization_code_grant` - [4.1 - Authorization Code Grant](https://tools.ietf.org/html/rfc6749#section-4.1) * `implicit_grant` - [4.2 - Implicit Grant](https://tools.ietf.org/html/rfc6749#section-4.2) * `resource_owner_password_credentials_grant` - [4.3 - Resource Owner Password Credentials Grant](https://tools.ietf.org/html/rfc6749#section-4.3) -* `extension_grants` - [4.5 - Extension Grants](https://tools.ietf.org/html/rfc6749#section-4.5) 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. +Also the [Extension Grants (section 4.5)](https://tools.ietf.org/html/rfc6749#section-4.5) are not supported. **Example Request**