diff --git a/docs/docs/examples/login/go.md b/docs/docs/examples/login/go.md index d78b41f77f..ae24148952 100644 --- a/docs/docs/examples/login/go.md +++ b/docs/docs/examples/login/go.md @@ -3,12 +3,16 @@ title: ZITADEL with Go sidebar_label: Go --- -This integration guide demonstrates the recommended way to incorporate ZITADEL into your Go web application. +This integration guide demonstrates the recommended way to incorporate ZITADEL into your Go web application. It explains how to enable user login in your application and how to fetch data from the user info endpoint. +> ℹ️ These examples and guides are based on our official [Go SDK](https://github.com/zitadel/zitadel-go). +> +> The SDK is a convenient wrapper around our low-level [OIDC library](https://github.com/zitadel/oidc). For most use cases, using the helpers provided in our [Go SDK](https://github.com/zitadel/zitadel-go) is the recommended approach for implementing authentication. + By the end of this guide, your application will have login functionality and will be able to access the current user's profile. -> This documentation references our [example](https://github.com/zitadel/zitadel-go) on GitHub. +> This documentation references our [example](https://github.com/zitadel/zitadel-go) on GitHub. > You can either create your own application or directly run the example by providing the necessary arguments. ## Set up application @@ -86,7 +90,7 @@ To ensure the user is authenticated before they are able to use your application ```go mw.CheckAuthentication()(handler) ``` - + ***Authentication context*** If you used either of the authentication checks above, you can then access context information in your handler: @@ -119,7 +123,7 @@ https://github.com/zitadel/zitadel-go/blob/next/example/app/templates/profile.ht You will need to provide some values for the program to run: - `domain`: Your ZITADEL instance domain, e.g. my-domain.zitadel.cloud -- `key`: Random secret string. Used for symmetric encryption of state parameters, cookies and PCKE. +- `key`: Random secret string. Used for symmetric encryption of state parameters, cookies and PCKE. - `clientID`: The clientID provided by ZITADEL - `redirectURI`: The redirectURI registered at ZITADEL - `port`: The port on which the API will be accessible, default it 8089 @@ -146,7 +150,7 @@ By clicking on `Login` you will be redirected to your ZITADEL instance. After lo Congratulations! You have successfully integrated your Go application with ZITADEL! -If you get stuck, consider checking out our [example](https://github.com/zitadel/zitadel-go) application. -This application includes all the functionalities mentioned in this quickstart. +If you get stuck, consider checking out our [example](https://github.com/zitadel/zitadel-go) application. +This application includes all the functionalities mentioned in this quickstart. You can directly start it with your own configuration. If you face issues, contact us or raise an issue on [GitHub](https://github.com/zitadel/zitadel-go/issues). diff --git a/docs/docs/examples/secure-api/go.md b/docs/docs/examples/secure-api/go.md index 90fe7830be..7c1db14cf2 100644 --- a/docs/docs/examples/secure-api/go.md +++ b/docs/docs/examples/secure-api/go.md @@ -6,13 +6,17 @@ sidebar_label: Go This integration guide shows you how to integrate **ZITADEL** into your Go API. It demonstrates how to secure your API using OAuth 2 Token Introspection. +> ℹ️ These examples and guides are based on our official [Go SDK](https://github.com/zitadel/zitadel-go). +> +> The SDK is a convenient wrapper around our low-level [OIDC library](https://github.com/zitadel/oidc). For most use cases, using the helpers provided in our [Go SDK](https://github.com/zitadel/zitadel-go) is the recommended approach for implementing authentication. + At the end of the guide you should have an API with a protected endpoint. > This documentation references our HTTP example. There's also one for GRPC. Check them out on [GitHub](https://github.com/zitadel/zitadel-go/blob/next/example/api/http/main.go). ## Prerequisites -This will handle the OAuth 2.0 introspection request including authentication using JWT with Private Key using our [OIDC client library](https://github.com/zitadel/oidc). +This will handle the OAuth 2.0 introspection request including authentication using JWT with Private Key using our [Go SDK](https://github.com/zitadel/zitadel-go). All that is required, is to create your API, create a private key and a personal access token for a service user. ### Set up application and obtain keys @@ -125,7 +129,7 @@ Now you can call the API by browser or curl. Try the healthz endpoint first: curl -i http://localhost:8089/api/healthz ``` -it should return something like: +it should return something like: ``` HTTP/1.1 200 OK diff --git a/docs/docs/guides/integrate/zitadel-apis/example-zitadel-api-with-go.md b/docs/docs/guides/integrate/zitadel-apis/example-zitadel-api-with-go.md index 3fdc3e8490..ef3f1739e5 100644 --- a/docs/docs/guides/integrate/zitadel-apis/example-zitadel-api-with-go.md +++ b/docs/docs/guides/integrate/zitadel-apis/example-zitadel-api-with-go.md @@ -6,13 +6,17 @@ sidebar_label: Example Go This integration guide shows you how to integrate **ZITADEL** into your Go application. It demonstrates how to fetch some data from the ZITADEL management API. +> ℹ️ These examples and guides are based on our official [Go SDK](https://github.com/zitadel/zitadel-go). +> +> The SDK is a convenient wrapper around our low-level [OIDC library](https://github.com/zitadel/oidc). For most use cases, using the helpers provided in our [Go SDK](https://github.com/zitadel/zitadel-go) is the recommended approach for implementing authentication. + At the end of the guide you should have an application able to read the details of your organization. > This documentation references our [CLI example](https://github.com/zitadel/zitadel-go/blob/next/example/client/cli/cli.go). ## Prerequisites -The client [SDK](https://github.com/zitadel/zitadel-go) will handle all necessary OAuth 2.0 requests and send the required headers to the ZITADEL API using our [OIDC client library](https://github.com/zitadel/oidc). +The client [SDK](https://github.com/zitadel/zitadel-go) will handle all necessary OAuth 2.0 requests and send the required headers to the ZITADEL API using our [Go SDK](https://github.com/zitadel/zitadel-go). All that is required, is a service account with an Org Owner (or another role, depending on the needed api requests) role assigned and its key JSON. However, we recommend you read the guide on [how to access ZITADEL API](/docs/guides/integrate/zitadel-apis/access-zitadel-apis)) and the associated guides for a basic knowledge of : @@ -64,7 +68,7 @@ This will output something similar to: You have successfully used the ZITADEL Go SDK to call the management API! -If you encountered an error (e.g. `code = PermissionDenied desc = No matching permissions found`), +If you encountered an error (e.g. `code = PermissionDenied desc = No matching permissions found`), ensure your service user has the required permissions by assigning the `ORG_OWNER` or `ORG_OWNER_VIEWER` role and check the mentioned [guides](#prerequisites) at the beginning. diff --git a/docs/docs/sdk-examples/client-libraries/_category_.json b/docs/docs/sdk-examples/client-libraries/_category_.json new file mode 100644 index 0000000000..f47958cf1c --- /dev/null +++ b/docs/docs/sdk-examples/client-libraries/_category_.json @@ -0,0 +1,4 @@ +{ + "label": "Client Libraries", + "position": 2 +} diff --git a/docs/docs/sdk-examples/client-libraries/java.mdx b/docs/docs/sdk-examples/client-libraries/java.mdx new file mode 100644 index 0000000000..565d2d932a --- /dev/null +++ b/docs/docs/sdk-examples/client-libraries/java.mdx @@ -0,0 +1,194 @@ +--- +title: Java Client +sidebar_label: 'Java Client' +--- + + + + + + +
+ java logo + + This guide covers the official Zitadel Management API Client for the JVM (Java 11+), which allows you to programmatically manage resources in your Zitadel instance. +
+ +:::info +**This is a Management API Client, not an Authentication SDK.** + +This library is designed for server-to-server communication to manage your Zitadel instance (e.g., creating users, managing projects, and updating settings). It is **not** intended for handling end-user login flows in your web application. For user authentication, you should use a standard OIDC library like Spring Security. +::: + +The Zitadel Java Client provides an idiomatic way to access the full gamut of Zitadel's v2 Management APIs from your JVM-based backend applications. + +> Please be aware that this client library is currently in an **incubating stage**. +While it is available for use, the API and its functionality may evolve, potentially introducing +breaking changes in future updates. We advise caution when considering it for production environments. + +### Installation + +You can add the client library to your project using Maven by adding the following dependency to your `pom.xml` : + +```xml + + io.github.zitadel + client + 4.0.0-beta-1 + +``` + +### Using the SDK + +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 + +**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. + +**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. Build the authenticator using the helper method. + +**Example:** + +```java +import com.zitadel.ApiException; +import com.zitadel.Zitadel; +import com.zitadel.model.UserServiceAddHumanUserRequest; +import com.zitadel.model.UserServiceAddHumanUserResponse; +import com.zitadel.model.UserServiceSetHumanEmail; +import com.zitadel.model.UserServiceSetHumanProfile; + +class Demo { + public static void main(String[] args) throws ApiException { + Zitadel zitadel = Zitadel.withPrivateKey("https://example.us1.zitadel.cloud", "path/to/jwt-key.json"); + + UserServiceAddHumanUserResponse response = zitadel.users.userServiceAddHumanUser( + new UserServiceAddHumanUserRequest() + .username("john.doe") + .profile(new UserServiceSetHumanProfile() + .givenName("John") + .familyName("Doe")) + .email(new UserServiceSetHumanEmail() + .email("john@doe.com")) + ); + System.out.println("User created: " + response); + } +} +``` + +#### 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 using the helper method. + +**Example:** + +```java +import com.zitadel.ApiException; +import com.zitadel.Zitadel; +import com.zitadel.model.UserServiceAddHumanUserRequest; +import com.zitadel.model.UserServiceAddHumanUserResponse; +import com.zitadel.model.UserServiceSetHumanEmail; +import com.zitadel.model.UserServiceSetHumanProfile; + +class Demo { + public static void main(String[] args) throws ApiException { + Zitadel zitadel = Zitadel.withClientCredentials("https://example.us1.zitadel.cloud", "id", "secret"); + + UserServiceAddHumanUserResponse response = zitadel.users.addHumanUser( + new UserServiceAddHumanUserRequest() + .username("john.doe") + .profile(new UserServiceSetHumanProfile() + .givenName("John") + .familyName("Doe")) + .email(new UserServiceSetHumanEmail() + .email("john@doe.com")) + ); + System.out.println("User created: " + response); + } +} +``` + +#### 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. Build the authenticator using the helper method. + +**Example:** + +```java +import com.zitadel.ApiException; +import com.zitadel.Zitadel; +import com.zitadel.model.UserServiceAddHumanUserRequest; +import com.zitadel.model.UserServiceAddHumanUserResponse; +import com.zitadel.model.UserServiceSetHumanEmail; +import com.zitadel.model.UserServiceSetHumanProfile; + +class Demo { + + public static void main(String[] args) throws ApiException { + Zitadel zitadel = Zitadel.withAccessToken("https://example.us1.zitadel.cloud", "token"); + + UserServiceAddHumanUserResponse response = zitadel.users.addHumanUser( + new UserServiceAddHumanUserRequest() + .username("john.doe") + .profile(new UserServiceSetHumanProfile() + .givenName("John") + .familyName("Doe")) + .email(new UserServiceSetHumanEmail() + .email("john@doe.com")) + ); + System.out.println("User created: " + response); + } +} +``` + +--- + +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). + +### Versioning + +The client library's versioning is aligned with the Zitadel core project. The major version of the +client corresponds to the major version of Zitadel it is designed to work with. For example, +v2.x.x of the client is built for and tested against Zitadel v2, ensuring a predictable and stable integration. + +### Resources + +- [GitHub Repository](https://github.com/zitadel/client-java): For source code, examples, and to report issues. +- [Maven Package](https://central.sonatype.com/artifact/io.github.zitadel/client): The official package artifact for Maven. diff --git a/docs/docs/sdk-examples/client-libraries/php.mdx b/docs/docs/sdk-examples/client-libraries/php.mdx new file mode 100644 index 0000000000..1f589dd51c --- /dev/null +++ b/docs/docs/sdk-examples/client-libraries/php.mdx @@ -0,0 +1,193 @@ +--- +title: PHP Client +sidebar_label: 'PHP Client' +--- + + + + + + +
+ php logo + + This guide covers the official Zitadel Management API Client for PHP, which allows you to programmatically manage resources in your Zitadel instance. +
+ +:::info +**This is a Management API Client, not an Authentication SDK.** + +This library is designed for server-to-server communication to manage your Zitadel instance (e.g., creating users, managing projects, and updating settings). It is **not** intended for handling end-user login flows in your web application. For user authentication, you should use a standard OIDC library with your PHP framework of choice. +::: + +The Zitadel PHP Client provides an idiomatic way to access the full gamut of +Zitadel's v2 Management APIs from your PHP backend. + +> Please be aware that this client library is currently in an **incubating stage**. +While it is available for use, the API and its functionality may evolve, potentially introducing +breaking changes in future updates. We advise caution when considering it for production environments. + +### Installation + +You can add the client library to your project using Composer: + +```bash +composer require zitadel/client:"^4.0.0-beta1" +``` + +### Using the SDK + +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 + +**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. + +**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:** + +```php +use \Zitadel\Client\Zitadel; + +$zitadel = Zitadel::withPrivateKey("https://example.us1.zitadel.cloud", "path/to/jwt-key.json"); + +try { + $response = $zitadel->users->userServiceAddHumanUser([ + 'username' => 'john.doe', + 'profile' => [ + 'givenName' => 'John', + 'familyName' => 'Doe' + ], + 'email' => [ + 'email' => 'john@doe.com' + ] + ]); + echo "User created: " . print_r($response, true); +} catch (ApiException $e) { + echo "Error: " . $e->getMessage(); +} +``` + +#### 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 + +**Example:** + +```php +use Zitadel\Client\Zitadel; +use Zitadel\Client\Model\UserServiceAddHumanUserRequest; +use \Zitadel\Client\Model\UserServiceAddHumanUserRequest; +use \Zitadel\Client\Model\UserServiceSetHumanProfile; +use \Zitadel\Client\Model\UserServiceSetHumanEmail; + +$zitadel = Zitadel::withClientCredentials("https://example.us1.zitadel.cloud", "id", "secret"); + +try { + $response = $zitadel->users->addHumanUser((new UserServiceAddHumanUserRequest()) + ->setUsername('john.doe') + ->setProfile( + (new UserServiceSetHumanProfile()) + ->setGivenName('John') + ->setFamilyName('Doe') + ) + ->setEmail( + (new UserServiceSetHumanEmail()) + ->setEmail('john@doe.com') + )); + echo "User created: " . print_r($response, true); +} catch (ApiException $e) { + echo "Error: " . $e->getMessage(); +} +``` + +#### 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:** + +```php +use \Zitadel\Client\Zitadel; +use Zitadel\Client\Zitadel; +use Zitadel\Client\Model\UserServiceAddHumanUserRequest; +use \Zitadel\Client\Model\UserServiceAddHumanUserRequest; +use \Zitadel\Client\Model\UserServiceSetHumanProfile; +use \Zitadel\Client\Model\UserServiceSetHumanEmail; + +$zitadel = Zitadel::withAccessToken("https://example.us1.zitadel.cloud", "token"); + +try { + $response = $zitadel->users->addHumanUser( + (new UserServiceAddHumanUserRequest()) + ->setUsername('john.doe') + ->setProfile( + (new UserServiceSetHumanProfile()) + ->setGivenName('John') + ->setFamilyName('Doe') + ) + ->setEmail( + (new UserServiceSetHumanEmail()) + ->setEmail('john@doe.com') + ) + ); + echo "User created: " . print_r($response, true); +} catch (ApiException $e) { + echo "Error: " . $e->getMessage(); +} +``` + +--- + +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). + +### Versioning + +The client library's versioning is aligned with the Zitadel core project. The major version of the +client corresponds to the major version of Zitadel it is designed to work with. For example, +v2.x.x of the client is built for and tested against Zitadel v2, ensuring a predictable and stable integration. + +### Resources + +- [GitHub Repository](https://github.com/zitadel/client-php): For source code, examples, and to report issues. +- [Packagist Package](https://packagist.org/packages/zitadel/client): The official package artifact for Composer. + diff --git a/docs/docs/sdk-examples/client-libraries/python.mdx b/docs/docs/sdk-examples/client-libraries/python.mdx new file mode 100644 index 0000000000..eb49145053 --- /dev/null +++ b/docs/docs/sdk-examples/client-libraries/python.mdx @@ -0,0 +1,197 @@ +--- +title: Python Client +sidebar_label: 'Python Client' +--- + + + + + + +
+ python logo + + This guide covers the official Zitadel Management API Client for Python (3.9+), which allows you to programmatically manage resources in your Zitadel instance. +
+ +:::info +**This is a Management API Client, not an Authentication SDK.** + +This library is designed for server-to-server communication to manage your Zitadel instance (e.g., creating users, managing projects, and updating settings). It is **not** intended for handling end-user login flows in your web application. For user authentication, you should use a standard OIDC library with your Python framework of choice, such as `mozilla-django-oidc` for Django or `Authlib` for Flask. +::: + +The Zitadel Python Client provides an idiomatic way to access the full gamut of Zitadel's v2 Management APIs from your Python backend. + +> Please be aware that this client library is currently in an **incubating stage**. +While it is available for use, the API and its functionality may evolve, potentially introducing +breaking changes in future updates. We advise caution when considering it for production environments. + +### Installation + +You can add the client library to your project using pip: + +```bash +pip install --pre zitadel-client +``` + +### Using the SDK + +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 + +**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. + +**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:** + +```python +import zitadel_client as zitadel +from zitadel_client.exceptions import ApiError +from zitadel_client.models import ( + UserServiceAddHumanUserRequest, + UserServiceSetHumanEmail, + UserServiceSetHumanProfile, +) + +zitadel = zitadel.Zitadel.with_private_key("https://example.us1.zitadel.cloud", "path/to/jwt-key.json") + +try: + request = UserServiceAddHumanUserRequest( + username="john.doe", + profile=UserServiceSetHumanProfile( + givenName="John", + familyName="Doe" + ), + email=UserServiceSetHumanEmail( + email="john@doe.com" + ), + ) + response = zitadel.users.add_human_user(request) + print("User created:", response) +except ApiError 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 + +**Example:** + +```python +import zitadel_client as zitadel +from zitadel_client.exceptions import ApiError +from zitadel_client.models import ( + UserServiceAddHumanUserRequest, + UserServiceSetHumanEmail, + UserServiceSetHumanProfile, +) + +zitadel = zitadel.Zitadel.with_client_credentials("https://example.us1.zitadel.cloud", "id", "secret") + +try: + request = UserServiceAddHumanUserRequest( + username="john.doe", + profile=UserServiceSetHumanProfile( + givenName="John", + familyName="Doe" + ), + email=UserServiceSetHumanEmail( + email="john@doe.com" + ), + ) + response = zitadel.users.add_human_user(request) + print("User created:", response) +except ApiError 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.exceptions import ApiError +from zitadel_client.models import ( + UserServiceAddHumanUserRequest, + UserServiceSetHumanEmail, + UserServiceSetHumanProfile, +) + +zitadel = zitadel.Zitadel.with_access_token("https://example.us1.zitadel.cloud", "token") + +try: + request = UserServiceAddHumanUserRequest( + username="john.doe", + profile=UserServiceSetHumanProfile( + givenName="John", + familyName="Doe" + ), + email=UserServiceSetHumanEmail( + email="john@doe.com" + ), + ) + response = zitadel.users.add_human_user(request) + print("User created:", response) +except ApiError 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). + +### Versioning + +The client library's versioning is aligned with the Zitadel core project. The major version of the +client corresponds to the major version of Zitadel it is designed to work with. For example, +v2.x.x of the client is built for and tested against Zitadel v2, ensuring a predictable and stable integration. + +### Resources + +- [GitHub Repository](https://github.com/zitadel/client-python): For source code, examples, and to report issues. +- [PyPI Package](https://pypi.org/project/zitadel-client): The official package artifact for pip. + diff --git a/docs/docs/sdk-examples/client-libraries/ruby.mdx b/docs/docs/sdk-examples/client-libraries/ruby.mdx new file mode 100644 index 0000000000..eeb0df9b2e --- /dev/null +++ b/docs/docs/sdk-examples/client-libraries/ruby.mdx @@ -0,0 +1,200 @@ +--- +title: Ruby Client +sidebar_label: 'Ruby Client' +--- + + + + + + +
+ ruby logo + + This guide covers the official Zitadel Management API Client for Ruby (3.1+), which allows you to programmatically manage resources in your Zitadel instance. +
+ +:::info +**This is a Management API Client, not an Authentication SDK.** + +This library is designed for server-to-server communication to manage your Zitadel instance (e.g., creating users, managing projects, and updating settings). It is **not** intended for handling end-user login flows in your web application. For user authentication, you should use a standard OIDC library with your Ruby framework of choice. +::: + +The Zitadel Ruby Client provides an idiomatic way to access the full gamut of Zitadel's v2 Management APIs from your Ruby backend. + +> Please be aware that this client library is currently in an **incubating stage**. +While it is available for use, the API and its functionality may evolve, potentially introducing +breaking changes in future updates. We advise caution when considering it for production environments. + +### Installation + +You can add the client library to your project using RubyGems. Add this line to your application's Gemfile: + +```ruby +gem install zitadel-client --pre +``` + +### Using the SDK + +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 + +**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. + +**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 create an authenticator. + +**Example:** + +```ruby +require 'zitadel-client' +require 'securerandom' + +client = Zitadel::Client::Zitadel.with_private_key("https://example.us1.zitadel.cloud", "path/to/jwt-key.json") + +begin + response = client.users.add_human_user( + Zitadel::Client::UserServiceAddHumanUserRequest.new( + username: SecureRandom.hex, + profile: Zitadel::Client::UserServiceSetHumanProfile.new( + given_name: 'John', + family_name: 'Doe' + ), + email: Zitadel::Client::UserServiceSetHumanEmail.new( + email: "john.doe@example.com" + ) + ) + ) + puts "User created: #{response}" +rescue StandardError => e + puts "Error: #{e.message}" +end +``` + +#### 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. Use the provided method to create an authenticator. + +**Example:** + +```ruby +require 'zitadel-client' +require 'securerandom' + +client = Zitadel::Client::Zitadel.with_client_credentials("https://example.us1.zitadel.cloud", "id", "secret") + +begin + response = client.users.add_human_user( + Zitadel::Client::UserServiceAddHumanUserRequest.new( + username: SecureRandom.hex, + profile: Zitadel::Client::UserServiceSetHumanProfile.new( + given_name: 'John', + family_name: 'Doe' + ), + email: Zitadel::Client::UserServiceSetHumanEmail.new( + email: "john.doe@example.com" + ) + ) + ) + puts "User created: #{response}" +rescue StandardError => e + puts "Error: #{e.message}" +end +``` + +#### 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. Use the provided method to create an authenticator. + +**Example:** + +```ruby +require 'zitadel-client' +require 'securerandom' + +client = Zitadel::Client::Zitadel.with_access_token("https://example.us1.zitadel.cloud", "token") + +begin + response = client.users.add_human_user( + Zitadel::Client::UserServiceAddHumanUserRequest.new( + username: SecureRandom.hex, + profile: Zitadel::Client::UserServiceSetHumanProfile.new( + given_name: 'John', + family_name: 'Doe' + ), + email: Zitadel::Client::UserServiceSetHumanEmail.new( + email: "john.doe@example.com" + ) + ) + ) + puts "User created: #{response}" +rescue StandardError => e + puts "Error: #{e.message}" +end +``` + +--- + +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` +flag to `true` when initializing the `Zitadel` client, like this: + +```ruby +zitadel = zitadel.Zitadel("your-zitadel-base-url", 'your-valid-token', lambda config: config.debug = True) +``` + +When enabled, the SDK will log additional information, such as HTTP request +and response details, which can be useful for identifying issues in the +integration or troubleshooting unexpected behavior. + +### Versioning + +The client library's versioning is aligned with the Zitadel core project. The major version of the +client corresponds to the major version of Zitadel it is designed to work with. For example, +v2.x.x of the client is built for and tested against Zitadel v2, ensuring a predictable and stable integration. + +### Resources + +- [GitHub Repository](https://github.com/zitadel/client-ruby): For source code, examples, and to report issues. +- [RubyGems Package](https://rubygems.org/gems/zitadel-client): The official package artifact for RubyGems. diff --git a/docs/docs/sdk-examples/introduction.mdx b/docs/docs/sdk-examples/introduction.mdx index 203e21e9f3..0e7aea7a66 100644 --- a/docs/docs/sdk-examples/introduction.mdx +++ b/docs/docs/sdk-examples/introduction.mdx @@ -19,9 +19,17 @@ We provide this list for informational purposes and to foster community engageme import { Frameworks } from "../../src/components/frameworks"; +## Clients + + framework.client === true } /> + +## SDKs + + framework.sdk === true } /> + ## Resources - + framework.client === false || framework.client == null} /> To further streamline your setup, simply visit the console in ZITADEL where you can select one of the languages or frameworks. This will allow you to instantly set up the configuration for that specific sample in ZITADEL, ensuring you have everything you need to get started right away. diff --git a/docs/frameworks.json b/docs/frameworks.json index 163b493274..88f47d0176 100644 --- a/docs/frameworks.json +++ b/docs/frameworks.json @@ -1,127 +1,169 @@ [ - { - "id": "angular", - "title": "Angular", - "description": "This preset sets up an OIDC configuration with Authentication Code Flow, secured by PKCE", - "imgSrcLight": "/docs/img/tech/angular.svg", - "imgSrcDark": "/docs/img/tech/angular.svg", - "docsLink": "/docs/sdk-examples/angular" - }, - { - "id": "flutter", - "title": "Flutter", - "imgSrcDark": "/docs/img/tech/flutter.svg", - "docsLink": "/docs/sdk-examples/flutter" - }, - { - "title": "Go", - "imgSrcDark": "/docs/img/tech/golang.svg", - "docsLink": "/docs/sdk-examples/go" - }, - { - "id": "java", - "title": "Java", - "imgSrcDark": "/docs/img/tech/java.svg", - "docsLink": "/docs/sdk-examples/java" - }, - { - "title": "NestJS", - "imgSrcDark": "/docs/img/tech/nestjs.svg", - "docsLink": "/docs/sdk-examples/nestjs" - }, - { - "id": "next", - "title": "Next.js", - "imgSrcDark": "/docs/img/tech/nextjs.svg", - "imgSrcLight": "/docs/img/tech/nextjslight.svg", - "docsLink": "/docs/sdk-examples/nextjs" - }, - { - "id": "django", - "title": "Python Django", - "imgSrcDark": "/docs/img/tech/django.png", - "docsLink": "/docs/sdk-examples/python-django" - }, - { - "title": "Python Flask", - "imgSrcDark": "/docs/img/tech/flask.svg", - "imgSrcLight": "/docs/img/tech/flasklight.svg", - "docsLink": "/docs/sdk-examples/python-flask" - }, - { - "id": "react", - "title": "React", - "description": "This preset sets up an OIDC configuration with Authentication Code Flow, secured by PKCE", - "imgSrcDark": "/docs/img/tech/react.png", - "docsLink": "/docs/sdk-examples/react" - }, - { - "id": "symfony", - "title": "Symfony", - "imgSrcDark": "/docs/img/tech/php.svg", - "docsLink": "/docs/sdk-examples/symfony" - }, - { - "id": "vue", - "title": "Vue.js", - "description": "This preset sets up an OIDC configuration with Authentication Code Flow, secured by PKCE", - "imgSrcDark": "/docs/img/tech/vue.svg", - "docsLink": "/docs/sdk-examples/vue" - }, - { - "title": "Dart", - "imgSrcDark": "/docs/img/tech/dart.svg", - "docsLink": "https://github.com/smartive/zitadel-dart", - "external": true - }, - { - "title": "Elixir", - "imgSrcDark": "/docs/img/tech/elixir.svg", - "docsLink": "https://github.com/maennchen/zitadel_api", - "external": true - }, - { - "title": "FastAPI", - "imgSrcDark": "/docs/img/tech/fastapi.svg", - "docsLink": "https://github.com/cleanenergyexchange/fastapi-zitadel-auth", - "external": true - }, - { - "title": "NextAuth", - "imgSrcDark": "/docs/img/tech/nextjs.svg", - "imgSrcLight": "/docs/img/tech/nextjslight.svg", - "docsLink": "https://next-auth.js.org/providers/zitadel", - "external": true - }, - { - "title": "Node.js", - "imgSrcDark": "/docs/img/tech/nodejs.svg", - "docsLink": "https://www.npmjs.com/package/@zitadel/node", - "external": true - }, - { - "title": ".Net", - "imgSrcDark": "/docs/img/tech/dotnet.svg", - "docsLink": "https://github.com/smartive/zitadel-net", - "external": true - }, - { - "title": "Passport.js", - "imgSrcDark": "/docs/img/tech/passportjs.svg", - "docsLink": "https://github.com/buehler/node-passport-zitadel", - "external": true - }, - { - "title": "Rust", - "imgSrcLight": "/docs/img/tech/rust.svg", - "imgSrcDark": "/docs/img/tech/rustlight.svg", - "docsLink": "https://github.com/smartive/zitadel-rust", - "external": true - }, - { - "title": "Pylon", - "imgSrcDark": "/docs/img/tech/pylon.svg", - "docsLink": "https://github.com/getcronit/pylon", - "external": true - } + { + "id": "client-php", + "title": "PHP", + "imgSrcDark": "/docs/img/tech/php.svg", + "docsLink": "/docs/sdk-examples/java", + "client": true + }, + { + "id": "client-java", + "title": "Java", + "imgSrcDark": "/docs/img/tech/java.svg", + "docsLink": "/docs/sdk-examples/java", + "client": true + }, + { + "id": "client-go", + "title": "Go", + "imgSrcDark": "/docs/img/tech/golang.svg", + "docsLink": "/docs/sdk-examples/java", + "client": true, + "sdk": true + }, + { + "id": "client-ruby", + "title": "Ruby", + "imgSrcDark": "/docs/img/tech/ruby.svg", + "docsLink": "/docs/sdk-examples/java", + "client": true + }, + { + "id": "client-python", + "title": "Python", + "imgSrcDark": "/docs/img/tech/python.svg", + "docsLink": "/docs/sdk-examples/java", + "client": true + }, + + { + "id": "angular", + "title": "Angular", + "description": "This preset sets up an OIDC configuration with Authentication Code Flow, secured by PKCE", + "imgSrcLight": "/docs/img/tech/angular.svg", + "imgSrcDark": "/docs/img/tech/angular.svg", + "docsLink": "/docs/sdk-examples/angular" + }, + { + "id": "flutter", + "title": "Flutter", + "imgSrcDark": "/docs/img/tech/flutter.svg", + "docsLink": "/docs/sdk-examples/flutter" + }, + { + "title": "Go", + "imgSrcDark": "/docs/img/tech/golang.svg", + "docsLink": "/docs/sdk-examples/go" + }, + { + "id": "spring", + "title": "Spring", + "imgSrcDark": "/docs/img/tech/spring.svg", + "docsLink": "/docs/sdk-examples/java" + }, + { + "title": "NestJS", + "imgSrcDark": "/docs/img/tech/nestjs.svg", + "docsLink": "/docs/sdk-examples/nestjs" + }, + { + "id": "next", + "title": "Next.js", + "imgSrcDark": "/docs/img/tech/nextjs.svg", + "imgSrcLight": "/docs/img/tech/nextjslight.svg", + "docsLink": "/docs/sdk-examples/nextjs" + }, + { + "id": "django", + "title": "Python Django", + "imgSrcDark": "/docs/img/tech/django.svg", + "docsLink": "/docs/sdk-examples/python-django" + }, + { + "title": "Python Flask", + "imgSrcDark": "/docs/img/tech/flask.svg", + "imgSrcLight": "/docs/img/tech/flask.svg", + "docsLink": "/docs/sdk-examples/python-flask" + }, + { + "id": "react", + "title": "React", + "description": "This preset sets up an OIDC configuration with Authentication Code Flow, secured by PKCE", + "imgSrcDark": "/docs/img/tech/react.svg", + "docsLink": "/docs/sdk-examples/react" + }, + { + "id": "symfony", + "title": "Symfony", + "imgSrcDark": "/docs/img/tech/symfony.svg", + "docsLink": "/docs/sdk-examples/symfony" + }, + { + "id": "vue", + "title": "Vue.js", + "description": "This preset sets up an OIDC configuration with Authentication Code Flow, secured by PKCE", + "imgSrcDark": "/docs/img/tech/vue.svg", + "docsLink": "/docs/sdk-examples/vue" + }, + { + "title": "Dart", + "imgSrcDark": "/docs/img/tech/dart.svg", + "docsLink": "https://github.com/smartive/zitadel-dart", + "external": true, + "client": true, + "sdk": true + }, + { + "title": "Elixir", + "imgSrcDark": "/docs/img/tech/elixir.svg", + "docsLink": "https://github.com/maennchen/zitadel_api", + "external": true + }, + { + "title": "FastAPI", + "imgSrcDark": "/docs/img/tech/fastapi.svg", + "docsLink": "https://github.com/cleanenergyexchange/fastapi-zitadel-auth", + "external": true + }, + { + "title": "NextAuth", + "imgSrcDark": "/docs/img/tech/nextjs.svg", + "imgSrcLight": "/docs/img/tech/nextjslight.svg", + "docsLink": "https://next-auth.js.org/providers/zitadel", + "external": true + }, + { + "title": "Node.js", + "imgSrcDark": "/docs/img/tech/nodejs.svg", + "docsLink": "https://www.npmjs.com/package/@zitadel/node", + "external": true, + "client": true + }, + { + "title": ".Net", + "imgSrcDark": "/docs/img/tech/dotnet.svg", + "docsLink": "https://github.com/smartive/zitadel-net", + "external": true, + "client": true + }, + { + "title": "Passport.js", + "imgSrcDark": "/docs/img/tech/passportjs.svg", + "docsLink": "https://github.com/buehler/node-passport-zitadel", + "external": true + }, + { + "title": "Rust", + "imgSrcLight": "/docs/img/tech/rust.svg", + "imgSrcDark": "/docs/img/tech/rustlight.svg", + "docsLink": "https://github.com/smartive/zitadel-rust", + "client": true, + "external": true + }, + { + "title": "Pylon", + "imgSrcDark": "/docs/img/tech/pylon.svg", + "docsLink": "https://github.com/getcronit/pylon", + "external": true + } ] diff --git a/docs/sidebars.js b/docs/sidebars.js index bc75f9ed87..5d87e1987d 100644 --- a/docs/sidebars.js +++ b/docs/sidebars.js @@ -74,7 +74,6 @@ module.exports = { { type: "category", label: "Examples & SDKs", - link: { type: "doc", id: "sdk-examples/introduction" }, items: [ { type: "autogenerated", diff --git a/docs/src/components/frameworks.jsx b/docs/src/components/frameworks.jsx index ca402ec7ff..a514b8ed2f 100644 --- a/docs/src/components/frameworks.jsx +++ b/docs/src/components/frameworks.jsx @@ -2,20 +2,23 @@ import React from "react"; import { Tile } from "./tile"; import frameworks from "../../frameworks.json"; -export function Frameworks({}) { - return ( -
- {frameworks.map((framework) => { - return ( - - ); - })} -
- ); +export function Frameworks({ filter }) { + const filteredFrameworks = frameworks.filter((framework) => { + return filter ? filter(framework) : true; + }); + + return ( +
+ {filteredFrameworks.map((framework) => ( + + ))} +
+ ); } diff --git a/docs/static/img/tech/django.svg b/docs/static/img/tech/django.svg new file mode 100644 index 0000000000..b3e95f0ca9 --- /dev/null +++ b/docs/static/img/tech/django.svg @@ -0,0 +1,10 @@ + + + + + + + + + + \ No newline at end of file diff --git a/docs/static/img/tech/flask.svg b/docs/static/img/tech/flask.svg index b8f3980529..942ea2143a 100644 --- a/docs/static/img/tech/flask.svg +++ b/docs/static/img/tech/flask.svg @@ -1 +1,4 @@ - \ No newline at end of file + + + + \ No newline at end of file diff --git a/docs/static/img/tech/golang.svg b/docs/static/img/tech/golang.svg index 8164d5589e..026829c2a6 100644 --- a/docs/static/img/tech/golang.svg +++ b/docs/static/img/tech/golang.svg @@ -1,55 +1,8 @@ - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - + + + + + + + + \ No newline at end of file diff --git a/docs/static/img/tech/java.svg b/docs/static/img/tech/java.svg index 80260a726d..9f0f599436 100644 --- a/docs/static/img/tech/java.svg +++ b/docs/static/img/tech/java.svg @@ -1,41 +1,11 @@ - - - - - - - - - - - - - - - - - - + + + + + + + + + + + \ No newline at end of file diff --git a/docs/static/img/tech/nodejs.svg b/docs/static/img/tech/nodejs.svg index 41d044ac6b..ec5b309699 100644 --- a/docs/static/img/tech/nodejs.svg +++ b/docs/static/img/tech/nodejs.svg @@ -1 +1,8 @@ - \ No newline at end of file + + + + + + + + \ No newline at end of file diff --git a/docs/static/img/tech/php.svg b/docs/static/img/tech/php.svg index e4f137cb4c..492cd85d1c 100644 --- a/docs/static/img/tech/php.svg +++ b/docs/static/img/tech/php.svg @@ -1,96 +1,2 @@ - - - Official PHP Logo - - - - image/svg+xml - - Official PHP Logo - - - Colin Viebrock - - - - - - - - - - - - Copyright Colin Viebrock 1997 - All rights reserved. - - - 1997 - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - \ No newline at end of file + +file_type_php3 \ No newline at end of file diff --git a/docs/static/img/tech/python.svg b/docs/static/img/tech/python.svg index 05602a8956..25df8268f7 100644 --- a/docs/static/img/tech/python.svg +++ b/docs/static/img/tech/python.svg @@ -1 +1,15 @@ - \ No newline at end of file + + + + + + + + + + + + + + + \ No newline at end of file diff --git a/docs/static/img/tech/react.svg b/docs/static/img/tech/react.svg new file mode 100644 index 0000000000..d7cb33c2af --- /dev/null +++ b/docs/static/img/tech/react.svg @@ -0,0 +1,5 @@ + + + + + \ No newline at end of file diff --git a/docs/static/img/tech/ruby.svg b/docs/static/img/tech/ruby.svg new file mode 100644 index 0000000000..1083613cde --- /dev/null +++ b/docs/static/img/tech/ruby.svg @@ -0,0 +1,948 @@ + + + +image/svg+xml + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + diff --git a/docs/static/img/tech/spring.svg b/docs/static/img/tech/spring.svg new file mode 100644 index 0000000000..4f70f0b7e4 --- /dev/null +++ b/docs/static/img/tech/spring.svg @@ -0,0 +1,8 @@ + + + + + + + + \ No newline at end of file diff --git a/docs/static/img/tech/symfony.svg b/docs/static/img/tech/symfony.svg new file mode 100644 index 0000000000..0841b4d3c6 --- /dev/null +++ b/docs/static/img/tech/symfony.svg @@ -0,0 +1,2 @@ + + \ No newline at end of file diff --git a/docs/static/img/tech/vue.svg b/docs/static/img/tech/vue.svg index a1d285eb2a..ad3d675c24 100644 --- a/docs/static/img/tech/vue.svg +++ b/docs/static/img/tech/vue.svg @@ -1,2 +1,2 @@ - - + + \ No newline at end of file