Merge pull request #32 from Conjur-Enterprise/docs-updates

CNJR-0000: Readme authentication updates

Author: gl-johnson

.gitleaksignore

@@ -0,0 +1,5 @@
+# Ignores for test files/examples
+f01985c225aa5d9ac815cc4c0ec8cc5327e44c4f:README.md:generic-api-key:72
+925cc7ebe3df6b63b16163c4c56a404bb7bcd874:ci/test/conjur-deployment/configuration/ldap/certs/ldap-server.key.pem:private-key:1
+925cc7ebe3df6b63b16163c4c56a404bb7bcd874:ci/test/conjur-deployment/configuration/oidc/certs/oidc-server.key.pem:private-key:1
+925cc7ebe3df6b63b16163c4c56a404bb7bcd874:ci/test/conjur-deployment/ubuntu_compose.yml:generic-api-key:35

.pylintrc

@@ -32,10 +32,6 @@ persistent=yes
 # Specify a configuration file.
 #rcfile=
 
-# When enabled, pylint would attempt to guess common misconfiguration and emit
-# user-friendly hints instead of false-positive error messages.
-suggestion-mode=yes
-
 # Allow loading of arbitrary C extensions. Extensions are imported into the
 # active Python interpreter and may run arbitrary code.
 unsafe-load-any-extension=no
@@ -508,4 +504,4 @@ preferred-modules=
 
 # Exceptions that will emit a warning when being caught. Defaults to
 # "BaseException, Exception".
-overgeneral-exceptions=BaseException
+overgeneral-exceptions=builtins.BaseException

CHANGELOG.md

