gsqlcmd Authentication Options

gsqlcmd Authentication Options

/accessToken=<token>

Use this option to set an OAuth1/OAuth2 access token.

You can set the OAuth2 token type using the /tokenType option. The default value is "Bearer".

For example:

/accessToken=12345 /tokenType=Bearer

/accessTokenUrl=<URL>

Use this option to set an OAuth1 service-specific URL to get an access token.

/auth=Auto | None | Basic | Windows | Forms | OAuth1 | OAuth2 | Custom

Use this option to define the authentication method: Auto, None, Basic, Windows, Forms, OAuth1, OAuth2, or Custom.

For example:

gsqlcmd download https://localhost/crm/contacts /auth=Forms /username=user /password=pass

You can try to omit the authentication method specifying a user name and password only like

gsqlcmd download https://localhost/crm/contacts /username=user /password=pass

In this case, gsqlcmd tries to detect the appropriate method automatically.

To force using the two-phase OAuth1 method, specify the /consumerKey and /consumerSecret options like

gsqlcmd download https://website.com/api/get-quotes /consumerKey=app /consumerSecret=appSecret

You can authorize the request in an interactive mode using the /interactive option like

gsqlcmd download https://localhost/crm/contacts /interactive

/authCode=<code>

This option is a synonym of the /code option.

/authorizationHeader=<value>

Use this option to specify the authorization header of the custom authentication provider.

For example:

"/authorizationHeader=Bearer 12345"

The example above is equivalent to

"/header=Authorization: Bearer 12345"

/authUri=<URL>

This option is a synonym of the /authorizationUrl option.

It is used to load authorization URLs from client configuration files, for example, exported from Google.

/authorizationUrlFormat=<URL format>

Use this option to customize the format of an OAuth2 authorization URL.

The default value:

{authorization_url}?scope={scope}&client_id={client_id}&response_type={response_type}&redirect_uri={redirect_uri}

/authorizationUrl=<URL>

Use this option to specify an OAuth1/OAuth2 authorization URL or a root URL of a web service with the Forms authentication.

For example:

/authorizationUrl=https://accounts.google.com/o/oauth2/auth

gsqlcmd detects the Forms authentication root URLs successfully in most cases. So, try to set it when the Forms authentication fails.

/callback=<URI>

Use this option to specify a callback URI of the registered OAuth1 application.

For example:

/callback=https://www.savetodb.com/

/clientId=<clientId>

Use this option to set a clientId value of the registered OAuth2 application.

For example:

gsqlcmd download https://website.com/api/get-quotes /clientId=myapp /clientSecret=mypassword

gsqlcmd uses this value with the OAuth1 authentication also if the /consumerKey option is not specified.

/clientJson=<filename>

Use this option to specify a file with the client credentials and the required authentication information.

For example:

gsqlcmd get-token /clientJson=client_secret.json /tokenJson=access_token.json ^
                  /scope=https://www.googleapis.com/auth/webmasters.readonly

Services can allow exporting such files from registered application pages.

For example, a Google Search Console client secret file looks like

{"installed":{
    "client_id":"123456789012-abcdefghijklmnopqrstuvwxyz123456.apps.googleusercontent.com",
    "project_id":"searchconsoleapi-123456",
    "auth_uri":"https://accounts.google.com/o/oauth2/auth",
    "token_uri":"https://oauth2.googleapis.com/token",
    "auth_provider_x509_cert_url":"https://www.googleapis.com/oauth2/v1/certs",
    "client_secret":"Abcdefghijklmnopqrstuvwx",
    "redirect_uris":["urn:ietf:wg:oauth:2.0:oob","http://localhost"]
}}

If you prepare such files manually, you can split settings using the /clientJson and /serviceJson options.

You can use plain text instead of JSON. For example, the settings shown above can look like

client_id=123456789012-abcdefghijklmnopqrstuvwxyz123456.apps.googleusercontent.com
project_id=searchconsoleapi-123456
auth_uri=https://accounts.google.com/o/oauth2/auth
token_uri=https://oauth2.googleapis.com/token
auth_provider_x509_cert_url=https://www.googleapis.com/oauth2/v1/certs
client_secret=Abcdefghijklmnopqrstuvwx
redirect_uris=urn:ietf:wg:oauth:2.0:oob,http://localhost

/clientSecret=<clientSecret>

Use this option to set a clientSecret value used with the OAuth2 authentication scheme.

For example:

gsqlcmd download https://website.com/api/get-quotes /clientId=myapp /clientSecret=mypassword

gsqlcmd uses this value with the OAuth1 authentication also if the /consumerSecret option is not specified.

/code=<code>

Use this option to set an OAuth2 authorization code obtained from a browser to skip acquiring such code using a built-in gsqlcmd browser.

For example:

/code=12345

/consumerKey=<consumerKey>

Use this option to set a consumerKey value of the registered OAuth1 application.

For example:

gsqlcmd download https://website.com/api/get-quotes /consumerKey=app /consumerSecret=appSecret

/consumerSecret=<consumerSecret>

