Originally posted by Sarah-Beth Bianchi (December 8, 2014)
How do I determine my App's Trusted URL?
The Trusted URL is simply a URL in your infrastructure that you will use to receive User ID\Key pairs. The x_target parameter that you append to your API calls must match this value in order for authentication to proceed. You should have a good idea of where this endpoint will be at the time you register the app, since the Trusted URL is a required field in the app registration request form.
The Trusted URL field is editable from within the Manage Extensibility screen for any existing domain-limited app.
Note: Universal apps must be edited in the D2L Keytool by a D2L Keytool Administrator.
If the Trusted URL value changes, or if you don't know what it will be at the time you register your app, you can put a placeholder value (e.g. https://apitesttool.desire2learnvalence.com/index.php) in place and then go back and edit this value in the Manage Extensibility tool.
Why do I receive the error "The request's 'x_target' value does not match the allowed values for this application. Contact your administrator"?
This error message indicates that your app is attempting to send authentication tokens to a location that does not match the one specified in your Trusted URL. To resolve this issue you will need to update the Trusted URL value for your app. If necessary, you can create multiple apps, each with their own Trusted URL value.
How do I update my Trusted URL?
You can easily update the Trusted URL value by editing the app record within the Manage Extensibility tool:
- Find your app in the Manage Extensibility List.
- Click the app name to reveal the app details screen.
- Click Edit.
- Change the Trusted URL and click Update.
Figure: You can change the Trusted URL field for your app in the Edit Application Record page.
Does the Trusted URL need to be the full location that is receiving the user credentials or is the domain sufficient?
The TrustedUrl needs to be the full URL.
And we really mean full URL; the query string, fragment, all of it. If you need to maintain state before and after login (which is usually the case) then you'll need to set a cookie on the user's browser before sending them to login with D2L.
Why is the Trusted URL not per domain (or prefix, etc)?
The reason for this is subtle. Let us use an an example the URL https://mysite.com/randomOtherFeature?returnUrl=<...>. Because that domain has an open redirect (i.e. a URL that takes another URL as part of the query and sends the user to it with a 302, etc.), this allows an attacker to set the x_target to https://mysite.com/randomOtherFeature?returnUrl=http://evil.com/foo.
When Brightspace redirects the user to "mysite" after login, they would send them to https://mysite.com/randomOtherFeature?returnUrl=http://evil.com/foo&x_a=<userId>&x_b=<userKey> which would then redirect the user to . Browsers often set a Referer header which is the address of the page that sent them. In this case, that header has the User Id\Key, so gets them from the Referer header.
In practice, open redirectors are very common. We made the choice to be very strict here.
Is the Trusted URL only required for obtaining the user context User Id-Key pair?
The TrustedUrl is only relevant for the login process. It is whatever you send in the x_target to Brightspace. For example, in the C# sample, the value of returnUrl here:
https://github.com/Brightspace/valence-sdk-dotnet/blob/master/samples/Basic/Basic/Controllers/HomeController.cs#L63