@@ -6,6 +6,12 @@ and this project adheres to [Semantic Versioning](http://semver.org/spec/v2.0.0.
 
 ## [Unreleased]
 
+## [0.1.8] - 2025-11-07
+
+### Changed
+- Remove `async_timeout` dependency
+- Clarify authentication methods in README.md
+
 ## [0.1.7] - 2025-10-16
 
 ### Added

README.md

@@ -59,13 +59,26 @@ pip3 install .
 
 #### Define connection parameters
 
-In order to login to Secrets Manager you need to have 5 parameters known from advance.
+In order to authenticate to Secrets Manager you need to have 5 parameters known in advance.  
+**NOTE:** We include example values in the sample code for simplicity, but credentials and secrets should **never** be hardcoded.
 
+As a host/workload:
 ```python
 from conjur_api.models import  SslVerificationMode
 
 conjur_url = "https://my_conjur.com"
-account = "my_account"
+account = "conjur"
+role_id = "host/data/my-host"
+api_key = "m3y70m29xt8ya2aa9p4z1nj0dskra4wpn2913vjb6s0ffw1j6gkp7"
+ssl_verification_mode = SslVerificationMode.TRUST_STORE
+```
+
+As a user (Only compatible with Secrets Manager Self-Hosted):
+```python
+from conjur_api.models import  SslVerificationMode
+
+conjur_url = "https://my_conjur.com"
+account = "conjur"
 username = "user1"
 password = "SomeStr@ngPassword!1"
 ssl_verification_mode = SslVerificationMode.TRUST_STORE
@@ -83,38 +96,49 @@ connection_info = ConjurConnectionInfo(conjur_url=conjur_url,account=account,cer
 
 * conjur_url - url of Secrets Manager server
 * account - the account which we want to connect to
-* cert_file - a path to Secrets Manager rootCA file. we need it if we initialize the client in `SslVerificationMode.SELF_SIGN`
+* cert_file - a path to Secrets Manager rootCA file. Required if initializing the client in `SslVerificationMode.SELF_SIGN`
   or `SslVerificationMode.CA_BUNDLE` mode
-* service_id - a service id for the Secrets Manager authenticator. Required when using the ldap authenticator (see below) but not when using the default `authn` authenticator.
+* service_id - a service id for the Secrets Manager authenticator. Required when using an authenticator besides the default
+  authn (see `Create Authentication Strategy`)
 * proxy_params - parameters for proxy connection. see `ProxyParams` class for more details - Optional
 
-#### Create credentials provider
+#### Create Credentials Provider
 
-The client uses credentials provider in order to get the connection credentials before making api command. This approach
-allow to keep the credentials in a safe location and provide it to the client on demand.
+The client uses a credentials provider in order to fetch connection credentials before making API calls. This allows credential
+storage in a safe location on the system.
 
-We provide the user with `CredentialsProviderInterface` which can be implemented the way the user see as best
-fit (`keyring` usage for example)
+We provide the user with `CredentialsProviderInterface` which can be implemented to create a custom credentials provider that
+best fits the use case (`keyring` for example)
 
-We also provide the user with a simple implementation of such provider called `SimpleCredentialsProvider`. Example of
-creating such provider + storing credentials:
+We also provide a simple implementation called `SimpleCredentialsProvider`. Example of
+creating a provider and storing credentials:
 
 ```python
 from conjur_api.models import CredentialsData
 from conjur_api.providers import SimpleCredentialsProvider
 
+# If using API key (most common)
+credentials = CredentialsData(username=role_id, api_key=api_key, machine=conjur_url)
+
+# If using username/password
 credentials = CredentialsData(username=username, password=password, machine=conjur_url)
+
 credentials_provider = SimpleCredentialsProvider()
 credentials_provider.save(credentials)
 del credentials
 ```
 
-#### Create authentication strategy
-
-The client also uses an authentication strategy in order to authenticate to Secrets Manager. This approach allows us to implement different authentication strategies
-(e.g. `authn`, `authn-ldap`, `authn-k8s`) and to keep the authentication logic separate from the client implementation.
+#### Create Authentication Strategy
 
-We provide the `AuthnAuthenticationStrategy` for the default Secrets Manager authenticator. Example use:
+The client uses an authentication strategy in order to authenticate to Secrets Manager. This approach allows us to implement
+different authentication strategies while keeping logic separate from the client implementation. Supported strategies are based
+on different Secrets Manager authenticators:
+  - authn (default)
+  - authn-ldap
+  - authn-oidc
+  - authn-jwt
+  
+We provide the `AuthnAuthenticationStrategy` for the default Secrets Manager authenticator. Example usage:
 
 ```python
 from conjur_api.providers import AuthnAuthenticationStrategy
@@ -124,7 +148,7 @@ authn_provider = AuthnAuthenticationStrategy(credentials_provider)
 
 We also provide the `LdapAuthenticationStrategy`, `OidcAuthenticationStrategy`, and `JWTAuthenticationStrategy` for the
 ldap, oidc, and jwt authenticators respectively.
-Example use:
+Example usage:
 
 ```python
 from conjur_api.providers import LdapAuthenticationStrategy, OidcAuthenticationStrategy, JWTAuthenticationStrategy
@@ -136,7 +160,7 @@ jwt_provider = JWTAuthenticationStrategy(token)
 
 When using these strategies, make sure `connection_info` has a `service_id` specified.
 
-#### Creating the client and use it
+#### Creating and using the client
 
 Now that we have created `connection_info` and `authn_provider`, we can create our client:
 
@@ -148,14 +172,14 @@ client = Client(connection_info,
                 ssl_verification_mode=ssl_verification_mode)
 ```
 
-* ssl_verification_mode = `SslVerificationMode` enum that states what is the certificate verification technique we will
-  use when making the api request
+* ssl_verification_mode = `SslVerificationMode` enum that states what is the certificate verification technique to be
+  used when making requests
 
 After creating the client we can login to Secrets Manager and start using it. Example of usage:
 
 ```python
-client.login() # login to conjur and return the api_key
-client.list() # get list of all conjur resources that the user authorize to read
+client.login() # NOTE: Only applicable for username/password authentication on Self-Hosted
+client.list() # List Secrets Manager resources the role is authorized to read
 ```
 
 ## Supported Client methods
@@ -287,7 +311,7 @@ endpoint is still subject to breaking changes in the future._
 
 #### `authenticate()`
 
-Performs an authentication with Secrets Manager, based on the authentication strategy and credentials provider there were given to the client.
+Performs an authentication with Secrets Manager, based on the authentication strategy and credentials provider that were given to the client.
 This method is not required, it will also be done implicitly and automatically when session with Secrets Manager needs to be refreshed.
 
 ## Contributing
@@ -297,7 +321,7 @@ development workflows, please see our [contributing guide](CONTRIBUTING.md).
 
 ## License
 
-Copyright (c) 2020 CyberArk Software Ltd. All rights reserved.
+Copyright (c) 2025 CyberArk Software Ltd. All rights reserved.
 
 Licensed under the Apache License, Version 2.0 (the "License"); you may not use this file except in compliance with the
 License. You may obtain a copy of the License at

conjur_api/wrappers/http_wrapper.py

@@ -15,9 +15,8 @@
 from typing import Union
 from urllib.parse import quote
 
-import async_timeout
 import urllib3
-from aiohttp import BasicAuth, ClientError, ClientResponseError, ClientSSLError, ClientSession
+from aiohttp import BasicAuth, ClientError, ClientResponseError, ClientSSLError, ClientSession, ClientTimeout
 
 from conjur_api.errors.errors import CertificateHostnameMismatchException, HttpSslError, HttpError, HttpStatusError
 from conjur_api.http.endpoints import ConjurEndpoint
@@ -171,27 +170,26 @@ async def invoke_request(http_verb: HttpVerb,
     This method preforms the actual request and catches possible SSLErrors to
     perform more user-friendly messages
     """
-    async with ClientSession() as session:
-        async with async_timeout.timeout(REQUEST_TIMEOUT_SECONDS):
-            ssl_context = __create_ssl_context(ssl_verification_metadata)
-            try:
-                async with session.request(http_verb.name,
-                                           url,
-                                           data=data,
-                                           params=query,
-                                           ssl=ssl_context,
-                                           auth=BasicAuth(*auth) if auth else None,
-                                           headers=headers,
-                                           proxy=proxy_params.proxy_url if proxy_params else None) as response:
-                    return await HttpResponse.from_client_response(response)
-
-            except ClientSSLError as ssl_error:
-                host_mismatch_message = re.search("hostname '.+' doesn't match", str(ssl_error))
-                if host_mismatch_message:
-                    raise CertificateHostnameMismatchException from ssl_error
-                raise HttpSslError(message=str(ssl_error)) from ssl_error
-            except ClientError as request_error:
-                raise HttpError() from request_error
+    async with ClientSession(timeout=ClientTimeout(total=REQUEST_TIMEOUT_SECONDS)) as session:
+        ssl_context = __create_ssl_context(ssl_verification_metadata)
+        try:
+            async with session.request(http_verb.name,
+                                        url,
+                                        data=data,
+                                        params=query,
+                                        ssl=ssl_context,
+                                        auth=BasicAuth(*auth) if auth else None,
+                                        headers=headers,
+                                        proxy=proxy_params.proxy_url if proxy_params else None) as response:
+                return await HttpResponse.from_client_response(response)
+
+        except ClientSSLError as ssl_error:
+            host_mismatch_message = re.search("hostname '.+' doesn't match", str(ssl_error))
+            if host_mismatch_message:
+                raise CertificateHostnameMismatchException from ssl_error
+            raise HttpSslError(message=str(ssl_error)) from ssl_error
+        except ClientError as request_error:
+            raise HttpError() from request_error
 
 
 def __create_ssl_context(ssl_verification_metadata: SslVerificationMetadata) -> Union[bool, ssl.SSLContext]: