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.
- 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)
To install oauth2c, you have several options depending on your operating
system.
On Mac, you can install oauth2c using brew by running the following command:
brew install cloudentity/tap/oauth2cOn 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 latestAlternatively, you can check the packages page for specific instructions on installing oauth2c using a package manager.
To compile oauth2c from source using go. To do this run the following
command:
go install github.com/cloudentity/oauth2c@latestYou can also download a pre-built binary from the releases page.
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 usernameoauth2c 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/callbackas 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.
Here are a few examples of using oauth2c with different grant types and client authentication methods:
NOTE: The authorization code, implicit, hybrid and device grant flows require browser and user authentication.
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_basicLearn more about authorization code flow
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_accessLearn more about implicit flow
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_accessLearn more about the hybrid flow
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_tokensLearn more about the client credentials flow
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_TOKENNote 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
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 openidLearn more about the password flow
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_accessLearn more about the device flow
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":"jdoe@example.com"}'Learn more about the jwt bearer flow
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_tokenNote 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
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_tokensLearn more about client secret basic
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_tokensLearn more about client secret post
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_tokensLearn more about client secret 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_tokensLearn more about private key jwt
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_tokensLearn more about tls client auth
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 \
--pkceLean more about none with PKCE
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-objectRequesting 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}}}'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 \
--pkceLearn more about authorization code flow with pkce
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_accessSigned 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.jsonPushed 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 \
--parDPoP, 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 \
--dpopRich 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"}]'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.pemIf 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/authorizeoauth2c is released under the
Apache v2.0.
We welcome contributions! If you have an idea for a new feature or have found a bug, please open an issue on GitHub.