From 7c3e3daeed0bf0d6f74aa1eab6e7d69ac07dd1ab Mon Sep 17 00:00:00 2001 From: Tanner Prestegard Date: Wed, 17 Jul 2019 08:42:43 -0500 Subject: [PATCH] Add documentation on reloading certificates --- docs/source/user_guide.rst | 31 +++++++++++++++++++++++++++++-- 1 file changed, 29 insertions(+), 2 deletions(-) diff --git a/docs/source/user_guide.rst b/docs/source/user_guide.rst index df7b183..095d7fb 100644 --- a/docs/source/user_guide.rst +++ b/docs/source/user_guide.rst @@ -25,6 +25,33 @@ If you are working behind a proxy, use the ``proxy_host`` and ``proxy_port`` arg More information about the client class and the options which can be provided to the constructor is covered in detail on the :ref:`api:API` page. +Credentials +----------- +Credentials are not required, but users who possess them will likely want to authenticate in order to gain full access to the GraceDB server. + + +X.509 certificates +~~~~~~~~~~~~~~~~~~ +LIGO/Virgo users can provide an X.509 certificate to the client for authenticating to the GraceDB server. +This can be a proxy certificate which is generated by ``ligo-proxy-init``, another certificate which has been registered with the LIGO auth system, or a robot certificate. +There are multiple methods for making these credentials available to the client class, detailed in the documentation for :py:class:`ligo.gracedb.rest.GraceDb`. + +These certificates may expire after some period of time and need to be renewed. +If you have long-running jobs where the lifetime of a client may exceed that of your certificate, +use the ``reload_certificate`` argument (and optionally, the ``reload_buffer`` argument) when instantiating a client object. +On each request, the client will check whether your certificate has expired; if it has, the client will attempt to reload the certificate before sending the request to the server. + +**NOTE:** the client requires that your renewed certificate is in the same location as the old one. +Users may want to set up a cron job to facilitate auto-renewal of their certificate. + + +Passwords +~~~~~~~~~ +Password-based authentication to limited portions of the GraceDB API has historically been available to partner astronomers who have an MOU with LIGO/Virgo. +The documentation for :py:class:`ligo.gracedb.rest.GraceDb` details how to provide these credentials to the client. +This authentication mechanism may be phased out in the future. + + Response contents ----------------- Most of the client methods return a :class:`httplib.HTTPResponse` object. @@ -207,8 +234,8 @@ There are a few tags which are used for exposing information (``lvem``, ``public Special permissions are required to apply or remove these tags. -Other information ------------------ +Other methods +------------- Additional methods are provided for managing signoffs, uploading EM observation data, and more. These are not covered in detail here because they are rather specialized options. See :ref:`api:API` for information about the client methods used for these actions. -- 2.26.2