cloudentity/oauth2c

User-friendly OAuth2 CLI

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
      --authorization-endpoint string                       server's authorization endpoint
      --browser-timeout duration                            browser timeout (default 10m0s)
      --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-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

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

Device

This grant type is a two-step process that allows a user to grant access to their data without having to enter a username and password. In the first step, the user grants permission for the client to access their data. In the second step, the client exchanges the authorization code received in the first step for an access token. This grant type is commonly used in server-side applications, such as when accessing a device from a TV or other non-interactive device.

oauth2c https://oauth2c.us.authz.cloudentity.io/oauth2c/demo \
  --client-id cauktionbud6q8ftlqq0 \
  --client-secret HCwQ5uuUWBRHd04ivjX5Kl0Rz8zxMOekeLtqzki0GPc \
  --grant-type urn:ietf:params:oauth:grant-type:device_code \
  --auth-method client_secret_basic \
  --scopes openid,email,offline_access

Learn more about the device flow

JWT Bearer

This grant type involves the client providing a JSON Web Token (JWT) to the OAuth2 server, which then returns an access token. This grant type is typically used when the client is a trusted third-party, such as a JWT issuer.

oauth2c https://oauth2c.us.authz.cloudentity.io/oauth2c/demo \
  --client-id cauktionbud6q8ftlqq0 \
  --client-secret HCwQ5uuUWBRHd04ivjX5Kl0Rz8zxMOekeLtqzki0GPc \
  --grant-type urn:ietf:params:oauth:grant-type:jwt-bearer \
  --auth-method client_secret_basic \
  --scopes email \
  --signing-key https://raw.githubusercontent.com/cloudentity/oauth2c/master/data/rsa/key.json \
  --assertion '{"sub":"[email protected]"}'

Learn more about the jwt bearer flow

Token exchange

The token exchange OAuth2 grant flow involves the client providing an access token to the OAuth2 server, which then returns a new access token. This grant type is typically used when the client and the OAuth2 server have a pre-existing trust relationship, such as when the client is a trusted third-party.

oauth2c https://oauth2c.us.authz.cloudentity.io/oauth2c/demo \
  --client-id cauktionbud6q8ftlqq0 \
  --client-secret HCwQ5uuUWBRHd04ivjX5Kl0Rz8zxMOekeLtqzki0GPc \
  --grant-type urn:ietf:params:oauth:grant-type:token-exchange \
  --auth-method client_secret_basic \
  --scopes email \
  --subject-token $SUBJECT_TOKEN \
  --subject-token-type urn:ietf:params:oauth:token-type:access_token \
  --actor-token $ACTOR_TOKEN \
  --actor-token-type urn:ietf:params:oauth:token-type:access_token

Note In order to use this command, you must first set the SUBJECT_TOKEN and ACTOR_TOKEN environment variables

Show example

export SUBJECT_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 .access_token`

export ACTOR_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 \
  --silent | jq -r .access_token`

Learn more about the token exchange flow

Auth methods

Client Secret Basic

This client authentication method involves the client sending its credentials as part of the HTTP Basic authentication header in the request to the OAuth2 server. This method is simple and widely supported, but it is less secure than other methods because the client secret is sent in the clear.

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 client secret basic

Client Secret Post

This client authentication method involves the client sending its credentials as part of the request body in the request to the OAuth2 server. This method provides more security than the basic authentication method, but it requires the request to be sent via HTTPS to prevent the client secret from being intercepted.

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

Learn more about client secret post

Client Secret JWT

This client authentication method involves the client signing a JSON Web Token (JWT) using its client secret, and then sending the JWT to the OAuth2 server. This method provides a higher level of security than the basic or post methods, as the client secret is never sent in the clear.

oauth2c https://oauth2c.us.authz.cloudentity.io/oauth2c/demo \
  --client-id ab966ce4f2ac4f4aa641582b099c32d3 \
  --client-secret 578-WfFYfBheWb8gJpHYXMRRqR5HN0qv7d7xIolJnIE \
  --grant-type client_credentials \
  --auth-method client_secret_jwt \
  --scopes introspect_tokens,revoke_tokens

Learn more about client secret jwt

Private Key JWT

This client authentication method involves the client signing a JSON Web Token (JWT) using its private key, and then sending the JWT to the OAuth2 server. This method provides a higher level of security than the JWT methods using a client secret, as the private key is never shared with the OAuth2 server.

oauth2c https://oauth2c.us.authz.cloudentity.io/oauth2c/demo \
  --client-id 582af0afb0d74554aa7af47849edb222 \
  --signing-key https://raw.githubusercontent.com/cloudentity/oauth2c/master/data/rsa/key.json \
  --grant-type client_credentials \
  --auth-method private_key_jwt \
  --scopes introspect_tokens,revoke_tokens

Learn more about private key jwt

TLS Client Auth

This client authentication method involves the client providing its own certificate as part of the TLS handshake when connecting to the OAuth2 server. This method provides a high level of security, as the client's identity is verified using a trusted certificate authority. However, it requires the OAuth2 server to support TLS client authentication, which may not be supported by all OAuth2 providers.

oauth2c https://oauth2c.us.authz.cloudentity.io/oauth2c/demo \
  --client-id 3f07a8c2adea4c1ab353f3ca8e16b8fd \
  --tls-cert https://raw.githubusercontent.com/cloudentity/oauth2c/master/data/cert.pem \
  --tls-key https://raw.githubusercontent.com/cloudentity/oauth2c/master/data/key.pem \
  --grant-type client_credentials \
  --auth-method tls_client_auth \
  --scopes introspect_tokens,revoke_tokens

Learn more about tls client auth

None with PKCE

Public clients, such as mobile apps, are unable to authenticate themselves to the authorization server in the same way that confidential clients can because they do not have a client secret. To protect themselves from having their authorization codes intercepted and used by attackers, public clients can use PKCE (Proof Key for Code Exchange) during the authorization process. PKCE provides an additional layer of security by ensuring that the authorization code can only be exchanged for a token by the same client that initially requested it. This helps prevent unauthorized access to the token.

oauth2c https://oauth2c.us.authz.cloudentity.io/oauth2c/demo \
  --client-id db5e375e7b634095b24bbb683fcb955b \
  --response-types code \
  --response-mode query \
  --grant-type authorization_code \
  --auth-method none \
  --scopes openid,email \
  --pkce

Lean more about none with PKCE

Extensions

Request Object

The Request Object is a JWT that contains the parameters of an authorization request. It allows the request to be passed along as a single, self-contained parameter, and it can be optionally signed and/or encrypted for added security.

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 \
  --request-object

Request claims

Requesting Claims using the "claims" Request Parameter enables clients to request specific user attributes in an authorization, enhancing efficiency and security.

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,offline_access \
  --claims '{"id_token":{"email": {"essential": true}}}'

PKCE

The Proof Key for Code Exchange (PKCE) is an extension to the OAuth2 authorization code grant flow that provides additional security when authenticating with an OAuth2 provider. In the PKCE flow, the client generates a code verifier and a code challenge, which are then sent to the OAuth2 provider during the authorization request. The provider returns an authorization code, which the client then exchanges for an access token along with the code verifier. The provider verifies the code verifier to ensure that the request is coming from the same client that initiated the authorization request.

This additional step helps to prevent attackers from intercepting the authorization code and using it to obtain an access token. PKCE is recommended for all public clients, such as single-page or mobile applications, where the client secret cannot be securely stored.

oauth2c https://oauth2c.us.authz.cloudentity.io/oauth2c/demo \
  --client-id db5e375e7b634095b24bbb683fcb955b \
  --response-types code \
  --response-mode query \
  --grant-type authorization_code \
  --auth-method none \
  --scopes openid,email \
  --pkce

Learn more about authorization code flow with pkce

JARM

JWT-secured OAuth 2.0 authorization response, also known as JARM, is a method of securely transmitting authorization information in an OAuth 2.0 authorization response using JSON Web Tokens (JWT). This allows the authorization response to be verified by the client, ensuring that the information is coming from a trusted source and has not been tampered with. The JWT is signed using a secret key shared between the authorization server and the client, allowing the client to verify the authenticity of the JWT. This provides an additional layer of security to the OAuth 2.0 authorization process.

Signed JWT

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

Signed and encrypted JWT

oauth2c https://oauth2c.us.authz.cloudentity.io/oauth2c/demo \
  --client-id cauosoo2omc4fr8ai1fg \
  --client-secret ipFkA1lMomOMI_d2HcGGQ7j8oxeHFqKw3kli76g92VM \
  --response-types code \
  --response-mode query.jwt \
  --grant-type authorization_code \
  --auth-method client_secret_post \
  --scopes openid,email,offline_access \
  --encryption-key https://raw.githubusercontent.com/cloudentity/oauth2c/master/data/rsa/key.json

PAR

