.. include:: /includes.rst.txt

.. comments - headings

   # with overline, for parts
   * with overline, for chapters
   = for sections
   - for subsections
   ^ for subsubsections
   " for paragraphs
   * for H5
   + for H6

.. _edg_authentication_apis:

Accessing EDG APIs with different types of authentication
=========================================================

In this section we will demonstrate how to call EDG Web APIs using Python for three different forms of authentication supported by EDG. For it, you will require a basic understanding of `Python`_. For each example, we provide Python code to execute the EDG Web Service "exportRDFFile". For more on using the exportRDFFile via Swagger and cURL, see `Downloading an asset collection as RDF <../edg_web_service_apis/index.html#downloading-an-asset-collection-as-rdf>`_. 

.. contents::

.. _1-basic_authentication:

1. Using Basic authentication
-----------------------------

Basic authentication relies on a Base64 encoded ``Authorization`` header whose value consists of the word ``Basic`` followed by a space followed by the Base64 encoded ``name:password``. This is better suited for service-only access because the only way a user can log out is to shut down their browser. The URL with header information can be submitted with authentication information. 

Here's an example using Python to access the EDG exportRDFFile Web Service. 

.. literalinclude:: ./_code/exportRDFFile_basic_auth.py
    :linenos:
    :language: python
    :lineno-start: 1

To run the service use the following command - 

.. code-block:: text

   python exportRDFFile.py --username <username>  --host <localhost> --asset_collection <asset_collection> --format <format>

When it prompts, enter your password. For example, running on an EDG instance locally with basic authentication, e.g. username admin, use the following command: ``python exportRDFFile_basic_auth.py --username "admin" --host "localhost:8083/tbl" --asset_collection "kennedy_family" --format "turtle"``. Then when prompted type in your password. On succesfully executing the script, it should print the kennedy_family ttl to the terminal/command window. 

For secure access, web services should use HTTPS encryption.

.. _112-form_based_authentication:

2. Using Form-based authentication
----------------------------------

Access using Form-based authentication, while not recommended, is possible using cookies generated by the server. The method we give here, using the following Python script, is to request an HTTP cookie that can be used in subsequent requests. The python script expects the same arguments as for basic auth, i.e. username, host, the asset collection name and the format. The inputs for these would be the same as for basic auth, except for host, which if you are running EDG studio locally with form based authentication would be ``"http://localhost:8083/tbl"``. You enter your password again when you receive a prompt. 

1. The main function specifies the required arguments, and then proceeds to create a session to handle the cookies. Next it executes the login function using this session. 

2. The login function takes the host URL and performs an initial ``POST`` request to obtain a cookie from the server. 

3. The login script then performs a second ``POST`` request to login, now making use of the username and password as parameters.  

4. On successful login, the python script uses the session to run subsequent http request. In this example we once again call the EDG exportRDFFile web service. 

.. literalinclude:: ./_code/exportRDFFile_form_auth.py
    :linenos:
    :language: python
    :lineno-start: 1

Use the following command to execute the script  ``python exportRDFFile_basic_auth.py --username "admin" --host "http://localhost:8083/tbl" --asset_collection "kennedy_family" --format "turtle"``. Then again, type in your password. 

On successfully executing the script, it should print the kennedy_family ttl to the terminal/command window. 

For secure access, web services should use HTTPS encryption.

.. _113-oauth_based_authentication:

3. Using OAuth authentication
--------------------------------

The following piece of Python script provides a means for calling the exportRDFFile when using OAuth authentication. The code takes the following parameters; host, the asset collection name and the format. The authentication server, client id and scope could also be potentially passed in as parameters. Here, we hard code them. We also prompt the use for their client secret. Again, this could be passed as a parameter. 

The code is broken into a main function and login function. The login function prompts the user for their client secret. This is then used to generate the "access_token", which is returned by the function. 

The main function then takes the three parameters, provides hard coded auth_server_url and client_id. Here we assemble the API URL from the parameters we pass in, but you can replace this with any API URL. The code then generates the access token hourly, prompting each time for the client secret. 

On successful execution, it will write the response data to the terminal/command line. 

.. literalinclude:: ./_code/exportRDFFile_oauth_auth.py
    :linenos:
    :language: python
    :lineno-start: 1

Use the following command to execute the script  ``python exportRDFFile_oauth_auth.py --username --host "localhost:8083" --asset_collection "kennedy_family" --format "turtle"``