Merge branch 'main' into add-repl-dockerfile

Author: mridang

.github/workflows/test.yml

@@ -35,3 +35,6 @@ jobs:
         env:
           BASE_URL: ${{ secrets.BASE_URL }}
           AUTH_TOKEN: ${{ secrets.AUTH_TOKEN }}
+          JWT_KEY: ${{ secrets.JWT_KEY }}
+          CLIENT_ID: ${{ secrets.CLIENT_ID }}
+          CLIENT_SECRET: ${{ secrets.CLIENT_SECRET }}

README.md

@@ -37,45 +37,133 @@ install dependencies.
 Install the SDK by running one of the following commands:
 
 ```bash
-composer require zitadel/client
+pip install zitadel_client
 ```
 
-### Authentication
+## Authentication Methods
 
-The SDK supports three authentication methods:
+Your SDK offers three ways to authenticate with Zitadel. Each method has its
+own benefits—choose the one that fits your situation best.
 
-1. Private Key JWT Authentication
-2. Client Credentials Grant
-3. Personal Access Tokens (PATs)
+#### 1. Private Key JWT Authentication
 
-For most service user scenarios in Zitadel, private key JWT authentication
-is the recommended choice due to its benefits in security, performance, and control.
-However, client credentials authentication might be considered in specific
-situations where simplicity and trust between servers are priorities.
+**What is it?**
+You use a JSON Web Token (JWT) that you sign with a private key stored in a
+JSON file. This process creates a secure token.
 
