Usage

Instantiate the client with the FASJSON URL you want to use:

>>> from fasjson_client import Client
>>> c = Client('http://fasjson.example.com')
>>> c.whoami().result
{'dn': 'uid=admin,cn=users,cn=accounts,dc=example,dc=test', 'username': 'admin', 'service': None, 'uri': 'http://fasjson.example.test/fasjson/v1/users/admin/'}

Authentication

Authentication is done with Kerberos. If you want to explicitely specify a principal to authenticate as, use the principal constructor argument:

c = Client('http://fasjson.example.com', principal='admin@EXAMPLE.TEST')

Configuring an application for Kerberos authentication

Users authenticate via kinit, applications authenticate via keytabs. It is highly recommended to use gssproxy in order to keep your keytabs secure.

  • First, install gssproxy with dnf install gssproxy

  • Create the service that you want to authenticate as in IPA: ipa service-add SERVICE/host-fqdn (for example ipa service-add HTTP/server.example.com)

  • Get the keytab for that service and store it in gssproxy’s directory: ipa-getkeytab -p SERVICE/host-fqdn -k /var/lib/gssproxy/service.keytab (for example ipa-getkeytab -p HTTP/server.example.com -k /var/lib/gssproxy/httpd.keytab)

  • Add a configuration file for your service in gssproxy’s configuration directory:

    # /etc/gssproxy/50-servicename.conf

[service/servicename]
  mechs = krb5
  cred_store = keytab:/var/lib/gssproxy/service.keytab
  cred_store = client_keytab:/var/lib/gssproxy/service.keytab
  allow_constrained_delegation = true
  allow_client_ccache_sync = true
  cred_usage = both
  euid = user_the_service_runs_as

For example:

# /etc/gssproxy/80-httpd.conf

[service/httpd]
  mechs = krb5
  cred_store = keytab:/var/lib/gssproxy/httpd.keytab
  cred_store = client_keytab:/var/lib/gssproxy/httpd.keytab
  allow_constrained_delegation = true
  allow_client_ccache_sync = true
  cred_usage = both
  euid = apache

  • Restart gssproxy with systemctl restart gssproxy

  • Configure the service to run with the GSS_USE_PROXY environment variable set. Services started by systemd can be configured with a service configuration file, for example with the httpd service:

    # /etc/systemd/system/httpd.service.d/gssproxy.conf
# /usr/lib/systemd/system/httpd.service.d/gssproxy.conf

[Service]
Environment=KRB5CCNAME=/tmp/krb5cc-httpd
Environment=GSS_USE_PROXY=yes

Your service should now be able to authenticate with Kerberos

Pagination

Some operations can be paginated:

>>> from fasjson_client import Client
>>> c = Client('http://fasjson.example.com')
>>> response = c.list_users(page_size=2)
>>> response.result
[{'username': 'user1', [...]}, {'username': 'user2', [...]}]

The pagination data is available in the page property:

>>> response.page
{'total_results': 52, 'page_size': 2, 'page_number': 1, 'total_pages': 26}

Next and previous pages are available with the next_page() and prev_page() methods, which return the same class of objects:

>>> response.next_page().result
[{'username': 'user3', [...]}, {'username': 'user4', [...]}]

Selecting attributes

You can select which attributes you want to get from the server using the X-Fields header. The header is given as a list of attribute names:

>>> from fasjson_client import Client
>>> c = Client('http://fasjson.example.com')
>>> response = c.list_users(
...     page_size=1,
...     _request_options={
...         "headers": {"X-Fields": ["username", "emails"]}
...     }
... )
>>> response.result
[{'username': 'user1', 'emails': ['user1@example.com']}]

Command line

This package also provides a command-line client to do some operations. Install the dependencies with poetry install -E cli and run fasjson-client --help to see which operations are available.