Commit d07c6dc5 authored by Simon Schürg's avatar Simon Schürg 🚀
Browse files

refactor(docs): Documentation overhaul

parent e314f02f
......@@ -8,12 +8,14 @@
> *A CLI tool for OAuth and OpenID Connect based access control.*
*Aims to become a swiss army knife for Open ID Connect on the command line.*
## Install
The actl releases can be found at <https://git.schuerg.net/simon/actl/-/releases>.
There are different options to install a release of actl:
1. Using a pre build `deb`, `rpm` or `apk` package for Debian, Ubuntu, Fedora, CentOS, RHEL, Alpine and others. This is the recommended option for users of a supported linux distribution because it does not only install the actl binary but also man pages and shell autocompletion scripts.
1. Using a pre build `deb`, `rpm` or `apk` package for Debian, Ubuntu, Fedora, CentOS, RHEL, Alpine and others. This is the recommended option for users of a supported linux distribution because it does not only install the actl binary but also man pages and shell autocompletion scripts in a sane way.
2. Grab a pre compiled binary for your system architecture from the releases page and install it yourself. Copy the `actl` binary to `~/.local/bin/actl` and give it executable permission with `chmod +x ~/.local/bin/actl`.
3. Compile it from source:
- `git clone ssh://git@git.schuerg.net:2222/simon/actl.git`
......
......@@ -9,7 +9,7 @@ import (
// completionCmd represents the completion command
var completionCmd = &cobra.Command{
Use: "completion [bash|zsh|fish|powershell]",
Short: "Generate completion script",
Short: "Generate actl shell completion for bash, zsh, fish and powershell.",
Long: `To load completions:
Bash:
......
......@@ -7,9 +7,10 @@ import (
var decodeCmd = &cobra.Command{
Use: "decode [jwt]",
Short: "Decodes a JWT and returns the result.",
Long: `Decodes a JWT (JSON Web Token) and returns the result.`,
Args: cobra.ExactArgs(1),
Short: "Decode a JWT and print it to stdout.",
Long: `Decodes a JWT (JSON Web Token) and print it to stdout.
The JWT headers and payload (claims) will be printed.`,
Args: cobra.ExactArgs(1),
Run: func(cmd *cobra.Command, args []string) {
token := args[0]
internal.PrettyPrintDecodedJWT(token)
......
......@@ -8,8 +8,8 @@ import (
var decryptCmd = &cobra.Command{
Use: "decrypt [privKey]",
Short: "Decrypts a JSON payload and returns a JWT.",
Long: `Decrypts a JSON payload and returns a JWT.`,
Short: "Decrypt a JWE cipher and print the plaintext payload.",
Long: `Decrypt a JWE cipher and print the plaintext payload.`,
Run: func(cmd *cobra.Command, args []string) {
log.Fatalln("This command is not yet implemented!")
},
......
......@@ -9,7 +9,7 @@ import (
var discoverCmd = &cobra.Command{
Use: "discover [issuer]",
Short: "OpenID provider configuration discovery",
Short: "Discover OpenID Connect provider configurations.",
Long: `Fetches the well known OpenID Connect configuration URL and displays the result on stdout.`,
Args: cobra.ExactArgs(1),
Run: func(cmd *cobra.Command, args []string) {
......
......@@ -14,8 +14,15 @@ func init() {
var docsCmd = &cobra.Command{
Use: "docs",
Short: "Generates the actl documentation",
Long: `Generates the actl documentation`,
Short: "Generate the actl documentation as .man, .md, .rst or .yaml.",
Long: `Generate the actl documentation in multiple formats:
- UNIX man pages
- Markdown
- reStructuredText
- YAML
The output directory is "./docs", relative to the current working directory.`,
Run: func(cmd *cobra.Command, args []string) {
manpageHeader := &doc.GenManHeader{
Title: "ACTL",
......
......@@ -8,8 +8,8 @@ import (
var encryptCmd = &cobra.Command{
Use: "encrypt [json] [pubKey]",
Short: "Encrypts a JSON payload and returns a JWE cipher.",
Long: `Encrypts a JSON payload and returns a JWE (JSON Web Encryption) cipher.`,
Short: "Encrypt a JSON payload as a JWE (JSON Web Encryption) cipher.",
Long: `Encrypt a JSON payload as a JWE (JSON Web Encryption) cipher.`,
Run: func(cmd *cobra.Command, args []string) {
log.Fatalln("This command is not yet implemented!")
},
......
......@@ -8,8 +8,11 @@ import (
var keygenCmd = &cobra.Command{
Use: "keygen",
Short: "Generates a key(pair) for JWS signing and verifying.",
Long: `Generates a key(pair) for JWS signing and verifying.`,
Short: "Generate keys for JSON Object Signing and Encryption (JOSE).",
Long: `Generate keys for JSON Object Signing and Encryption (JOSE).
There is JWS (JSON Web Signature) for signing and JWE for encrypting JSON payloads.
The result is in both cases a so called JWT (JSON Web Token) in Base64 format.`,
Run: func(cmd *cobra.Command, args []string) {
log.Fatalln("This command is not yet implemented!")
},
......
......@@ -60,8 +60,40 @@ func (c RefreshCredentials) Login() *internal.TokenSet {
var loginCmd = &cobra.Command{
Use: "login",
Short: "Performs an OpenID Connect Login and retrieve tokens.",
Long: `Performs an OpenID Connect Login and retrieve two JWT - an access token and a refresh token.`,
Short: "Perform an OpenID Connect Auth Flow and retrieve a JWT token set.",
Long: `Perform an OpenID Connect Auth Flow and retrieve a JWT token set.
You can either use one of the auth flow specific subcommands directly,
or specify login profiles in the actl config (e.g. ~/.config/actl.actl.toml)
for easy repeatability and convenience. There is also dynamic shell completion
for login profiles specified in the config.
Login examples:
# Using a login profile from the actl config
$ actl login --profile jane-example
# The same as above, but automatically copy the retrieved access token
# to my clipboard for easy usage and pasting.
$ actl login --profile jane-example
# Using the code subcommand (Authorization Code Flow) directly
$ actl login code --issuer https://auth.example.com/ --client_id oidc-client
# Using the password subcommand (Resource Owner Password Credentials flow) directly
$ actl login password --issuer https://auth.example.com/ --client_id oidc-client --username jane --password top-secret
# Using the client subcommand (Client Credentials flow) directly
$ actl login client --issuer https://auth.example.com/ --client_id oidc-client --client_secret d52cc581-7bc2-4bf4-aa78-25d0c86e4cc9
# Perform a token refresh instead of a completly new login
$ actl login refresh --issuer https://auth.example.com/ --client_id oidc-client --refresh_token eyJhbGciOiJIUz...
The result will be printed to stdout and typically contains some of these tokens:
- access token
- refresh token
- id token`,
Run: func(cmd *cobra.Command, args []string) {
if profile != "" {
loginProfile := GetProfile(profile)
......
......@@ -8,8 +8,8 @@ import (
var signCmd = &cobra.Command{
Use: "sign [json]",
Short: "Signs a JSON payload and returns a JWT.",
Long: `Signs a JSON payload and returns a JWT.`,
Short: "Sign a JSON payload as a JWS (JSON Web Signature).",
Long: `Sign a JSON payload as a JWS (JSON Web Signature).`,
Run: func(cmd *cobra.Command, args []string) {
log.Fatalln("This command is not yet implemented!")
},
......
......@@ -9,8 +9,8 @@ import (
var statusCmd = &cobra.Command{
Use: "status",
Short: "Print the current state of OpenID Connect sessions",
Long: `Print the current state of OpenID Connect sessions`,
Short: "Print state information.",
Long: `Print state information.`,
Run: func(cmd *cobra.Command, args []string) {
if viper.ConfigFileUsed() != "" {
fmt.Printf("Using config file: %s\n", viper.ConfigFileUsed())
......
......@@ -7,8 +7,8 @@ import (
var userinfoCmd = &cobra.Command{
Use: "userinfo [access_token]",
Short: "Fetches the OpenID Connect userinfo endpoint and returns the result",
Long: `Fetches the OpenID Connect userinfo endpoint and returns the result`,
Short: "Fetch the OpenID Connect userinfo endpoint and print it to stdout",
Long: `Fetch the OpenID Connect userinfo endpoint and print it to stdout`,
Args: cobra.ExactArgs(1),
Run: func(cmd *cobra.Command, args []string) {
rawToken := args[0]
......
......@@ -45,3 +45,9 @@ func PrintTokenSet(tokenSet *TokenSet) {
FatalOnError(err)
PrettyPrintJSON(tokenSetJSON)
}
func PrintStructAsJSON(anyStruct interface{}) {
jsonBytes, err := json.Marshal(anyStruct)
FatalOnError(err)
PrettyPrintJSON(jsonBytes)
}
Supports Markdown
0% or .
You are about to add 0 people to the discussion. Proceed with caution.
Finish editing this message first!
Please register or to comment