From 05974c377c6de1a03e490d85d2891e1222066d09 Mon Sep 17 00:00:00 2001 From: Jared Dominguez Date: Thu, 22 Dec 2016 16:19:10 -0800 Subject: [PATCH 1/5] Add analytics script --- docs/_includes/analytics.html | 7 +++++++ docs/_includes/head.html | 2 ++ 2 files changed, 9 insertions(+) create mode 100644 docs/_includes/analytics.html diff --git a/docs/_includes/analytics.html b/docs/_includes/analytics.html new file mode 100644 index 000000000..0cdbad25d --- /dev/null +++ b/docs/_includes/analytics.html @@ -0,0 +1,7 @@ + + + diff --git a/docs/_includes/head.html b/docs/_includes/head.html index 80ae0323a..e4d432e12 100644 --- a/docs/_includes/head.html +++ b/docs/_includes/head.html @@ -13,3 +13,5 @@ + +{% if jekyll.environment == "production" %}{% include analytics.html %}{% endif %} From a8688e1cd3d2205a11fb5c2cce61f86088b0858f Mon Sep 17 00:00:00 2001 From: Lalith Vipulananthan Date: Thu, 12 Jan 2017 14:21:48 +0900 Subject: [PATCH 2/5] First draft of doc update --- docs/docs/sign-in-out.md | 23 +++++++++++++++++++++++ 1 file changed, 23 insertions(+) diff --git a/docs/docs/sign-in-out.md b/docs/docs/sign-in-out.md index f619aaeab..358fdd935 100644 --- a/docs/docs/sign-in-out.md +++ b/docs/docs/sign-in-out.md @@ -37,3 +37,26 @@ with server.auth.sign_in(tableau_auth): ``` The TSC library signs you out of Tableau Server when you exit out of the `with` block. + +If a self-signed certificate is used, certificate verification can be disabled using ```add_http_options```: + +```py +import tableauserverclient as TSC + +tableau_auth = TSC.TableauAuth('USERNAME', 'PASSWORD') +server = TSC.Server('http://SERVER_URL') +server.add_http_options({'verify': False}) +``` + +However, each subsequent REST API call will print an ```InsecureRequestWarning```: +``` +C:\Program Files (x86)\Python35-32\lib\site-packages\requests\packages\urllib3\connectionpool.py:838: InsecureRequestWarning: Unverified HTTPS request is being made. Adding certificate verification is strongly advised. See: https://urllib3.readthedocs.io/en/latest/security.html +InsecureRequestWarning) +``` + +These warnings can be disabled with the following line: +```py +requests.packages.urllib3.disable_warnings(InsecureRequestWa‌​rning) +``` + +Instead of disabling warnings or certificate verification, we recommend using a Certificate Authority (CA) signed certificate. [Let's Encrypt](https://letsencrypt.org/) is a free, automated, and open Certificate Authority that can be used, although please note that no official Windows client currently exists. From ada4658688336a2108957d0cde9c8ea948d33e26 Mon Sep 17 00:00:00 2001 From: Lalith Vipulananthan Date: Thu, 12 Jan 2017 15:35:39 +0900 Subject: [PATCH 3/5] Second draft of doc update --- docs/docs/sign-in-out.md | 38 ++++++++++++++++++++------------------ 1 file changed, 20 insertions(+), 18 deletions(-) diff --git a/docs/docs/sign-in-out.md b/docs/docs/sign-in-out.md index 358fdd935..66e28a6e5 100644 --- a/docs/docs/sign-in-out.md +++ b/docs/docs/sign-in-out.md @@ -2,8 +2,21 @@ title: Sign In and Out layout: docs --- +## Signing in and out +To sign in and out of Tableau Server, simply call `Auth.sign_in` as follows: +```py +import tableauserverclient as TSC + +tableau_auth = TSC.TableauAuth('USERNAME', 'PASSWORD') +server = TSC.Server('http://SERVER_URL') -To sign in and out of Tableau Server, call the `Auth.sign_in` and `Auth.sign_out` functions like so: +with server.auth.sign_in(tableau_auth): + # Do awesome things here! + +# The Auth context manager will automatically call 'Auth.sign_out' on exiting the with block +``` + +Alternatively, call both `Auth.sign_in` and `Auth.sign_out` functions explicitly like so: ```py import tableauserverclient as TSC @@ -23,22 +36,8 @@ server.auth.sign_out() limited by the maximum session length (of four hours) on Tableau Server. - -Alternatively, for short programs, consider using a `with` block: - -```py -import tableauserverclient as TSC - -tableau_auth = TSC.TableauAuth('USERNAME', 'PASSWORD') -server = TSC.Server('http://SERVER_URL') - -with server.auth.sign_in(tableau_auth): - # Do awesome things here! -``` - -The TSC library signs you out of Tableau Server when you exit out of the `with` block. - -If a self-signed certificate is used, certificate verification can be disabled using ```add_http_options```: +### Disabling certificate verification and warnings +If a self-signed certificate is used, certificate verification can be disabled with ```add_http_options```: ```py import tableauserverclient as TSC @@ -59,4 +58,7 @@ These warnings can be disabled with the following line: requests.packages.urllib3.disable_warnings(InsecureRequestWa‌​rning) ``` -Instead of disabling warnings or certificate verification, we recommend using a Certificate Authority (CA) signed certificate. [Let's Encrypt](https://letsencrypt.org/) is a free, automated, and open Certificate Authority that can be used, although please note that no official Windows client currently exists. +### A better way to avoid certificate warnings +Instead of disabling warnings or certificate verification when using self-signed certificates, we recommend using a Certificate Authority (CA) signed certificate. + +In addition to standard Certificate Authorities, [Let's Encrypt](https://letsencrypt.org/) is an automated and open Certificate Authority that can be used for absolutely free. Please note that no official Windows client currently exists, and so certificates must be signed using a Linux machine or using a third-party Windows client. From 8cc157d2f44a93be05c293ef7e59b2c51bbc332f Mon Sep 17 00:00:00 2001 From: Lalith Vipulananthan Date: Thu, 12 Jan 2017 16:18:21 +0900 Subject: [PATCH 4/5] Updated following Github discussion --- docs/docs/sign-in-out.md | 13 +++++++++---- 1 file changed, 9 insertions(+), 4 deletions(-) diff --git a/docs/docs/sign-in-out.md b/docs/docs/sign-in-out.md index 66e28a6e5..f3742aaea 100644 --- a/docs/docs/sign-in-out.md +++ b/docs/docs/sign-in-out.md @@ -53,12 +53,17 @@ C:\Program Files (x86)\Python35-32\lib\site-packages\requests\packages\urllib3\c InsecureRequestWarning) ``` -These warnings can be disabled with the following line: +These warnings can be disabled by adding the following lines to your script: ```py -requests.packages.urllib3.disable_warnings(InsecureRequestWa‌​rning) +import requests +from requests.packages.urllib3.exceptions import InsecureRequestWarning +requests.packages.urllib3.disable_warnings(InsecureRequestWarning) ``` ### A better way to avoid certificate warnings -Instead of disabling warnings or certificate verification when using self-signed certificates, we recommend using a Certificate Authority (CA) signed certificate. +Instead of disabling warnings or certificate verification to avoid issues with self-signed certificates, the best practice is to use a certificate signed by a Certificate Authority. -In addition to standard Certificate Authorities, [Let's Encrypt](https://letsencrypt.org/) is an automated and open Certificate Authority that can be used for absolutely free. Please note that no official Windows client currently exists, and so certificates must be signed using a Linux machine or using a third-party Windows client. +If you have the ability to do so, we recommend the following Certificate Authorities: +* [GlobalSign](https://www.globalsign.com/en/) +* [Let's Encrypt](https://letsencrypt.org/) - a free, automated, and open Certificate Authority +* [SSL.com](https://www.ssl.com/) From b9d322fb86b863ddd33fb98997ef701f5e321bb0 Mon Sep 17 00:00:00 2001 From: Lalith Vipulananthan Date: Thu, 12 Jan 2017 17:40:41 +0900 Subject: [PATCH 5/5] Second revision based on discussion --- docs/docs/sign-in-out.md | 25 +++++++++++++------------ 1 file changed, 13 insertions(+), 12 deletions(-) diff --git a/docs/docs/sign-in-out.md b/docs/docs/sign-in-out.md index f3742aaea..77cb78108 100644 --- a/docs/docs/sign-in-out.md +++ b/docs/docs/sign-in-out.md @@ -3,20 +3,22 @@ title: Sign In and Out layout: docs --- ## Signing in and out -To sign in and out of Tableau Server, simply call `Auth.sign_in` as follows: +To sign in and out of Tableau Server, call the `Auth.sign_in` and `Auth.sign_out` functions like so: + ```py import tableauserverclient as TSC tableau_auth = TSC.TableauAuth('USERNAME', 'PASSWORD') server = TSC.Server('http://SERVER_URL') -with server.auth.sign_in(tableau_auth): - # Do awesome things here! +server.auth.sign_in(tableau_auth) -# The Auth context manager will automatically call 'Auth.sign_out' on exiting the with block +# Do awesome things here! + +server.auth.sign_out() ``` -Alternatively, call both `Auth.sign_in` and `Auth.sign_out` functions explicitly like so: +Alternatively, for short programs, consider using a `with` block: ```py import tableauserverclient as TSC @@ -24,11 +26,10 @@ import tableauserverclient as TSC tableau_auth = TSC.TableauAuth('USERNAME', 'PASSWORD') server = TSC.Server('http://SERVER_URL') -server.auth.sign_in(tableau_auth) - -# Do awesome things here! +with server.auth.sign_in(tableau_auth): + # Do awesome things here! -server.auth.sign_out() +# No need to call auth.sign_out() as the Auth context manager will handle that on exiting the with block ```
@@ -37,7 +38,7 @@ server.auth.sign_out()
### Disabling certificate verification and warnings -If a self-signed certificate is used, certificate verification can be disabled with ```add_http_options```: +Certain environments may throw errors related to SSL configuration, such as self-signed certificates or expired certificates. These errors can be avoided by disabling certificate verification with ```add_http_options```: ```py import tableauserverclient as TSC @@ -49,7 +50,7 @@ server.add_http_options({'verify': False}) However, each subsequent REST API call will print an ```InsecureRequestWarning```: ``` -C:\Program Files (x86)\Python35-32\lib\site-packages\requests\packages\urllib3\connectionpool.py:838: InsecureRequestWarning: Unverified HTTPS request is being made. Adding certificate verification is strongly advised. See: https://urllib3.readthedocs.io/en/latest/security.html +InsecureRequestWarning: Unverified HTTPS request is being made. Adding certificate verification is strongly advised. See: https://urllib3.readthedocs.io/en/latest/security.html InsecureRequestWarning) ``` @@ -61,7 +62,7 @@ requests.packages.urllib3.disable_warnings(InsecureRequestWarning) ``` ### A better way to avoid certificate warnings -Instead of disabling warnings or certificate verification to avoid issues with self-signed certificates, the best practice is to use a certificate signed by a Certificate Authority. +Instead of disabling warnings and certificate verification to workaround issues with untrusted certificates, the best practice is to use a certificate signed by a Certificate Authority. If you have the ability to do so, we recommend the following Certificate Authorities: * [GlobalSign](https://www.globalsign.com/en/)