{"id":16526742,"url":"https://github.com/nikhiljohn10/step-ca-tutorials","last_synced_at":"2025-10-12T20:41:23.919Z","repository":{"id":47531061,"uuid":"377123765","full_name":"nikhiljohn10/step-ca-tutorials","owner":"nikhiljohn10","description":"This is an automated demo that takes you through the process of setting up PKI.","archived":false,"fork":false,"pushed_at":"2021-09-09T12:26:24.000Z","size":180,"stargazers_count":3,"open_issues_count":0,"forks_count":0,"subscribers_count":3,"default_branch":"main","last_synced_at":"2025-01-13T16:16:42.041Z","etag":null,"topics":["demo","multipass","pki","step-ca","tutorial"],"latest_commit_sha":null,"homepage":"","language":"Shell","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"unlicense","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/nikhiljohn10.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}},"created_at":"2021-06-15T10:29:27.000Z","updated_at":"2024-08-16T22:32:25.000Z","dependencies_parsed_at":"2022-09-08T18:20:22.029Z","dependency_job_id":null,"html_url":"https://github.com/nikhiljohn10/step-ca-tutorials","commit_stats":null,"previous_names":[],"tags_count":0,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/nikhiljohn10%2Fstep-ca-tutorials","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/nikhiljohn10%2Fstep-ca-tutorials/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/nikhiljohn10%2Fstep-ca-tutorials/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/nikhiljohn10%2Fstep-ca-tutorials/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/nikhiljohn10","download_url":"https://codeload.github.com/nikhiljohn10/step-ca-tutorials/tar.gz/refs/heads/main","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":241610978,"owners_count":19990505,"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","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":["demo","multipass","pki","step-ca","tutorial"],"created_at":"2024-10-11T17:29:50.777Z","updated_at":"2025-10-12T20:41:18.885Z","avatar_url":"https://github.com/nikhiljohn10.png","language":"Shell","readme":"# Step CA Tutorials\n\nAn automated demo for Step CA using Multipass\n\n(Docker \u0026 K8 demo coming soon)\n\n## Installation\n\n### Multipass\n\n**Ubuntu**\n```\nsudo snap install multipass\n```\n\n**macOS**\n```\nbrew install --cask multipass\n```\n\nFor other methods of installations, follow this [link](https://multipass.run/)\n\n### Tutorial\n\n```\ngit clone https://github.com/nikhiljohn10/step-ca-tutorials\ncd step-ca-tutorials\n```\n\nUse `vm.sh` script to manage virtual ubuntu instance via multipass.\n\n```\nUsage: ./vm.sh \u003cINSTANCE|KEYWORD\u003e [OPTIONS]\nOptions:\n         -u,--upgrade    Update and upgrade packages inside ubuntu instance\n         -f,--force      Force a new instance to start\n         -d,--delete     Delete the instance\n\nKeywords: ca, server, client, help, reset\nIf none of keywords given, it creates a generic instance with name INSTANCE\n```\n\nUse `./vm.sh help` to display command help.\nUse `./vm.sh reset` to delete all instance and purge them. (**Use this option with care if you have other instances running in multipass.**)\n\n## Step by Step by Step\n\nRun the following 3 commands in 3 different terminals. The last two commands are only for testing the Certificate Authority.\n\n### 1. `./vm.sh ca`\n\n`ubuntu@stepca` : Contains Step CA PKI\n\n   1. Verify network, dependencies \u0026 instance existence\n   2. Multipass generate ubuntu instance using cloud-init configuration from `/configs/ca.yaml`\n   3. Install `runstep` command inside the instance\n   4. Install `step-ca` and `step-cli` inside the instance\n   5. Generate passwords\n   6. Generate PKI\n   7. Add `acme` provisioner of type `ACME`\n   8. Move the PKI files to `/etc/step-ca`\n   9. Install, enable \u0026 start `step-ca` server as a service\n   10. Display bootstrapping commands\n\n### 2. `./vm.sh server`\n\n`ubuntu@website` : Contain HTTPS server which subscribes to the CA\n\n   1. Verify network, dependencies \u0026 instance existence\n   2. Multipass generate ubuntu instance using cloud-init configuration from `/configs/server.yaml`\n   3. Install `runstep` command inside the instance\n   4. Install `step-ca` and `step-cli` inside the instance\n   5. Install, enable `https-server` as a service\n\n### 3. `./vm.sh client`\n\n`ubuntu@home` : Uses `curl` command with the client and root certificates to connect with an HTTPS server \n\n   1. Verify network, dependencies \u0026 instance existence\n   2. Multipass generate ubuntu instance using cloud-init configuration from `/configs/client.yaml`\n   3. Install `runstep` command inside the instance\n   4. Install `step-ca` and `step-cli` inside the instance\n\nUbuntu 20.04 LTS is the default image used by multipass. For bootstrapping, you can use Password tokens or ACME service. By default, certbot is used to subscribe to ACME service in `ubuntu@stepca`.\n\nAll the bootstrapping commands required by the webserver and client will be displayed in `ubuntu@stepca` after the instance configuration is complete.\n\nTo load the shell of corresponding instance, run the same command again. To refresh the instance, pass `-f` or `--force` parameter after the command. This will delete, purge and start the instance fresh.\n\n### Testing\n\n```\n./test.sh\n```\nThis command will run 2 major test which uses the above 3 commands followed by bootstrapping commands.\n\n**Tests:**\n\n   1. HTTPS Request without mTLS\n   2. HTTPS Request with mTLS\n\n---\n\u003e *Note: The following commands are only for reference.*\n\n## Using runstep command\n\n`runstep` command is custom-built for this tutorial to demo the working of step-ca.\n\n```\nUsage: runstep \u003ccommand\u003e\nCommands:\n        install                         Install Step CA **\n        uninstall                       Uninstall Step CA **\n        init                            Initialise Step CA\n        service [COMMAND]               Manage Step CA service ** (Show status if no commands found)\n        follow [KEYWORD]                Follow a service log \n        start                           Start Step CA server\n        commands [STEP PATH]            Show credentials of CA ** (default path=$ROOT_STEP_PATH)\n        bootstrap FINGERPRINT [-c]      Bootstrap Step CA inside a client\n        server [-m] [-p|--port PORT]    Run HTTPS server with optional mTLS **\n        server COMMAND                  Manage HTTPS server service using systemctl commands **\n        certbot                         Run certbot and obtain client certificate from stepca **\n        certificate                     Generate a client certificate\n\nService commands:  install, start, stop, enable [--now], disable [--now], restart, status \nFollow keywords:   ca (Step CA server), server (HTTPS WebServer), mtls (HTTPS Server with mTLS), syslog (System Logs)\n\n[ ** - Require root access ]\n```\n\n`runstep` can manage the lifecycle of step-ca using inner shortcut commands.\n\nWhen the `step-ca.service` is installed, the step-ca path is moved from the user's home directory to `/etc/step-ca/`.\n\n**Note: Do not run `init`, `bootstrap`, `start`, `certificate` \u0026 `follow` commands with root privileges**\n\n### Bootstrapping\n\n```\nrunstep bootstrap FINGERPRINT\n```\nThis will fetch \u0026 install the CA root certificate from `ubuntu@stepca`.\n\n```\nsudo runstep certbot\n```\nGet a new client certificate and private key using `certbot` on the first run. Once certificates are obtained, certbot will renew the certificate every 12 hours automatically and restart the webserver if the `https-server` service exists.\n\n### Webserver\n\nThis command will start a new HTTPS server\n```\nsudo runstep server [-m|--mtls] [-p|--port PORT]\n```\n\n- With `-m` or `--mtls` options, the client will have to request the server along with client certificates to allow mutual authentication. By default, https-server does not use mTLS.\n\n- With `-p PORT` or `--port PORT` option, HTTPS server start listening in the given port number. Default is `443`.\n\nPre-installed HTTPS server listens on port `443` without using mTLS. To manage pre-installed HTTPS server in use following format: \n```\nsudo runstep server COMMAND\n```\n\nAvailable service commands are `start`, `stop`, `enable`, `disable`, `restart`.\n\n### Client\n\nAfter bootstrapping, you can use the following commands depending on the type of authentication.\n\nNormal TLS:\n```\ncurl https://website.local\n```\n\nMutual TLS:\n```\ncurl https://website.local:8443 --cert $(step path)/certs/home.local.crt --key $(step path)/secrets/home.local.key\n```\n\n**NOTE: You need to pass `--cacert` if the root certificate is not installed. But by default, the root certificate is installed while bootstrapping.**\n\n### Alternative to certbot\n\nTo obtain a client certificate for `ubuntu@home`, you can use the following command.\n```\nrunstep certificate [TOKEN]\n```\n\nIf no token parameter is provided, you have to choose the token-admin provisioner which uses the jwk token method. It will ask for a provisioner password. You can copy \u0026 paste the password from the terminal of `ubuntu@stepca` instance.\n\nYou can use the following command to display the bootstrapping process.\n```\nsudo runstep commands\n```\n\n**Note: Refer `test.sh` to understand how to use `certificate` command with the one-time token. Password is not required when the token parameter is given.**\n\n## Limitation\n\n- Not compatible with Windows or WSL\n- DNS Issue in Ubuntu can be resolved by running `bash utils/netfix_ubuntu.sh` on the host system\n\n## Credits\n\nThis project is completed with great help from various communities.\n\n- [Michał Sawicz](https://github.com/Saviq) (multipass)\n- [Mariano Cano](https://github.com/maraino) (stepca)\n","funding_links":[],"categories":[],"sub_categories":[],"project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fnikhiljohn10%2Fstep-ca-tutorials","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fnikhiljohn10%2Fstep-ca-tutorials","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fnikhiljohn10%2Fstep-ca-tutorials/lists"}