Add documentation on reloading certificates

parent f5e79527
...@@ -25,6 +25,33 @@ If you are working behind a proxy, use the ``proxy_host`` and ``proxy_port`` arg ...@@ -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. 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 Response contents
----------------- -----------------
Most of the client methods return a :class:`httplib.HTTPResponse` object. 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 ...@@ -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. 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. 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. 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. See :ref:`api:API` for information about the client methods used for these actions.
Markdown is supported
0%
or
You are about to add 0 people to the discussion. Proceed with caution.
Finish editing this message first!
Please register or to comment