IdentityServer4 - What is the difference between 'RedirectUri' and 'ReturnUrl' - identityserver4

Question

I'm new to both Identity Server and OAuth 2.0 and am struggling to understand what is happening with each network request after I login.
I have set up a very basic authorization code grant login process with identity server that results in the following series of network requests...
The user attempts to access a resource with the [Authorize] attribute on the client (/home/secret)
They are redirected to the login screen
They login
They can now access the protected resource
I'm struggling to understand what is happening at the point the callback url is triggered.
I understand that redirect_uri is an OAuth term that refers to an address on the client the authorization server (identity server in this case) will send the authorization code to (setup against a client with the setting RedirectUris). This accounts for the signin-oidc request above...
...but what about callback? This url appears to be stored as a ReturnUrl parameter after the user is challenged and redirected to the login page.
What is the difference between this ReturnUrl and the standard OAuth redirect_uri?
In OAuth tutorials I've looked at, they describe the key exchange process as follows...
Authorization server checks username and password
Sends authorization_code to redirect_uri
authorization_code, client_id and client_secret sent back from client to authorization server
authorization_code is checked. access_token sent to redirect_uri
access_token is used to access protected resource
I'm struggling to map this process to what Identity Server appears to be doing.
Any help would be much appreciated!

Answer 1

To understand the need for this parameter we must take into account that in the authorization endpoint we can obtain different types of interactions with the user and that they can also be chained one after the other before being redirected to the client application. For example, an interaction could be the presentation of a Login view and, after a successful sign-in, a Consent screen.
User interactions
The conditions of the request will be evaluated to determine the type of interaction that must be presented to the user. These are some of the possible interactions when you access to the /authorize endpoint:
The user must be redirected to the Login view.
The user must be redirected to the Consent view.
The user must be redirected to the Access Denied view.
The request prompt parameter is none but the user is not authenticated or is not active. A login_required error will be returned.
The request prompt parameter is none, consent is requires but there isn't consent yet. A consent_required error will be returned.
...
And these are some of the conditions to determine which interaction should be used:
Prompt mode (login, none, consent)
If the user is or not authenticated
If user is or not active
If client allows or not local logins
...
Where does the url parameter come from
When you configure IdentityServer4 you can configure the name of this parameter by setting the option UserInteraction.LoginReturnUrlParameter. It is also possible to configure the path of the login endpoint:
services.AddIdentityServer(options =>
{
options.UserInteraction.LoginReturnUrlParameter = "myParamName"; // default value = "returnUrl"
options.UserInteraction.LoginUrl = "/user/login"; // default value = "/account/login"
})
And the value of this parameter is the constant value AuthorizeCallback composed of the Authorize constant and "/callback":
public const string Authorize = "connect/authorize";
public const string AuthorizeCallback = Authorize + "/callback";
Where is this parameter used?
In your case your /authorize endpoint has resolved to redirect to the login view. Notice the returnUrl paremeter added to the login url:
/login?ReturnUrl=/connect/authorize/callback
We can see that this parameter is used in the model of the login view. The following code is extracted from the UI proposed by IdentityServer4 Quickstart.UI:
Login (get). Shows the login page
[HttpGet]
public async Task<IActionResult> Login(string returnUrl)
{
// build a model so we know what to show on the login page
var vm = await BuildLoginViewModelAsync(returnUrl); // returnUrl is added to the LoginViewModel.ReturnUrl property
...
return View(vm);
}
Login (post). Validate credentials and redirect to returnUrl:
[HttpPost]
public async Task<IActionResult> Login(LoginInputModel model, string button)
{
...
if (_users.ValidateCredentials(model.Username, model.Password))
{
...
await HttpContext.SignInAsync(isuser, props); // Creates the "idsrv" cookie
...
return Redirect(model.ReturnUrl); // If we come from an interaction we will end up being redirected to ReturUrl
...
}
}
But I guess your question is why doesn't the idp just redirect to the client application using the redirectUri (signin-oidc) instead of using a local returnUrl?
IdentityServer will receive the request again to re-evaluate if other interaction is necessary before redirect to the client application, for example a consent interaction. Successive requests will be authenticated since we already have a session cookie.
These callbacks to /authorize/callback will take into account additional conditions to the previous ones to determine the next interaction, for example:
If there was already consent or not
If user accepted consent
If user denied consent
...
And what about the original url? (your /home/secret)
This time we are in your client app...
The authentication middleware keeps the original request data in a HttpContext.Feature, this way it will be available later in the handler.
context.Features.Set<IAuthenticationFeature>(new AuthenticationFeature
{
OriginalPath = context.Request.Path,
OriginalPathBase = context.Request.PathBase
});
The base class AuthenticationHandler retrieves this feature in two variables:
protected PathString OriginalPath => Context.Features.Get<IAuthenticationFeature>()?.OriginalPath ?? Request.Path;
protected PathString OriginalPathBase => Context.Features.Get<IAuthenticationFeature>()?.OriginalPathBase ?? Request.PathBase;
When the user attempts to access a resource with the [Authorize] attribute on the client (/home/secret) What it does is invoke the challenge action for your remote handler.
This is the code for the challenge action for OpenIdConnectHandler. This code of the challenge is very similar in other handlers: OauthHandler, CookieAuthenticationHandler.
if (string.IsNullOrEmpty(properties.RedirectUri))
{
properties.RedirectUri = OriginalPathBase + OriginalPath + Request.QueryString;
}
So, the original path "/home/secret" is stored in the AuthenticationProperty.RedirectUri. This AuthenticationProperty is encoded in the state parameter to be sent to the /authorize endpoint.
OAuth2 establishes that if the identity provider receives this parameter, it must return the same value in the response:
state
REQUIRED if the "state" parameter was present in the client
authorization request. The exact value received from the
client.
The challenge action redirects to the idp /authorize endpoint with the OAuth2 parameters including state.
When the idp interaction finish it will redirect us back to our client application with the autentication response, which includes the state value.
The remote handler captures this callback (/signin-oidc), decodes the AuthenticationProperties and invokes the SignIn action of the SignIn scheme.
The SignIn scheme is configured in the handler options SignInScheme property or, if not configured, it will use the default scheme for this action (usually "Cookies").
The SignIn invokation occurs in the abstract base class RemoteAuthenticationHandler, base class of all remote handlers. Notice the parameter ticketContext.Properties. This properties include our original url in the RedirectUri property:
await Context.SignInAsync(SignInScheme, ticketContext.Principal, ticketContext.Properties);
The Cookie handler SignIn action creates the session cookie for our client application (it should not be confused with the SSO cookie created in the idp "idsrv") and uses the RedirectUri property to redirect to the original path: /home/secret