Pushed Authorization Requests (PAR) is an extension of the OAuth 2.0 specification that enables client applications to push the payloads of authorization requests directly to the authorization server via a PAR endpoint. This allows for more efficient and secure handling of authorization requests. PAR can be useful for client applications that require a high level of security, and may be required for compliance with certain security profiles and regulations.

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 \
  --par

Learn more about PAR

DPoP

DPoP, or Demonstration of Proof of Possession, is an extension that describes a technique to cryptographically bind access tokens to a particular client when they are issued. This is one of many attempts at improving the security of Bearer Tokens by requiring the application using the token to authenticate itself.

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 \
  --signing-key https://raw.githubusercontent.com/cloudentity/oauth2c/master/data/ps/key.json \
  --dpop

RAR

Rich Authorization Request (RAR) introduces a new parameter authorization_details that allows clients to specify their fine-grained authorization requirements using the expressiveness of JSON data structures. For example, an authorization request for a credit transfer (designated as "payment initiation" in several open banking initiatives) can be represented using a JSON object like this:

{
   "type": "payment_initiation",
   "locations": [
      "https://example.com/payments"
   ],
   "instructedAmount": {
      "currency": "EUR",
      "amount": "123.50"
   },
   "creditorName": "Merchant A",
   "creditorAccount": {
      "bic":"ABCIDEFFXXX",
      "iban": "DE02100100109307118603"
   },
   "remittanceInformationUnstructured": "Ref Number Merchant"
}

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 \
  --rar '[{"type":"payment_initiation","locations":["https://example.com/payments"],"instructedAmount":{"currency":"EUR","amount":"123.50"},"creditorName":"Merchant A","creditorAccount":{"bic":"ABCIDEFFXXX","iban":"DE02100100109307118603"},"remittanceInformationUnstructured":"Ref Number Merchant"}]'

Miscellaneous

Using HTTPs for Callback URL

You can use --callback-tls-cert and --callback-tls-key flags to specify a TLS certificate and key for the HTTPs callback redirect URL.

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 \
  --redirect-url https://localhost:9876/callback \
  --callback-tls-cert https://raw.githubusercontent.com/cloudentity/oauth2c/master/data/cert.pem \
  --callback-tls-key https://raw.githubusercontent.com/cloudentity/oauth2c/master/data/key.pem

Specifying Authorization Server's Endpoint Manually

If your authorization server does not support OIDC, you can specify the endpoint manually using flags.

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 \
  --token-endpoint https://oauth2c.us.authz.cloudentity.io/oauth2c/demo/oauth2/token \
  --authorization-endpoint https://oauth2c.us.authz.cloudentity.io/oauth2c/demo/oauth2/authorize

License

oauth2c is released under the Apache v2.0.

Contributing

We welcome contributions! If you have an idea for a new feature or have found a bug, please open an issue on GitHub.

oauth2c's Issues

Device Flow

https://cloudentity.com/developers/basics/oauth-grant-types/device/

CLI args validation

See #94

Add nix package

Having oauth2c available as a nix package would be useful!

oauth2c version provide `unknown` on both MacOS and Ubuntu 22.04 on 1.12.2

Hi, I just installed oauth2c on Ubuntu 22.04 and I've tried it out briefly on MacOS using a github runner (public) with macos-latest as the flag.

When I run oauth2c version, it prints "unknown" as indicated in the version code.

Operating System

• Ubuntu 22.04
• Github runner - macos-latest distro

Version

• oauth2c 1.12.2

Silent mode

HTTP 400: Could not determine client ID from request when authorizing from Google

Hello,

Thank you for your work on oauth2c ! I am trying to generate tokens in order to use IMAP with gmail. I followed this procedure to generate a client ID and client secret, setting up a Desktop application; and following this document, requested the "https://mail.google.com" scope with the following command:

 oauth2c "https://accounts.google.com/" \
               --client-id $(jq -r .[].client_id gc) \
               --client-secret $(jq -r .[].client_secret gc) \
               --response-types code \
               --response-mode query \
               --grant-type authorization_code \
               --auth-method client_basic \
               --scopes "https://mail.google.com"

which fails with the following output:

┌───────────────────────────────────────────────────────────────────────────────────────────┐
| Issuer URL     | https://accounts.google.com/                                             |
| Grant type     | authorization_code                                                       |
| Auth method    | client_basic                                                             |
| Scopes         | https://mail.google.com                                                  |
| Response types | code                                                                     |
| Response mode  | query                                                                    |
| PKCE           | false                                                                    |
| Client ID      | <redacted>                                                               |
| Client secret  | <redacted>                                                               |
└───────────────────────────────────────────────────────────────────────────────────────────┘

                                                                                                                                                                                               
Authorization Code Flow                                                                                    
                                                                                                                                                                                               

# Request authorization

GET https://accounts.google.com/o/oauth2/v2/auth
Query params:
  scope: https://mail.google.com
  state: QyUPE2AKvdFqqMykQeuJYF
  client_id: 745633595393-nfnn82tgaj47o7tk9s56munqs4nv794j.apps.googleusercontent.com
  nonce: QNqeFwokTBd9niFBFYmfYr
  redirect_uri: http://localhost:9876/callback
  response_mode: query
  response_type: code

Open the following URL:

https://accounts.google.com/o/oauth2/v2/auth?client_id=<redacted>&nonce=<redacted>&redirect_uri=http%3A%2F%2Flocalhost%3A9876%2Fcallback&response_mode=query&response_type=code&scope=https%3A%2F%2Fmail.google.com&state=<redacted>
Opening in existing browser session.

GET /callback                                                                                                                                                                                  
Query params:                                                                                                                                                                                  
  state: <redacted>                                                                                                                                                                
  code: <redacted>                                                                                                              
  scope: https://mail.google.com/                                                                                                                                                              
                                                                                                                                                                                               
 SUCCESS  Obtained authorization code                                                                                                                                                          


# Exchange authorization code for token

POST https://oauth2.googleapis.com/token                                                                                                                                                       
Headers:
     Content-Type: application/x-www-form-urlencoded                                                                                                                                              
Form post:                                                                                                                                                                                     
  code: <redacted>                                                                                                              
  grant_type: authorization_code                                                                                                                                                               
  redirect_uri: http://localhost:9876/callback                                                                                                                                                 
Response:                                                                                                                                                                                      
{                                                                                                                                                                                              
  "error": "invalid_request",
  "error_description": "Could not determine client ID from request."
}
                                                                                                                                                                                               
  ERROR   400: invalid_request                                                                                                                                                                                     

I have also tried using Mozilla Thunderbird's clientID and client secret (which can be found here) with the same result. Is this a bug ? I see that the clientID is not sent again in the second POST request, maybe it should be ? I am sadly rather unfamiliar with the whole oauth2 flow thing.

Thank you for any tips or pointers on how to get this to work!

Add `acr_values` flag to pass to `/authorize` call

Currently it's not possible to pass arbitrary acr_values as a query parameter to the /authorize call. Can a -- acr_values flag be added?

cc @piotrek-janus

Allow configuring audiences

It'd be nice if oauth2c would support specifying the Audience in Authorization Code, Implicit, and hybrid flows (audience URL parameter):

When performing an OAuth 2.0 Authorization Code Grant, Implicit Grant, or hybrid flow, developers can request audiences at the /oauth2/auth endpoint using the audience query parameter:

https://{project.slug}.projects.oryapis.com/oauth2/auth
  ?client_id=...
  &scope=...
  &audience=https://api.my-cloud.com/user+https://some-tenant.my-cloud.com/

The audience query parameter can contain multiple strings separated by a URL-encoded space (+ or %20). The audience values must also be URL-encoded.

Unable to use oauth2c on an Ubuntu GitHub Actions runner

When trying to use oauth2c on a GitHub Actions Ubuntu runner, having installed via:

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

The command times out due to:

/usr/bin/xdg-open: 882: www-browser: not found
/usr/bin/xdg-open: 882: links2: not found
/usr/bin/xdg-open: 882: elinks: not found
/usr/bin/xdg-open: 882: links: not found
/usr/bin/xdg-open: 882: lynx: not found
/usr/bin/xdg-open: 882: w3m: not found

The runner images already come with Chrome and other browsers installed - https://github.com/actions/runner-images/blob/main/images/linux/Ubuntu2204-Readme.md

When using the macos-latest runner and installing via Homebrew, oauth2c works correctly. Given the 10x multiplier for macOS Github Action runners it would be ideal for oauth2c to work correctly on an Ubuntu runner. I attempt to install lynx and elinks on the runner, but still had issues with timeouts.

Pushed Authorization Requests

https://cloudentity.com/developers/basics/oauth-grant-types/pushed-authorization-requests/

Make listening port for callback configurable

Basically, just make

oauth2c/cmd/oauth2.go

Lines 21 to 23 in 1fe01c5

	const (
	addr = "localhost:9876"
	)

