Add OAuth Browser Flow documentation
Resolves #4
Change-Id: I4384a97d2125eaace79e6f99057f5882af349e7a
diff --git a/R/KorAPConnection.R b/R/KorAPConnection.R
index 8921e44..ea6d5c4 100644
--- a/R/KorAPConnection.R
+++ b/R/KorAPConnection.R
@@ -30,13 +30,29 @@
#' @param KorAPUrl URL of the web user interface of the KorAP server instance you want to access.
#' @param apiVersion which version of KorAP's API you want to connect to.
#' @param apiUrl URL of the KorAP web service.
-#' @param accessToken OAuth2 access token. To use authorization based on an access token
-#' in subsequent queries, initialize your KorAP connection with
-#' `kco <- new("KorAPConnection", accessToken="<access token>")`.
+#' @param accessToken OAuth2 access token. For queries on corpus parts with restricted
+#' access (e.g. textual queries on IPR protected data), you need to authorize
+#' your application with an access token.
+#' How to obtain an access token for the DeReKo KorAP instance is explained in the
+#' [authorization section](https://github.com/KorAP/RKorAPClient#authorization)
+#' of the RKorAPClient Readme on GitHub.
+#'
+#' To use authorization based on an access token
+#' in subsequent queries, initialize your KorAP connection with:
+#'
+#' ```
+#' kco <- new("KorAPConnection", accessToken="<access token>")
+#' ```
+#'
#' In order to make the API
#' token persistent for the currently used `KorAPUrl` (you can have one
-#' token per KorAPUrl / KorAP server instance), use
-#' `persistAccessToken(kco)`. This will store it in your keyring using the
+#' token per KorAPUrl / KorAP server instance), use:
+#'
+#' ```
+#' persistAccessToken(kco)
+#' ```
+#'
+#' This will store it in your keyring using the
#' [keyring()] package. Subsequent new("KorAPConnection") calls will
#' then automatically retrieve the token from your keying. To stop using a
#' persisted token, call `clearAccessToken(kco)`. Please note that for
@@ -46,6 +62,7 @@
#' you experience problems or unexpected results, please try `kco <-
#' new("KorAPConnection", cache=FALSE)` or use
#' [clearCache()] to clear the cache completely.
+#'
#' @param userAgent user agent string.
#' @param timeout tineout in seconds for API requests (this does not influence server internal timeouts).
#' @param verbose logical that decides whether following operations will default to
diff --git a/R/KorAPQuery.R b/R/KorAPQuery.R
index eb2afbd..9114c83 100644
--- a/R/KorAPQuery.R
+++ b/R/KorAPQuery.R
@@ -87,7 +87,12 @@
#' @param query string that contains the corpus query. The query language depends on the `ql` parameter. Either `query` must be provided or `KorAPUrl`.
#' @param vc string describing the virtual corpus in which the query should be performed. An empty string (default) means the whole corpus, as far as it is license-wise accessible.
#' @param KorAPUrl instead of providing the query and vc string parameters, you can also simply copy a KorAP query URL from your browser and use it here (and in `KorAPConnection`) to provide all necessary information for the query.
-#' @param metadataOnly logical that determines whether queries should return only metadata without any snippets. This can also be useful to prevent access rewrites. Note that the default value is TRUE, unless the connection is authorized (currently not possible).
+#' @param metadataOnly logical that determines whether queries should return only metadata without any snippets. This can also be useful to prevent access rewrites. Note that the default value is TRUE.
+#' If you want your corpus queries to return not only metadata, but also KWICS, you need to authorize
+#' your RKorAPClient application as explained in the
+#' [authorization section](https://github.com/KorAP/RKorAPClient#authorization)
+#' of the RKorAPClient Readme on GitHub and set the `metadataOnly` parameter to
+#' `FALSE`.
#' @param ql string to choose the query language (see [section on Query Parameters](https://github.com/KorAP/Kustvakt/wiki/Service:-Search-GET#user-content-parameters) in the Kustvakt-Wiki for possible values.
#' @param fields (meta)data fields that will be fetched for every match.
#' @param accessRewriteFatal abort if query or given vc had to be rewritten due to insufficient rights (not yet implemented).
diff --git a/Readme.md b/Readme.md
index 53a14a0..5b9fd07 100644
--- a/Readme.md
+++ b/Readme.md
@@ -86,30 +86,66 @@
|[in Marsch setzen](https://korap.ids-mannheim.de/?q=Marsch%20focus%28in%20%5btt%2fp%3dNN%5d%20%7b%5btt%2fl%3dsetzen%5d%7d%29&ql=poliqarp) | 6.87| 9.27| 22041.63|
|[in Klammern setzen](https://korap.ids-mannheim.de/?q=Klammern%20focus%28in%20%5btt%2fp%3dNN%5d%20%7b%5btt%2fl%3dsetzen%5d%7d%29&ql=poliqarp) | 6.55| 10.08| 15643.27|
-### Access restricted KWICs
-In order to perform the collocation analysis and other textual queries also on corpus parts where KWIC access requires a login, you need to authorize your application via an access token.
+### <a name="authorization"></a> Authorizing RKorAPClient applications to access restricted KWICs from copyrighted texts
-In the case of DeReKo, you cat get an access token from [KorAP OAuth settings here](https://korap.ids-mannheim.de/settings/oauth#page-top). There login, register a new client application, create a new token, copy it and in R use it via the `accessToken` parameter:
+In order to perform collocation analysis and other textual queries on corpus parts for which KWIC access requires a login, you need to authorize your application with an access token.
-```
-kco <- new("KorAPConnection", accessToken="<access token>")
-```
+In the case of DeReKo, this can be done in two different ways.
-You can also persist the access token for subsequent sessions with the `persistAccessToken` function:
-```
-persistAccessToken(kco)
-```
+#### The old way: Authorize your RKorAPClient application manually
+
+1. Log in into the [KorAP DeReKo instance](https://korap.ids-mannheim.de/)
+1. Open the [KorAP OAuth settings](https://korap.ids-mannheim.de/settings/oauth#page-top)
+1. If you have not yet registered a client application, or not the desired one, register one (it is sufficient to fill in the marked fields).
+1. Click the intended client application name.
+1. If you do not have any access tokens yet, click on the "Issue new token" button.
+1. Copy one of your access tokens to you clipboard by clicking on the copy symbol ⎘ behind it.
+1. In R/RStudio, paste the token into you KorAPConnection initialization, overwriting `<access token>` in the following example:
+ ```R
+ kco <- new("KorAPConnection", accessToken="<access token>")
+ ```
The whole process is shown in this video:
https://user-images.githubusercontent.com/11092081/142769056-b389649b-eac4-435f-ac6d-1715474a5605.mp4
-In order to use the access token for plain corpus queries, i.e. to make `corpusQuery` return KWIC snippets, the `metadataOnly` parameter must be set to `FALSE`, for instance:
+#### The new way (since March 2023)[^1]: Authorize your RKorAPClient application via the usual OAuth browser flow
+
+1. Follow steps 1-4 of the old way shown above.
+2. Click on the copy symbol ⎘ behind the ID of your client application.
+3. Paste your clipboard content overwriting `<application ID>` in the following example code:
+ ```R
+ library(httr)
+ library(httpuv)
+ korap_app <- oauth_app("korap-client", key = "<application ID>", secret = NULL)
+ korap_endpoint <- oauth_endpoint(NULL,
+ "settings/oauth/authorize",
+ "api/v1.0/oauth2/token",
+ base_url = "https://korap.ids-mannheim.de")
+ token_bundle = oauth2.0_token(korap_endpoint, korap_app, scope = "search match_info", cache = FALSE)
+
+ kco <- new("KorAPConnection", accessToken = token_bundle[["credentials"]][["access_token"]])
+ ```
+[^1]: This new method has been made possible purely on the server side, so that it will also work with older versions of RKorAPClient.
+
+#### Storing and testing your authorized access
+
+You can also persist the access token for subsequent sessions with the `persistAccessToken` function:
```R
-new("KorAPConnection") %>% corpusQuery("Ameisenplage", metadataOnly = FALSE) %>% fetchAll()
+persistAccessToken(kco)
```
+Afterwards a simple `kco <- new("KorAPConnection")` will retrieve the stored token.
+
+To use the access token for simple corpus queries, i.e. to make `corpusQuery` return KWIC snippets, the `metadataOnly` parameter must be set to `FALSE`, for example:
+
+```R
+corpusQuery(kco, "Ameisenplage", metadataOnly = FALSE) %>% fetchAll()
+```
+
+should return KWIC snippets, if you have authorized your application successfully.
+
## Demos
More elaborate R scripts demonstrating the use of the package can be found in the [demo](demo) folder.
diff --git a/man/KorAPConnection-class.Rd b/man/KorAPConnection-class.Rd
index ad64dc9..0b14316 100644
--- a/man/KorAPConnection-class.Rd
+++ b/man/KorAPConnection-class.Rd
@@ -54,13 +54,27 @@
\item{apiUrl}{URL of the KorAP web service.}
-\item{accessToken}{OAuth2 access token. To use authorization based on an access token
-in subsequent queries, initialize your KorAP connection with
-\code{kco <- new("KorAPConnection", accessToken="<access token>")}.
+\item{accessToken}{OAuth2 access token. For queries on corpus parts with restricted
+access (e.g. textual queries on IPR protected data), you need to authorize
+your application with an access token.
+How to obtain an access token for the DeReKo KorAP instance is explained in the
+\href{https://github.com/KorAP/RKorAPClient#authorization}{authorization section}
+of the RKorAPClient Readme on GitHub.
+
+To use authorization based on an access token
+in subsequent queries, initialize your KorAP connection with:
+
+\if{html}{\out{<div class="sourceCode">}}\preformatted{kco <- new("KorAPConnection", accessToken="<access token>")
+}\if{html}{\out{</div>}}
+
In order to make the API
token persistent for the currently used \code{KorAPUrl} (you can have one
-token per KorAPUrl / KorAP server instance), use
-\code{persistAccessToken(kco)}. This will store it in your keyring using the
+token per KorAPUrl / KorAP server instance), use:
+
+\if{html}{\out{<div class="sourceCode">}}\preformatted{persistAccessToken(kco)
+}\if{html}{\out{</div>}}
+
+This will store it in your keyring using the
\code{\link[=keyring]{keyring()}} package. Subsequent new("KorAPConnection") calls will
then automatically retrieve the token from your keying. To stop using a
persisted token, call \code{clearAccessToken(kco)}. Please note that for
diff --git a/man/KorAPQuery-class.Rd b/man/KorAPQuery-class.Rd
index 1f0bca3..97000de 100644
--- a/man/KorAPQuery-class.Rd
+++ b/man/KorAPQuery-class.Rd
@@ -123,7 +123,12 @@
\item{KorAPUrl}{instead of providing the query and vc string parameters, you can also simply copy a KorAP query URL from your browser and use it here (and in \code{KorAPConnection}) to provide all necessary information for the query.}
-\item{metadataOnly}{logical that determines whether queries should return only metadata without any snippets. This can also be useful to prevent access rewrites. Note that the default value is TRUE, unless the connection is authorized (currently not possible).}
+\item{metadataOnly}{logical that determines whether queries should return only metadata without any snippets. This can also be useful to prevent access rewrites. Note that the default value is TRUE.
+If you want your corpus queries to return not only metadata, but also KWICS, you need to authorize
+your RKorAPClient application as explained in the
+\href{https://github.com/KorAP/RKorAPClient#authorization}{authorization section}
+of the RKorAPClient Readme on GitHub and set the \code{metadataOnly} parameter to
+\code{FALSE}.}
\item{ql}{string to choose the query language (see \href{https://github.com/KorAP/Kustvakt/wiki/Service:-Search-GET#user-content-parameters}{section on Query Parameters} in the Kustvakt-Wiki for possible values.}