Use this option to set a consumerSecret value of the registered OAuth1 application.

For example:

gsqlcmd download https://website.com/api/get-quotes /consumerKey=app /consumerSecret=appSecret

Use this option to set a cookie used with the Forms or Custom authentication methods.

For example:

gsqlcmd download https://website.com/api/get-quotes /cookie=.ASPXFORMSAUTH=D3A...

You can use the /cookieFile option to define the cookie in a file instead of the inline parameter.

/cookieFile=<filename>

Use this option to set a file with a cookie used with the Forms or Custom authentication methods.

For example:

gsqlcmd download https://website.com/api/get-quotes /cookieFile=cookie.txt

The cookie file should contain a cookie value only. For example:

.ASPXFORMSAUTH=D3A...

gsqlcmd updates the cookie file when the service returns an updated cookie.

To avoid updating the cookie file, use the /options option instead. For example:

gsqlcmd download https://website.com/api/get-quotes /options=options.txt

In this case, you have to name the value in the file. So, the sample options.txt should look like

cookie=.ASPXFORMSAUTH=D3A...

/expiresIn=<seconds>

Use this option to set a token expiration time in seconds.

For example:

/expiresIn=3600

gsqlcmd uses this value to refresh expired tokens automatically using the date and time of the file specified with the /tokenJson option.

Usually, you do not need to set it manually as the exported token file contains this value.

The /validTo option has a higher priority.

/grantType=<type>

Use this option to specify a required grant type.

For example:

/grantType=authorization_code

OAuth2 defines the following types: authorization_code, client_credentials, password, and refresh_token.

However, OAuth2 allows extended types also. So, refer to the service documentation.

/getTokenBodyFormat=<body format>

Use this option to customize the body of an OAuth2 getting token request.

The default value:

grant_type={grant_type}&client_id={client_id}&client_secret={client_secret}&redirect_uri={redirect_uri}&code={code}

/getTokenUrl=<URL>

Use this option to set the URL of an OAuth2 getting token request.

gsqlcmd uses the /token_uri value by default if the value is not specified.

/getTokenUrlFormat=<URL format>

Use this option to customize the URL of an OAuth2 getting token request.

The default value:

{get_token_url}

/interactive[=true | false]

Use this option to allow authorizing the request in an interactive mode.

For example:

gsqlcmd download https://localhost/crm/contacts /interactive

This mode does not require additional parameters for the Basic, Windows, and Forms authentication schemes.

To use it with the OAuth1, OAuth2, or the Custom authentication schemes, specify the required client and service settings.

For example:

gsqlcmd download https://localhost/crm/contacts /interactive /clientJson=client.txt /serviceJson=service.txt /tokenJson=token.json

/oauthExpiresIn=<seconds>

Use this option to set an OAuth1 access token expiration time in seconds.

Usually, you do not need to set it manually as the exported token file contains this value.

gsqlcmd uses this value to refresh expired tokens automatically using the date and time of the file specified with the /tokenJson option.

The /validTo option has a higher priority.

/oauthSessionHandle=<value>

Use this option to set an OAuth1 session handle value.

Usually, you do not need to set it manually as the exported token file contains this value.

/oauthToken=<token>

Use this option to set an OAuth1 access token.

Usually, you do not need to set it manually as the exported token file contains this value.

/oauthTokenSecret=<token secret>

Use this option to set an OAuth1 access token secret.

Usually, you do not need to set it manually as the exported token file contains this value.

/password=<password>

Use this option to set a password for web resources protected with the Basic, Windows, or Forms authentication schemes.

For example:

gsqlcmd download https://localhost/crm/contacts /auth=Forms /username=user /password=pass

/redirectUri=<URI>

Use this option to specify a redirect URI of the registered OAuth2 application.

For example:

/redirectUri=urn:ietf:wg:oauth:2.0:oob

gsqlcmd also uses this value as a default for OAuth1 authentication if the /callback option has no value.

/redirectUris=<URI>

This option is a synonym of the /redirectUri option used to import URIs from files specified with the /clientJson option.

/refreshToken=<token>

Use this option to set an OAuth2 refresh token used to update an expired access token.

For example:

/refreshToken=1/ABCDEFGHIJKLMNOPQRST-abcdefghijklmnopqrstuv

Usually, you do not need to set it manually as the exported token file contains this value.

/refreshTokenBodyFormat=<body format>

Use this option to customize the body of an OAuth2 refresh token request.

The default value:

refresh_token={refresh_token}&client_id={client_id}&client_secret={client_secret}&grant_type={grant_type}

/refreshTokenUrl=<URL>

Use this option to set the URL of an OAuth2 refresh token request.

gsqlcmd uses the /token_uri value by default if the value is not specified.

/refreshTokenUrlFormat=<URL format>

Use this option to customize the URL of an OAuth2 refresh token request.

The default value:

{refresh_token_url}

/requestTokenUrl=<URL>

Use this option to set an OAuth1 service-specific URL to request a token.

/responseType=<type>

Use this option to specify an OAuth2 response type.

