DOCSEARCHbyAlgolia
Submit Docs

oauth2c

repository·master·Indexed 21 days ago

https://github.com/secureauthcorp/oauth2c

A command-line tool for interacting with OAuth 2.0 authorization servers. It supports various grant types including authorization code, implicit, hybrid, client credentials, refresh token, password, device, JWT bearer, and token exchange. The tool provides support for OIDC, OIDF FAPI, and JWT profiles, as well as extensions such as PKCE, JARM, PAR, DPoP, and RAR.

Tokens
10.8K
Snippets
27
Records
29
Agent score
75%

What's inside oauth2c

  1. Basic usage of OAuth2c

    master

    To interact with an OAuth 2.0 authorization server, run the command followed by the issuer URL and any necessary flags:

    oauth2c [issuer url] [flags]

    For flows that require a browser (like authorization code), oauth2c will automatically open a browser and start a local HTTP server to handle the callback.

    Important: To ensure browser-based flows work, you must add http://localhost:9876/callback as a valid redirect URL in your OAuth client configuration.

    If you are using oauth2c in a CI/CD pipeline where interactive prompts are not possible, use the --silent flag to suppress output.

    oauth2c [issuer url] [flags]

  2. Install OAuth2c on Mac, Linux, or from source

    master

    You can install oauth2c using several methods depending on your environment:

    macOS

    Use Homebrew:

    brew install cloudentity/tap/oauth2c

    Linux

    Use the official installation script:

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

    Compile from source

    If you have Go installed, you can compile it directly:

    go install github.com/cloudentity/oauth2c@latest

    Alternatively, pre-built binaries are available on the releases page.

    brew install cloudentity/tap/oauth2c

  3. Supported OAuth2 Grant Types in oauth2c

    master

    The oauth2c CLI supports the following grant types via the --grant-type flag. The specific flow executed depends on this value:

    • authorization_code: Standard authorization code flow.
    • implicit: Implicit grant flow.
    • client_credentials: Client credentials flow.
    • password: Resource owner password credentials flow.
    • refresh_token: Refresh token flow.
    • jwt_bearer: JWT bearer grant flow.
    • token_exchange: Token exchange flow.
    • device: Device authorization flow.

  4. Use the Authorization Code grant flow

    master

    The Authorization Code grant flow is used to obtain access tokens by redirecting a user to an authorization server. The flow follows these steps:

    1. Request Authorization: Depending on configuration, the tool either performs a Pushed Authorization Request (PAR) or a standard authorization request. If PKCE is enabled, a code_verifier and code_challenge are generated.
    2. User Authentication: The tool provides an authorization URL. You must navigate to this URL in a browser to authenticate.
    3. Callback Handling: The tool waits for the authorization server to send the callback (containing the code) to the configured RedirectURL.
    4. Token Exchange: The tool automatically exchanges the obtained authorization code for an access token using the token endpoint, including the code_verifier if PKCE was used.

    If clientConfig.PAR is enabled, the tool first executes a PAR request to secure the authorization request.

    // Note: This is a programmatic representation of the CLI flow logic.
// The CLI automates the following sequence:
// 1. Request PAR (if enabled) or Request Authorization
// 2. Wait for callback at RedirectURL
// 3. Exchange code for token via oauth2.RequestToken
//    - Uses oauth2.WithAuthorizationCode(code)
//    - Uses oauth2.WithRedirectURL(redirect_url)
//    - Uses oauth2.WithCodeVerifier(verifier) if PKCE is active

  5. Use the Device Grant Flow

    master

    The Device Grant Flow (Device Authorization Grant) allows a CLI or device with limited input capabilities to obtain an access token. The process follows these steps:

    1. Request Device Authorization: The client requests a device code and a verification URI from the OAuth2 server.
    2. User Authentication: The user is presented with a verification_uri (and sometimes a user code) to visit in a web browser to authorize the request.
    3. Polling: The CLI automatically polls the token endpoint using the device_code at a specified interval (defaulting to 5 seconds if not provided by the server).
    4. Token Exchange: Once the user completes the authorization in the browser, the polling succeeds and the CLI exchanges the device code for an access token.

    During polling, the CLI handles specific OAuth2 error codes like authorization_pending and slow_down by continuing to wait or adjusting the polling frequency.

    // Note: This is a conceptual representation of the internal flow logic