configurable via a cli argument

When using authorization code flow --signing-key parameter is ignored.

When using oauth2c to trigger an authorization code flow, the --signing-key parameter is not used, the jwks_endpoint from the server openid-configuration is always used.

This is causing problems when the issuer is exposing a set of keys where some of them are not compatible with go-jose.

Token exchange

https://cloudentity.com/developers/basics/oauth-grant-types/token-exchange/

Enable using in scripts

This is a very useful tool which helped me to quickly play around with different OAuth2 configurations - thanks a lot!

Currently all console output goes to stdout, mixing both the token result and the diagnostic output. In --silent there is no diagnostic output whatsoever, which makes it hard to debug errors.

To enable using oauth2c in scripts please separate write all diagnostic output to stderr, leaving only the JSON with the token data on stdout. Also, it would be nice to see the login progress without dumping the token info.

CIBA

https://cloudentity.com/developers/basics/oauth-grant-types/ciba-flow/

ID token encryption

JWT verification

Discourage usage of fragment response mode

The fragment response mode is not supported, as the HTTP server cannot access the fragment part of the URL.

We should block users from trying to use fragment response mode.

TokenResponse unmarshalling error using Azure

Hi,

When using oauth2c against Azure for a authorization code flow I received the following error:

ERROR failed to parse exchange response: json: cannot unmarshal string into Go struct field TokenResponse.expires_in of type int64

Debugging the token - it looks like Azure returns the expires_in as a string:

 {
  "token_type": "Bearer",
  "expires_in": "3599",
  "ext_expires_in": "3599",
  "expires_on": "1671217329",
  "access_token": "...",
  "id_token": "...."
}

This seems to be known issue and resolved using custom unmarshalling function as seen here - https://github.com/golang/oauth2/blob/master/internal/token.go#L65

Would be good to seen something similar implemented in oauth2c.

Proxy settings aren't respected

I'm trying to use this tool in an environment where all traffic is routed via a proxy, but this tool doesn't seem to use HTTP_PROXY or HTTPS_PROXY environment variables.

Any suggestions or enhancements that need to be made? All my requests timeout as it won't get through the proxy. Thanks.

Claims request parameter

https://openid.net/specs/openid-connect-core-1_0.html#ClaimsParameter

Signed Request Object

https://openid.net/specs/openid-connect-core-1_0.html#JWTRequests

Allow passing oauth configuration instead of using the /.well-known endpoint

I have a server that supports oauth2 but doesn't have a /.well-known/openid-configuration.

I can use it with a lot of libraries by setting the token and authentication endpoints, and it works, would it be possible for this cli to accept the parameters that it gets from the endpoint via cli arguments?

IIRC that endpoint is only mandatory for oidc, not oauth2.

Force private key for signing

Right now if you provide a public key as a signing key you get an ambiguous error

ERROR   failed to create signer: failed to create a signer: go-jose/go-jose: unsupported key type/format 

We should check if a provided key for signing is a private key and if not fail with a better error.

The following example should fail with an error saying that only private keys are allowed for signing keys:

oauth2c https://oauth2c.us.authz.cloudentity.io/oauth2c/demo \
  --client-id 3f07a8c2adea4c1ab353f3ca8e16b8fd \
  --response-types code,id_token \
  --response-mode form_post.jwt \
  --grant-type authorization_code \
  --auth-method tls_client_auth \
  --scopes openid,email,offline_access \
  --tls-cert https://raw.githubusercontent.com/cloudentity/oauth2c/master/data/cert.pem \
  --tls-key https://raw.githubusercontent.com/cloudentity/oauth2c/master/data/key.pem \
  --signing-key https://raw.githubusercontent.com/cloudentity/oauth2c/master/data/public.json \
  --encryption-key https://oauth2c.us.authz.cloudentity.io/oauth2c/demo/.well-known/jwks.json \
  --request-object \
  --pkce \
  --par

This one should still work fine:

oauth2c https://oauth2c.us.authz.cloudentity.io/oauth2c/demo \
  --client-id 3f07a8c2adea4c1ab353f3ca8e16b8fd \
  --response-types code,id_token \
  --response-mode form_post.jwt \
  --grant-type authorization_code \
  --auth-method tls_client_auth \
  --scopes openid,email,offline_access \
  --tls-cert https://raw.githubusercontent.com/cloudentity/oauth2c/master/data/cert.pem \
  --tls-key https://raw.githubusercontent.com/cloudentity/oauth2c/master/data/key.pem \
  --signing-key https://raw.githubusercontent.com/cloudentity/oauth2c/master/data/key.json \
  --encryption-key https://oauth2c.us.authz.cloudentity.io/oauth2c/demo/.well-known/jwks.json \
  --request-object \
  --pkce \
  --par

