what is the callback url

[jagan]

what is the callback url

[Theodora Boudale]

Hi jagan and welcome to the community!

Are you referring to the Callback URL field in an OAuth consumer?

This is the URL where users are redirected after OAuth authorization for the consumer.

For example, if you request authorization from the end user by sending their browser to:

https://bitbucket.org/site/oauth2/authorize?client_id={client_id}&response_type=code

then after the user grants access they will get redirected to the Callback URL.

The callback will include the ?code={} query parameter that you can swap for an access token.

Please also see the following info from our documentation:

Callback URL: Required for OAuth 2.0 consumers.

When making requests you can include a call back URL in the request:

• If you do include the URL in a request it must be appended to the same URL configured in the consumer. So if your consumer callback URL is example.com/add-on the URL in your request must be something similar to example.com/add-on/function.

• If you don't include the URL in the request we redirect to the callback URL in the consumer.

Documentation:

• https://support.atlassian.com/bitbucket-cloud/docs/use-oauth-on-bitbucket-cloud/

You can also find more info about OAuth consumers on this page.

Kind regards,
Theodora

[Hendriekus Roux]

@jagan this is an area that people struggle with a lot.  The callback is part of the authorization leg of the OAuth.  You need to have a contextual understanding of where in the process the callback fits, to fully know what it is.  The OAuth process is:

1. Create an Oauth app in the called_application, e.g., 
   1. Jira - the objective is to obtain an authorization URL
   2. You fiddle-faff this a little, until you have the following parameters:
      1. client_id (from the Jira OAuth app)
      2. scope (you select this for how much access to grant in your Jira)
      3. redirect_uri aka callback (whatch this space)
      4. response_type=code
      5. state (watch this space)
      6. prompt=consent
2. Once you have this together, you submit it via a browser address
   1. It calls Jira first and takes you through an authentication and indication of what project you are accessing.
   2. The URL "returns" with a very long codified thinamagic in the browser.
   3. In the background it calls the redirect_uri and delivers a little nugget called the "code".  This is a step prior to obtaining the "token", usually on an address related to the calling_application, e.g. make.com, n8n, google, etc.

The black magic is locked into the callback (redirect_uri) and if you open the lid, the following can be seen:

1. Input (that comes into the URI of your callback in response to your browser submission) that bears the "code" (from Jira) that decided (based on your courteous login, i.e., that middle step) to authorize you.
2. Depending on your (callback) setup, it returns to the browser (which is what the coding behind the redirect URL does, i.e., it decides what to do) and what to do is based on the routing of the web app that powers the callback.
   1. It can simply return the code to you with a message and some sparklers 
   2. Or (if you control the callback URI) use the code to obtain the token and do other things before you return the "webhook" ack.
   3. To get the token, another call has to be made to the called_application
      1. the authorization_code (the "code")
      2. grant_type=authorization_code
      3. code (that long thing you received in the last call)
      4. redirect_uri (same olde callback, which will understand the swing on the grant_type)
      5. client_id (your name tag)
      6. client_secret (your secret hand-shake)
      7. code_verifier (optional - proof key for code exchange)
         1. code_verifier and code_challence (SHA256 of former)
         2. code_challenge goes in the initial request
         3. code_verifier is sent when exchanging the code for tokens.
   4. Once it has the token, it makes it available to other applications that call the Jira API, so they don't get booted.
3. Your last step in the Oauth is to obtain the token and use it (for the duration of its lifespan) to access the Jira API, after which you go through a renewal call, the two-step, that you do until you no longer need the token.

The state parameter is just a code you generate via some sha256 generator to use in your first call.  The callback URI (when responding) includes that state sequence so that you (as the caller) can inspect to know it is the same responder to whom you enquired.

Pardon the long-windedness, but I hope it sheds enough light.