// used by the OAuth2c CLI for the Device Grant.

// 1. Request authorization
authReq, authRes, err := oauth2.RequestDeviceAuthorization(ctx, clientConfig, serverConfig, httpClient)

// 2. User visits the URI
verificationURI := authRes.VerificationURI

// 3. Polling loop (internal to the CLI)
// The CLI waits for the user to authorize via the browser...

// 4. Exchange for token
tokenReq, tokenRes, err := oauth2.RequestToken(ctx, clientConfig, serverConfig, httpClient, oauth2.WithDeviceCode(authRes.DeviceCode))

  6. Use the Implicit Grant Flow

    master

    The Implicit Grant Flow is used to obtain an access token directly from the authorization endpoint without an intermediate code exchange. This flow is typically used by client-side applications. The process involves:

    1. Requesting Authorization: The CLI constructs an authorization request and provides a URL for the user to visit in a browser.
    2. User Authentication: The user authenticates with the OAuth2 server via the browser.
    3. Callback Handling: The CLI waits for the server to redirect the user back to the configured callback URL, which contains the access token in the URL fragment or form parameters.
    4. Token Extraction: The CLI extracts the token payload and displays the result.
    // This is a conceptual representation of the Implicit Grant Flow execution
// The CLI handles the following sequence:
// 1. Log 'Implicit Flow'
// 2. Request authorization via oauth2.RequestAuthorization
// 3. Display Authorization URL
// 4. Wait for callback via oauth2.WaitForCallback
// 5. Parse token via oauth2.NewTokenResponseFromForm
// 6. Print the resulting token payload

  7. Use the oauth2c CLI to authorize with an OAuth2 provider

    master

    The oauth2c CLI is used to perform various OAuth2 grant flows. You can initiate a flow by providing an issuer URL or a path to a JSON configuration file as the primary argument. If a JSON file is provided, its contents are merged with any flags passed via the command line.

    Basic Usage: oauth2c [issuer_url_or_config_file_path]

    Workflow:

    1. The CLI attempts to fetch OpenID Connect configuration from the provided issuer URL.
    2. If not in --silent or --no-prompt mode, the CLI will prompt you to confirm or adjust the client configuration.
    3. The CLI executes the requested grant-type flow.
    4. Upon success, the result (typically containing tokens) is printed to stdout as a JSON object.
    # Using an issuer URL
oauth2c https://auth.example.com

# Using a JSON configuration file
oauth2c config.json

  8. Use the Hybrid grant type

    master

    The hybrid flow obtains both an authorization code and an ID token. The ID token can be used to verify the identity of the authenticated user. The response mode determines if the tokens are returned in the response body or as fragment parameters in the redirect URL.

    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

  9. Use the Password grant type

    master

    The password grant type involves providing a username and password directly to the OAuth2 server. This should only be used in secure environments.

    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

  10. Use the Refresh Token grant type

    master

    This grant type uses a refresh token to obtain a new access token. You must first set the REFRESH_TOKEN environment variable before running the command.

    # Set the environment variable first
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`

# Use the 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

  11. Use the Client Credentials grant type

    master

    The client credentials grant type is used for server-to-server communication where the client is a trusted server rather than a user. The client provides its own credentials to obtain an access token.

    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

  12. Use the Authorization Code grant type

    master

    The authorization code grant type is a two-step process used typically in server-side applications. The user first grants permission, and then the client exchanges the authorization code for an access token. Note that this flow (along with implicit, hybrid, and device) requires browser and user authentication.

    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