-For more details on these authentication methods, please refer
-to the [Zitadel documentation on authenticating service users](https://zitadel.com/docs/guides/integrate/service-users/authenticate-service-users).
+**When should you use it?**
+- **Best for production:** It offers strong security.
+- **Advanced control:** You can adjust token settings like expiration.
 
+**How do you use it?**
+1. Save your private key in a JSON file.
+2. Use the provided method to load this key and create a JWT-based
+   authenticator.
 
-### Example
+**Example:**
 
 ```python
 import zitadel_client as zitadel
+from zitadel_client.auth.web_token_authenticator import WebTokenAuthenticator
+
+base_url = "https://example.zitadel.com"
+key_file = "/path/to/jwt-key.json"
+
+authenticator = WebTokenAuthenticator.from_json(base_url, key_file)
+zitadel = zitadel.Zitadel(authenticator)
+
+try:
+    response = zitadel.users.add_human_user({
+        "username": "john.doe",
+        "profile": {"givenName": "John", "familyName": "Doe"},
+        "email": {"email": "john@doe.com"}
+    })
+    print("User created:", response)
+except Exception as e:
+    print("Error:", e)
+```
+
+#### 2. Client Credentials Grant
+
+**What is it?**
+This method uses a client ID and client secret to get a secure access token,
+which is then used to authenticate.
+
+**When should you use it?**
+- **Simple and straightforward:** Good for server-to-server communication.
+- **Trusted environments:** Use it when both servers are owned or trusted.
+
+**How do you use it?**
+1. Provide your client ID and client secret.
+2. Build the authenticator
 
-with zitadel.Zitadel("your-zitadel-base-url", 'your-valid-token') as client:
-	try:
-		response = client.users.add_human_user(
-			body=zitadel.V2AddHumanUserRequest(
-				username="john.doe",
-				profile=zitadel.V2SetHumanProfile(given_name="John", family_name="Doe"),
-				email=zitadel.V2SetHumanEmail(email="johndoe@doe.com")
-			)
-		)
-		print("User created:", response)
-	except Exception as e:
-		raise e
+**Example:**
+
+```python
+import zitadel_client as zitadel
+from zitadel_client.auth.client_credentials_authenticator import ClientCredentialsAuthenticator
+
+base_url = "https://example.zitadel.com"
+client_id = "your-client-id"
+client_secret = "your-client-secret"
+
+authenticator = ClientCredentialsAuthenticator.builder(base_url, client_id, client_secret).build()
+zitadel = zitadel.Zitadel(authenticator)
+
+try:
+    response = zitadel.users.add_human_user({
+        "username": "john.doe",
+        "profile": {"givenName": "John", "familyName": "Doe"},
+        "email": {"email": "john@doe.com"}
+    })
+    print("User created:", response)
+except Exception as e:
+    print("Error:", e)
 ```
 
+#### 3. Personal Access Tokens (PATs)
+
+**What is it?**
+A Personal Access Token (PAT) is a pre-generated token that you can use to
+authenticate without exchanging credentials every time.
+
+**When should you use it?**
+- **Easy to use:** Great for development or testing scenarios.
+- **Quick setup:** No need for dynamic token generation.
+
+**How do you use it?**
+1. Obtain a valid personal access token from your account.
+2. Create the authenticator with: `PersonalAccessTokenAuthenticator`
+
+**Example:**
+
+```python
+import zitadel_client as zitadel
+from zitadel_client.auth.personal_access_token_authenticator import PersonalAccessTokenAuthenticator
+
+base_url = "https://example.zitadel.com"
+valid_token = "your-valid-token"
+
+authenticator = PersonalAccessTokenAuthenticator(base_url, valid_token)
+zitadel = zitadel.Zitadel(authenticator)
+
+try:
+    response = zitadel.users.add_human_user({
+        "username": "john.doe",
+        "profile": {"givenName": "John", "familyName": "Doe"},
+        "email": {"email": "john@doe.com"}
+    })
+    print("User created:", response)
+except Exception as e:
+    print("Error:", e)
+```
+
+---
+
+Choose the authentication method that best suits your needs based on your
+environment and security requirements. For more details, please refer to the
+[Zitadel documentation on authenticating service users](https://zitadel.com/docs/guides/integrate/service-users/authenticate-service-users).
+
 ### Debugging
 The SDK supports debug logging, which can be enabled for troubleshooting
 and debugging purposes. You can enable debug logging by setting the `debug`

spec/conftest.py

@@ -1,6 +1,7 @@
 import pytest
 from dotenv import load_dotenv
 
+
 @pytest.fixture(scope="session", autouse=True)
 def load_env():
     """Load the .env file for the entire test session."""

spec/sdk_test_using_client_credentials_authentication_spec.py

@@ -0,0 +1,74 @@
+import os
+import uuid
+
+import pytest
+
+import zitadel_client as zitadel
+from zitadel_client.auth.client_credentials_authenticator import ClientCredentialsAuthenticator
+
+
+@pytest.fixture
+def client_id():
+  """Fixture to return a valid personal access token."""
+  return os.getenv("CLIENT_ID")
+
+
+@pytest.fixture
+def client_secret():
+  """Fixture to return a valid personal access token."""
+  return os.getenv("CLIENT_SECRET")
+
+
+@pytest.fixture
+def base_url():
+  """Fixture to return the base URL."""
+  return os.getenv("BASE_URL")
+
+
+@pytest.fixture
+def user_id(client_id, client_secret, base_url):
+  """Fixture to create a user and return their ID."""
+  with zitadel.Zitadel(ClientCredentialsAuthenticator.builder(base_url, client_id, client_secret).build()) as client:
+    try:
+      response = client.users.add_human_user(
+        body=zitadel.models.V2AddHumanUserRequest(
+          username=uuid.uuid4().hex,
+          profile=zitadel.models.V2SetHumanProfile(given_name="John", family_name="Doe"),
+          email=zitadel.models.V2SetHumanEmail(email=f"johndoe{uuid.uuid4().hex}@caos.ag")
+        )
+      )
+      print("User created:", response)
+      return response.user_id
+    except Exception as e:
+      pytest.fail(f"Exception while creating user: {e}")
+
+
+def test_should_deactivate_and_reactivate_user_with_valid_token(user_id, client_id, client_secret, base_url):
+  """Test to (de)activate the user with a valid token."""
+  with zitadel.Zitadel(ClientCredentialsAuthenticator.builder(base_url, client_id, client_secret).build()) as client:
+    try:
+      deactivate_response = client.users.deactivate_user(user_id=user_id)
+      print("User deactivated:", deactivate_response)
+
+      reactivate_response = client.users.reactivate_user(user_id=user_id)
+      print("User reactivated:", reactivate_response)
+      # Adjust based on actual response format
+      # assert reactivate_response["status"] == "success"
+    except Exception as e:
+      pytest.fail(f"Exception when calling deactivate_user or reactivate_user with valid token: {e}")
+
+
+def test_should_not_deactivate_or_reactivate_user_with_invalid_token(user_id, base_url):
+  """Test to attempt (de)activating the user with an invalid token."""
+  with zitadel.Zitadel(ClientCredentialsAuthenticator.builder(base_url, "id", "secret").build()) as client:
+    try:
+      client.users.deactivate_user(user_id=user_id)
+      pytest.fail("Expected exception when deactivating user with invalid token, but got response.")
+    except Exception as e:
+      print("Caught expected UnauthorizedException:", e)
+
+    try:
+      client.users.reactivate_user(user_id=user_id)
+      pytest.fail("Expected exception when reactivating user with invalid token, but got response.")
+    except Exception as e:
+      print("Caught expected UnauthorizedException:", e)

spec/sdk_test_using_personal_access_token_authentication_spec.py

@@ -1,25 +1,31 @@
-import pytest
-import uuid
 import os
+import uuid
+
+import pytest
+
 import zitadel_client as zitadel
 from zitadel_client.auth.personal_access_token_authenticator import PersonalAccessTokenAuthenticator
 from zitadel_client.exceptions import UnauthorizedException
 
+
 @pytest.fixture
 def valid_token():
     """Fixture to return a valid personal access token."""
     return os.getenv("AUTH_TOKEN")
 
+
 @pytest.fixture
 def invalid_token():
     """Fixture to return an invalid token."""
     return "whoops"
 
+
 @pytest.fixture
 def base_url():
     """Fixture to return the base URL."""
     return os.getenv("BASE_URL")
 
+
 @pytest.fixture
 def user_id(valid_token, base_url):
     """Fixture to create a user and return their ID."""
@@ -37,6 +43,7 @@ def user_id(valid_token, base_url):
         except Exception as e:
             pytest.fail(f"Exception while creating user: {e}")
 
+
 def test_should_deactivate_and_reactivate_user_with_valid_token(user_id, valid_token, base_url):
     """Test to (de)activate the user with a valid token."""
     with zitadel.Zitadel(PersonalAccessTokenAuthenticator(base_url, valid_token)) as client:
@@ -51,6 +58,7 @@ def test_should_deactivate_and_reactivate_user_with_valid_token(user_id, valid_t
         except Exception as e:
             pytest.fail(f"Exception when calling deactivate_user or reactivate_user with valid token: {e}")
 
+
 def test_should_not_deactivate_or_reactivate_user_with_invalid_token(user_id, invalid_token, base_url):
     """Test to attempt (de)activating the user with an invalid token."""
     with zitadel.Zitadel(PersonalAccessTokenAuthenticator(base_url, invalid_token)) as client:

spec/sdk_test_using_web_token_authentication_spec.py

@@ -0,0 +1,57 @@
+import os
+import tempfile
+import uuid
+
+import pytest
+
+import zitadel_client as zitadel
+from zitadel_client.auth.web_token_authenticator import WebTokenAuthenticator
+
+
+@pytest.fixture
+def key_file():
+  jwt_key = os.getenv("JWT_KEY")
+  if jwt_key is None:
+    pytest.fail("JWT_KEY is not set in the environment")
+  with tempfile.NamedTemporaryFile(delete=False, mode="w") as tf:
+    tf.write(jwt_key)
+    return tf.name
+
+
+@pytest.fixture
+def base_url():
+  """Fixture to return the base URL."""
+  return os.getenv("BASE_URL")
+
+
+@pytest.fixture
+def user_id(key_file, base_url):
+  """Fixture to create a user and return their ID."""
+  with zitadel.Zitadel(WebTokenAuthenticator.from_json(base_url, key_file)) as client:
+    try:
+      response = client.users.add_human_user(
+        body=zitadel.models.V2AddHumanUserRequest(
+          username=uuid.uuid4().hex,
+          profile=zitadel.models.V2SetHumanProfile(given_name="John", family_name="Doe"),
+          email=zitadel.models.V2SetHumanEmail(email=f"johndoe{uuid.uuid4().hex}@caos.ag")
+        )
+      )
+      print("User created:", response)
+      return response.user_id
+    except Exception as e:
+      pytest.fail(f"Exception while creating user: {e}")
+
+
+def test_should_deactivate_and_reactivate_user_with_valid_token(user_id, key_file, base_url):
+  """Test to (de)activate the user with a valid token."""
+  with zitadel.Zitadel(WebTokenAuthenticator.from_json(base_url, key_file)) as client:
+    try:
+      deactivate_response = client.users.deactivate_user(user_id=user_id)
+      print("User deactivated:", deactivate_response)
+
+      reactivate_response = client.users.reactivate_user(user_id=user_id)
+      print("User reactivated:", reactivate_response)
+      # Adjust based on actual response format
+      # assert reactivate_response["status"] == "success"
+    except Exception as e:
+      pytest.fail(f"Exception when calling deactivate_user or reactivate_user with valid token: {e}")