OAuth2c: user-friendly OAuth CLI

oauth2c is a command-line tool for interacting with OAuth 2.0 authorization servers. Its goal is to make it easy to fetch access tokens using any grant type or client authentication method. It is compliant with almost all basic and advanced OAuth 2.0, OIDC, OIDF FAPI and JWT profiles.

Features

• support for authorization code, hybrid, implicit, password, client credentials, refresh token, JWT bearer, token exchange, device grant flows
• support for client secret basic, client secret post, client secret JWT, private key JWT, TLS client auth client authentication methods
• passing request parameters as plaintext, signed, and/or encrypted JWT
• support for Proof Key for Code Exchange (PKCE)
• support for JWT Secured Authorization Response Mode (JARM)
• support for Pushed Authorization Requests (PAR)
• support for Demonstration of Proof of Possession (DPoP)
• support for Rich Authorization Requests (RAR)

Installation

To install oauth2c, you have several options depending on your operating system.

Install on Mac

On Mac, you can install oauth2c using brew by running the following command:

brew install cloudentity/tap/oauth2c

Install on Linux

On linux, you can install oauth2c using the installation script by running the following command:

curl -sSfL https://raw.githubusercontent.com/cloudentity/oauth2c/master/install.sh | \
  sudo sh -s -- -b /usr/local/bin latest

Alternatively, you can check the packages page for specific instructions on installing oauth2c using a package manager.

Compile from source

To compile oauth2c from source using go. To do this run the following command:

go install github.com/cloudentity/oauth2c@latest

You can also download a pre-built binary from the releases page.

Usage

To use oauth2c, run the following command and follow the prompts:

oauth2c [issuer url] [flags]

The available flags are:

      --acr-values strings                                  ACR values
      --actor-token string                                  acting party token
      --actor-token-type string                             acting party token type
      --assertion string                                    claims for jwt bearer assertion
      --audience strings                                    requested audience
      --auth-method string                                  token endpoint authentication method
      --authentication-code string                          authentication code used for passwordless authentication
      --authorization-endpoint string                       server's authorization endpoint
      --browser-timeout duration                            browser timeout (default 10m0s)
      --callback-addr string                                callback server bind address (e.g., 0.0.0.0:8080)
      --callback-tls-cert string                            path to callback tls cert pem file
      --callback-tls-key string                             path to callback tls key pem file
      --claims string                                       use claims
      --client-id string                                    client identifier
      --client-secret string                                client secret
      --device-authorization-endpoint string                server's device authorization endpoint
      --dpop                                                use DPoP
      --encrypted-request-object                            pass request parameters as encrypted jwt
      --encryption-key string                               path or url to encryption key in jwks format
      --grant-type string                                   grant type
  -h, --help                                                help for oauth2c
      --http-timeout duration                               http client timeout (default 1m0s)
      --id-token-hint string                                id token hint
      --idp-hint string                                     identity provider hint
      --insecure                                            allow insecure connections
      --login-hint string                                   user identifier hint
      --max-age string                                      maximum authentication age in seconds
      --mtls-pushed-authorization-request-endpoint string   server's mtls pushed authorization request endpoint
      --mtls-token-endpoint string                          server's mtls token endpoint
      --no-browser                                          do not open browser
      --no-prompt                                           disable prompt
      --par                                                 enable pushed authorization requests (PAR)
      --password string                                     resource owner password credentials grant flow password
      --pkce                                                enable proof key for code exchange (PKCE)
      --prompt strings                                      end-user authorization purpose
      --purpose string                                      string describing the purpose for obtaining End-User authorization
      --pushed-authorization-request-endpoint string        server's pushed authorization request endpoint
      --rar string                                          use rich authorization request (RAR)
      --redirect-url string                                 client redirect url (default "http://localhost:9876/callback")
      --refresh-token string                                refresh token
      --request-object                                      pass request parameters as jwt
      --response-mode string                                response mode
      --response-types strings                              response type
      --scopes strings                                      requested scopes
      --signing-key string                                  path or url to signing key in jwks format
  -s, --silent                                              silent mode
      --subject-token string                                third party token
      --subject-token-type string                           third party token type
      --tls-cert string                                     path to tls cert pem file
      --tls-key string                                      path to tls key pem file
      --tls-root-ca string                                  path to tls root ca pem file
      --token-endpoint string                               server's token endpoint
      --username string                                     resource owner password credentials grant flow username

oauth2c opens a browser for flows such as authorization code and starts an HTTP server which acts as a client application and waits for a callback.

Note: To make browser flows work add http://localhost:9876/callback as a redirect URL to your client.

oauth2c prints all the requests it made to obtain an access token. If you want to integrate it with CI/CD pipeline use the --silent flag.

For more information on the available options and arguments run oauth2c --help.

Examples

Here are a few examples of using oauth2c with different grant types and client authentication methods:

Grant types

NOTE: The authorization code, implicit, hybrid and device grant flows require browser and user authentication.

Authorization code

This grant type involves a two-step process where the user first grants permission to access their data, and then the client exchanges the authorization code for an access token. This grant type is typically used in server-side applications.

oauth2c https://oauth2c.us.authz.cloudentity.io/oauth2c/demo \
  --client-id cauktionbud6q8ftlqq0 \
  --client-secret HCwQ5uuUWBRHd04ivjX5Kl0Rz8zxMOekeLtqzki0GPc \
  --response-types code \
  --response-mode query \
  --grant-type authorization_code \
  --auth-method client_secret_basic

Learn more about authorization code flow

Implicit

This grant type is similar to the authorization code grant, but the access token is returned directly to the client without an intermediate authorization code. This grant type is typically used in single-page or mobile applications.

Note: The implicit flow is not recommended for use in modern OAuth2 applications. Instead, it is recommended to use the authorization code flow with PKCE (Proof Key for Code Exchange) for added security.

oauth2c https://oauth2c.us.authz.cloudentity.io/oauth2c/demo \
  --client-id cauktionbud6q8ftlqq0 \
  --response-types token \
  --response-mode form_post \
  --grant-type implicit \
  --scopes openid,email,offline_access

Learn more about implicit flow

Hybrid

To use the OAuth2 hybrid flow to obtain an authorization code and an ID token, the client first sends an authorization request to the OAuth2 provider. The request should include the code and id_token response types.

The OAuth2 provider will then return an authorization code and an ID token to the client, either in the response body or as fragment parameters in the redirect URL, depending on the response mode specified in the request. The client can then use the authorization code to obtain an access token by sending a token request to the OAuth2 provider.

The ID token can be used to verify the identity of the authenticated user, as it contains information such as the user's name and email address. The ID token is typically signed by the OAuth2 provider, so the client can verify its authenticity using the provider's public key.

oauth2c https://oauth2c.us.authz.cloudentity.io/oauth2c/demo \
  --client-id cauktionbud6q8ftlqq0 \
  --client-secret HCwQ5uuUWBRHd04ivjX5Kl0Rz8zxMOekeLtqzki0GPc \
  --response-types code,id_token \
  --response-mode form_post \
  --grant-type authorization_code \
  --auth-method client_secret_basic \
  --scopes openid,email,offline_access

Learn more about the hybrid flow

Client credentials

This grant type involves the client providing its own credentials to the OAuth2 server, which then returns an access token. This grant type is typically used for server-to-server communication, where the client is a trusted server rather than a user.

oauth2c https://oauth2c.us.authz.cloudentity.io/oauth2c/demo \
  --client-id cauktionbud6q8ftlqq0 \
  --client-secret HCwQ5uuUWBRHd04ivjX5Kl0Rz8zxMOekeLtqzki0GPc \
  --grant-type client_credentials \
  --auth-method client_secret_basic \
  --scopes introspect_tokens,revoke_tokens

Learn more about the client credentials flow

Refresh token

This grant type involves the client providing a refresh token to the OAuth2 server, which then returns a new access token.

oauth2c https://oauth2c.us.authz.cloudentity.io/oauth2c/demo \
  --client-id cauktionbud6q8ftlqq0 \
  --client-secret HCwQ5uuUWBRHd04ivjX5Kl0Rz8zxMOekeLtqzki0GPc \
  --grant-type refresh_token\
  --auth-method client_secret_basic \
  --refresh-token $REFRESH_TOKEN

Note In order to use this command, you must first set the REFRESH_TOKEN environment variable

Show example

sh export REFRESH_TOKEN=`oauth2c https://oauth2c.us.authz.cloudentity.io/oauth2c/demo \ --client-id cauktionbud6q8ftlqq0 \ --client-secret HCwQ5uuUWBRHd04ivjX5Kl0Rz8zxMOekeLtqzki0GPc \ --response-types code \ --response-mode query \ --grant-type authorization_code \ --auth-method client_secret_basic \ --scopes openid,email,offline_access \ --silent | jq -r .refresh_token`

Learn more about the refresh token flow

Password

This grant type involves the client providing the user's username and password to the OAuth2 server, which then returns an access token. This grant type should only be used in secure environments, as it involves sending the user's credentials to the OAuth2 server.

oauth2c https://oauth2c.us.authz.cloudentity.io/oauth2c/demo \
  --client-id cauktionbud6q8ftlqq0 \
  --client-secret HCwQ5uuUWBRHd04ivjX5Kl0Rz8zxMOekeLtqzki0GPc \
  --grant-type password \
  --username demo \
  --password demo \
  --auth-method client_secret_basic \
  --scopes openid

[Learn more about the password flow](https://cloudentity.com/developers/basics/oauth-grant-types/resource-owner-password-credenti