zitadel / zitadel-tools

zitadel-tools

Installation

go install github.com/zitadel/zitadel-tools@latest

key2jwt

Convert a key file to jwt token

Usage

key2jwt requires two flags:

• audience: where the assertion is going to be used (e.g. https://zitadel.cloud or https://{your domain})
• key: the path to the key.json

The tool prints the result to standard output.

zitadel-tools key2jwt --audience=https://zitadel.cloud --key=key.json

Optionally you can pass an output flag. This will save the jwt in the provided file path:

zitadel-tools key2jwt --audience=https://zitadel.cloud --key=key.json --output=jwt.txt

You can also create a JWT by providing a RSA private key (.pem file). You then also need to specify the issuer of the token:

zitadel-tools key2jwt --audience=https://zitadel.cloud --key=key.pem --issuer=client_id

basicauth

Convert client ID and client secret to be used in Authorization header for Client Secret Basic

Usage

basicauth requires two flags:

• id: client id
• secret: client secret

The tool prints the URL- and Base64 encoded result to standard output

zitadel-tools basicauth --id $CLIENT_ID --secret $CLIENT_SECRET

Migrate data to ZITADEL import

Zitadel-tools can be used to transform exported data from other providers to the import schema of Zitadel. We currently support Auth0 and Keycloak.

To print available sub-commands and flags:

zitadel-tools migrate --help

zitadel-tools's Issues

Keyclock hashed password migration

Admins must be able to migrate KeyCloak users to ZITADEL. For that we should provide a tool, which takes exported users and a credential export and create a JSON file, which can be used to import into ZITADEL.

Acceptance criteria

• import.json ready to be used on the Import endpoint of Admin API
• hashed password format in MCF (see below)

Additional Information

Keyclock stores passwords in the following format:

 "credentials": [
      {
        "id": "f27826f7-6ec1-4283-822f-10e0c51a9089",
        "type": "password",
        "userLabel": "My password",
        "createdDate": 1690887741455,
        "secretData": "{\"value\":\"G4pkQxlaYGLOqaO4wDUgItslxTtvcg3lv+JihbYD2ccym7aDixYmCUf5L318TjrfMFZIxqwzrVjGTXUF5GGttA==\",\"salt\":\"VaXa3H3OJXXujl+cRg66HA==\",\"additionalParameters\":{}}",
        "credentialData": "{\"hashIterations\":27500,\"algorithm\":\"pbkdf2-sha256\",\"additionalParameters\":{}}"
      }
    ],

For a ZITADEL import, the format needs to be according to the Modular Crypt Format, e.g. $pbkdf2-sha256$12$cmFuZG9tc2FsdGlzaGFyZA$OFvEcLOIPFd/oq8egf10i.qJLI7A8nDjPLnolCWarQY

one - to - one mapping of Auth0 userdata

The current Auth0 migration tool currently transforms data:

Source (Auth0)	Destination (ZITADEL)
email	userName
name	firstName
name	lastName
--email-verified flag	isEmailVerified

I believe this was based on the data available in the export example docs. However, digging a little deeper, it seems it's possible to extract all fields from auth0 directly: https://auth0.com/docs/manage-users/user-accounts/user-profiles/user-profile-structure. Including fields currently not even considered, such as a metadata object.

Acceptance criteria

• Map all available export fields to available import fields
• Update the documentation with the command required to export those fields from Auth0

update this repo

• master to main
• codeql

[key2jwt]: allow PKCS8

The key2jwt currently is only able to handle RSA private keys in PKCS1 format. Depending on the tool and version used to create a key pair, the create private key might be in PKCS8.

Acceptance criteria

• Sign JWT with private key of PKCS8 format