For example:

/responseType=code

OAuth2 defines two response types: code and token.

However, OAuth2 allows services to define extended types also. So, refer to the service documentation.

/revokeTokenBodyFormat=<body format>

Use this option to customize the body of an OAuth2 revoking token request.

The default value:

token={refresh_token}

/revokeTokenUrl=<URL>

Use this option to set the URL of an OAuth2 revoking token request.

/revokeTokenUrlFormat=<URL format>

Use this option to customize the URL of an OAuth2 revoking token request.

The default value:

{revoke_token_url}

/scope=<scope>

Use this option to specify the required scope of an OAuth2 authentication scheme.

Find the scopes in the target service API documentation.

Below is an example for Google Search Console:

gsqlcmd get-token /clientJson=client_secret.json /tokenJson=access_token.json ^
                  /scope=https://www.googleapis.com/auth/webmasters.readonly

/serviceJson=<filename>

Use this option to specify a file with the service options instead of inline values.

For example:

gsqlcmd ... /clientJson=client.json /serviceJson=service.json /tokenJson=token.json ...

Services can allow exporting client and service settings in a single file, usually used with the /clientJson option.

So, this option is useful to separate client and service options if you prepare the files manually.

You can use a JSON or plain text format.

Below is a suggested content of the service.txt file for Zoho CRM that rewrites the default OAuth2 format values:

authorization_url_format={authorization_url}?scope={scope}&client_id={client_id}&response_type=code&access_type=offline&redirect_uri={redirect_uri}
authorization_url=https://accounts.zoho.com/oauth/v2/auth

get_token_url_format={accounts-server}/oauth/v2/token
get_token_body_format=grant_type=authorization_code&client_id={client_id}&client_secret={client_secret}&redirect_uri={redirect_uri}&code={code}

refresh_token_url_format={accounts-server}/oauth/v2/token?refresh_token={refresh_token}&client_id={client_id}&client_secret={client_secret}&grant_type=refresh_token
refresh_token_body_format=

revoke_token_url_format={accounts-server}/oauth/v2/token/revoke?token={refresh_token}
revoke_token_body_format=

/tokenFields=<fields>

Use this option to define the field list saved in the OAuth1/OAuth2 token file explicitly.

For example:

/tokenFields=access_token,refresh_token,token_type,expires_in,valid_to

Below is a sample for Zoho CRM that has additional fields:

/tokenFields=location,accounts-server,api_domain,access_token,refresh_token,token_type,expires_in,valid_to

In most cases, gsqlcmd detects such fields automatically. Also, it creates such lists automatically when loading an actual token file.

/tokenJson=<file>

Use this option to specify a file with access and refresh tokens.

gsqlcmd updates such files automatically when acquiring or refreshing tokens, for example, in the get-token and refresh-token modes.

For example:

gsqlcmd refresh-token /clientJson=client_secret.json /tokenJson=access_token.json

Below is an example of the token file acquired from the Google Search Console API:

{
  "access_token": "ya29.abcdefghijklmnopqrstuv-1234567890123456789-abcdefghijklmnopqrstu_123456789012345678-abc-abcdefghijklmnopqrstuvwx-1234567890123",
  "expires_in": 3600,
  "refresh_token": "1/ABCDEFGHIJKLMNOPQRST-abcdefghijklmnopqrstuv",
  "scope": "https://www.googleapis.com/auth/webmasters.readonly",
  "token_type": "Bearer"
}

/tokenType=<type>

Use this option to specify an OAuth2 token type.

For example:

/accessToken=12345 /tokenType=Bearer

The "Bearer" is a default value.

This option also requires an access token specified with the /accessToken or /tokenJson option.

Alternatively, you can set the Authorization header using the /header option directly, like

"/header=Authorization: Bearer 12345"

/tokenUri=<URL>

Use this option to set a URL used by default to acquire and refresh an OAuth2 access token.

For example:

/token_uri=https://oauth2.googleapis.com/token

This option is useful to load the service URLs from the client application files exported, for example, from Google.

If you configure the service manually, you can define the /getTokenUrl and /refreshTokenUrl options instead.

/urlParameters=<value>

Use this option to specify the URL parameters of the custom authentification method.

For example:

gsqlcmd download https://localhost/crm/contacts /urlParameters=api_key=key

The actual URL, in this case, looks like

https://localhost/crm/contacts?api_key=key

/username=<username>

Use this option to set a username for web resources protected with the Basic, Windows, or Forms authentication schemes.

For example:

gsqlcmd download https://localhost/crm/contacts /username=user /password=pass

If the tool cannot get data using the credentials, try to specify the authentication method using the /auth option manually like

gsqlcmd download https://localhost/crm/contacts /auth=Forms /username=user /password=pass

/validTo=<datetime>

Use this option to set the time when the OAuth1/OAuth2 token expires.

For example:

/validTo=2021-03-10T16:36:15.850Z

gsqlcmd uses this value to refresh tokens automatically.

Usually, you do not need to set it manually as the exported token file contains this value.