None client authentication method

accept callback also via https://localhost:9877

Most corporate systems enforce nowadays https, which is good. Unfortunately that means, that they replace redirect URLs to point to https too.
So the whole flow is broken, as the actual redirect call from the auth system that reaches the local system will never be read by the server started by auth2c.

I did not find any option to let the locally started server to react on https:// (needs self-signed certificates?)

Any chance to add this?

Unable to match command output after in v.1.12.0

Hello 👋 . I'm a maintainer for the Homebrew project. While packaging v1.12.0 of oauth2c, we are encountering a test failure matching the "Authorization completed" output. It appears this was changed in #77. Our test is not just receiving the access token response instead of the full output. Is there any way to resolve this? Thanks!

Relates to Homebrew/homebrew-core#147883

Windows binaries

Thanks for a great tool.

Would you consider adding Windows binaries to the Github Releases page? This would enable me to reference it from a scoop.sh repository and make installation and updating easy for users who don't have the go compilers and runtime available.

Thanks.

Make timeout configurable using flags

Right now the HTTP client timeout is hardcoded.

We should make it configurable using flags.

Ctrl-C not aborting

I noticed that Ctrl-C doesn't abort while waiting for the callback to the redirect URL. If the redirect URL is not allowed for the OAuth2 client, then this tool will wait forever.

Please add support for aborting via Ctrl-C

Webserver for callback refuses connection

Hello,

I just installed the tool using this command

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

I successfully started the tool. However, the local webserver refuses connection. When asked to open the URL, callback endpoint doesn't work. telneting to it indicates a refused connection:

$ telnet localhost 9876
Trying 127.0.0.1...
telnet: Unable to connect to remote host: Connection refused

Encrypted Request Object

https://openid.net/specs/openid-connect-core-1_0.html#JWTRequests

Homebrew Integration

Hello!

Could you possible add Homebrew integration (in core or in a homebrew tap) so I can use brew to install and update oauth2c?

There are different ways to do this, but I personally use GoReleaser to generate the Homebrew formula and commit it to my Homebrew tap repo when I push to GitHub.

Docs: GoReleasor Homebrew Integration, GoReleasor GitHub Actions Integration

See how this works in a small project of mine: See my .goreleasor, my GitHub workflow, and the generated formula

Support for the custom query paramters

It would be useful to add support for the query parameters passed as part of the /authorize request like login_hint, id_token_hint, idp_hint etc...

Redeeming authorization code for token fails in v1.14 (MS Entra - Web Application)

Authenticating using oauth2c when application is configured as "web" in MS Entra fails using v1.14 with the error AADSTS9002326: Cross-origin token redemption is permitted only for the 'Single-Page Application' client-type. Request origin: 'http://localhost:9876'. Trace ID:....

The same configuration works with v1.13, leading me to believe this is caused by the change introduced in #108. I suspect MS Entra errors out if the Origin header is set and the application is of "web" type instead of "single page application" type.

JARM

https://openid.net/specs/openid-financial-api-jarm.html

Microsoft authorization_code flow

Thanks for such a cool library.

I am having some trouble fixing an issue with Microsoft's code flow. It appears I need to add the code field in the token exhange. Is this something I can do just via settings of the CLI?

Thanks

 SUCCESS  Obtained authorization code


# Exchange authorization code for token

POST https://login.microsoftonline.com/common/oauth2/v2.0/token
Headers:
  Authorization: Basic NWJiZWRmZ..........................................kI2clZiT3I=
  Content-Type: application/x-www-form-urlencoded
Form post:
  grant_type: authorization_code
  redirect_uri: http://localhost:9876/callback
  code_verifier: Pi1uLA..................NO8n2tpEiARqd
Response:
{
  "error": "invalid_request",
  "error_description": "AADSTS900144: The request body must contain the following parameter: 'code'...."
}

Request Object

https://openid.net/specs/openid-connect-core-1_0.html#JWTRequests

Add timeout for login operation

unlike #61 I'd like to have a timeout for the actual login, which would also abort after the timeout if nobody called the local webserver or on other cases of the login taking too long.

Why? That would help a lot with using this tool in scripts. It should return an error if the timeout happens

JWKs generation