{"id":20238449,"url":"https://github.com/smallstep/clients","last_synced_at":"2025-08-18T20:45:38.231Z","repository":{"id":40798203,"uuid":"429247240","full_name":"smallstep/clients","owner":"smallstep","description":"Various client examples for getting TLS certificates from a Smallstep CA server","archived":false,"fork":false,"pushed_at":"2025-03-24T14:37:34.000Z","size":140,"stargazers_count":19,"open_issues_count":0,"forks_count":4,"subscribers_count":9,"default_branch":"main","last_synced_at":"2025-08-12T15:08:55.833Z","etag":null,"topics":["csr","jwt","security","x509"],"latest_commit_sha":null,"homepage":"","language":"Python","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"apache-2.0","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/smallstep.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":null,"license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null,"zenodo":null}},"created_at":"2021-11-18T00:45:27.000Z","updated_at":"2025-05-29T13:31:47.000Z","dependencies_parsed_at":"2024-04-09T22:41:27.728Z","dependency_job_id":"44c041dc-0984-47ec-8530-42214e7f68b5","html_url":"https://github.com/smallstep/clients","commit_stats":null,"previous_names":[],"tags_count":0,"template":false,"template_full_name":null,"purl":"pkg:github/smallstep/clients","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/smallstep%2Fclients","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/smallstep%2Fclients/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/smallstep%2Fclients/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/smallstep%2Fclients/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/smallstep","download_url":"https://codeload.github.com/smallstep/clients/tar.gz/refs/heads/main","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/smallstep%2Fclients/sbom","scorecard":null,"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":271059731,"owners_count":24692425,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2022-07-04T15:15:14.044Z","status":"online","status_checked_at":"2025-08-18T02:00:08.743Z","response_time":89,"last_error":null,"robots_txt_status":"success","robots_txt_updated_at":"2025-07-24T06:49:26.215Z","robots_txt_url":"https://github.com/robots.txt","online":true,"can_crawl_api":true,"host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["csr","jwt","security","x509"],"created_at":"2024-11-14T08:34:13.927Z","updated_at":"2025-08-18T20:45:38.158Z","avatar_url":"https://github.com/smallstep.png","language":"Python","readme":"# step-ca certificate signing client\n\nThis repo contains demo client code in various languages, for getting X.509 certificates signed by a [step-ca](https://github.com/smallstep/certificates/) Certificate Authority.\n\n## How you might use this\n\nUse one of these clients if you need to write a custom integration with `step-ca` that authenticates X.509 certificate requests on behalf of your users.\n\n**These clients are not designed to be used directly by end users.** Their use of an unencrypted JWK for the [JWK provisioner](https://smallstep.com/docs/step-ca/provisioners#jwk) gives these clients too much power.\nFor direct end user applications, we recommend using the [OIDC provisioner](https://smallstep.com/docs/step-ca/provisioners/#oauthoidc-single-sign-on) if possible.\nAlternatively, you could modify this code to interactively ask for a JWK password to decrypt the JWK used by the CA.\n\nThe examples in this repository let you **delegate CA authentication or access control to a custom service** that will request TLS certificates on behalf of its clients.\nYour implementation must be responsible for authentication and access control.\n\nFor example, say you manage a set of global VPN servers for your company, \nand each VPN server provides access to an internal network for a given business unit or region.\nYou've created a service for managing VPN access and issuing client certificates.\nThe service maintains an access control database that maps employees to VPN servers.\nAn employee can sign in and request access to a particular server.\nWhen access is granted, the service will get an appropriate CSR signed by the CA,\nand make the certificate available for download.\n\n## Alternatives\n\nIf you only need certificates with IP or hostname identifiers, the ACME protocol may be ba better fit for you.\nIt has [many client implementations](https://letsencrypt.org/docs/client-options/).\nPair your ACME client with `step-ca`'s [ACME provisioner](https://smallstep.com/docs/step-ca/provisioners#acme).\n\nThe [OIDC provisioner](https://smallstep.com/docs/step-ca/provisioners/#oauthoidc-single-sign-on) allows you to authenticate client certificate requests using any OpenID Connect identity provider.\nThis is a better fit for integrating into interactive, end-user workflows.\n\n## You will need\n\n- A `step-ca` server or a [Certificate Manager](https://smallstep.com/certificate-manager/) authority.\n- A JWK provisioner configured in your CA. (use `step ca provisioner add` to add one)\n- The JSON for the provisioner's JWK praviate key, to authenticate the client to the CA. To generate the JSON file, take the `encryptedKey` value from the CA provisioner, and run:\n\n  ```\n  $ step crypto jwe decrypt \u003c encrypted.key \u003e decrypted.json\n  Please enter the password to decrypt the content encryption key: \n  $ cat decrypted.json\n  {\"use\":\"sig\",\"kty\":\"EC\",\"kid\":\"udaECquEXAMPLErW2dYw\",\"crv\":\"P-256\",\"alg\":\"ES256\",\"x\":\"Pn_JEXAMPLEByDJA\",\"y\":\"_x7JjfwqKEXAMPLEBp73E\",\"d\":\"u1_OZH1EXAMPLEXAL__bE6u0\"}\n  ```\n  \n  Treat this `decrypted.json` file as you would any sensitive credential. Anyone with this file can sign arbitrary certificates with your CA.\n\n## Features\n\nThese clients are not full featured. They are able to do the following:\n- Bootstrap with the CA (download the CA root certificate securely)\n- Check CA health\n- Get a Certificate Signing Request (CSR) signed by a [JWK provisioner](https://smallstep.com/docs/step-ca/provisioners#jwk) configured in the CA\n\n## Under the hood\n\nTo get the CSR signed, clients follow these steps:\n- Bootstrap with the CA (using the CA's URL and SHA256 root certificate fingerprint); and download the root certificate\n- Generate the desired CSR (a [PKCS#10](https://www.rfc-editor.org/rfc/rfc2986#section-4.2) PEM)\n- Generate and sign a one-time-use authentication token for the CA. This token is a JSON Web Token (JWT) ([RFC 7519](https://datatracker.ietf.org/doc/html/rfc7519); see [jwt.io](https://jwt.io/)) signed using the JSON Web Key (JWK) that has been configured in the CA's JWK provisioner.\n- POST the CSR and JWT to the `/1.0/sign` endpoint on the CA\n- Return the signed TLS certificate PEM from the response.\n\n## See also\n\n- Our [Go client examples](https://github.com/smallstep/certificates/tree/master/examples) in smallstep/certificates. This example illustrates how to do basic CA client operations in Go, using smallstep's Go bindings.\n- Our [Go gRPC example](https://github.com/smallstep/go-grpc-example). This example shows how to create a Go service that uses TLS. A further example illustrates how to manage TLS server certificate using the ACME protocol.\n","funding_links":[],"categories":[],"sub_categories":[],"project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fsmallstep%2Fclients","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fsmallstep%2Fclients","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fsmallstep%2Fclients/lists"}