The traditional URLs that work for most cases have reserved characters that throw a spanner in the works. Following Shahid's blog about Getting your ServiceNow URLs right, here are my examples to show how to make URLs that have reserved characters work fine.
Let's talk about redirection links and the parameters passed to them.
Redirection links
Direct links are the address to the target pages themselves (e.g. htt�s://<instance>.service-now.com/reviewurlparameters.do). They are useful when the users are already logged in.
They usually open without the usual left and top menus.
Redirection pages are called "navigational pages". They are forms created to direct users to the target landing pages (e.g htt�s://<instance>.service-now.com/nav_to.do?uri=<target page>). They can contain the target page which can include some parameters. Most links send to final users will be redirection links to maintain consistency whether the users are logged in or not. The most common navigation pages are: nav.do, navigator.do, navpage.do, nav_to.do and navigator_change.do. They usually open within the frame of ServiceNow left and top menus.
Navigation pages need to remain public
It is important to notice navigational pages need to remain public pages. You can ensure they stay public by checking that they are set to True on the sys_public table. This could be confusing because it creates the idea that they will give access to the target pages themselves. They don't. Even when the navigation pages are public, the system will correctly authenticate when reaching the target pages that are not set public. See the example below:
Navigational pages are key when working with SSO deep-linking, service catalog and the infamous SAML RelayState information. When SSO is enabled, multiple re-directions may happens.
If the navigation pages are not made public and SSO is enabled, when you click to logout, you would be asked to login immediately after. This is a logout loop. Normally you should be redirected to a logout page. So keep navigation pages public.
Redirection link parameters
We need the navigation pages to piggyback the target page information with the parameters encoded in a proper way.
Without the URL properly URI encoded, the final target page could lose or truncate some parameter and their values.
That could cause that form data get truncated or missing, or even opening the wrong page.
There is a trade between consistency and convenience.
Most URL works fine when the parameters do not contain reserved characters. However, if reserved characters like ?#[]@!$&'()*+,;= $&+,/:;="<> are present in the parameters data, please consider URL encoding them.
URL encoding is a mechanism for encoding information in a Uniform Resource Identifier (URI) as is often used in the submission of HTML form data in HTTP requests.
Example: This is text "._~:/?#[]@!," URL encoded looks like "._~%3A/%3F%23%5B%5D%40!%2C".
Testing the parameters passed for direct and navigational links
I have created the following ServiceNow processor to validate the parameters passed to the instance:
|
Processor |
||
|
Name |
= |
reviewurlparameters |
|
Type |
= |
script |
|
Path |
= |
reviewurlparameters |
|
Active |
= |
TRUE |
Script:
// vstringtosend contains the final text to print
var vstringtosend = "----------PASSING PARAMETERS TESTER ---------\n"
+ print_parameters(g_request.getParameterNames());
g_processor.writeOutput("text/plain", vstringtosend);
// Function will walk on the parameters to create the final string
function print_parameters(v_pnames) {
var vparam_string = "";
while (v_pnames.hasMoreElements()) {
var vkey = v_pnames.nextElement();
// To allow triple URI encoding - decode data
var vvalue = decodeURIComponent(g_request.getParameter(vkey));
// To allow tripple URI encoding - decode data
vkey = decodeURIComponent(vkey);
vparam_string += vkey + " = " + vvalue + "\n";
}
return vparam_string;
}
If have the following parameters to pass to the application:
|
Parameters name/Value |
||
|
ParA |
= |
test1 |
|
A |
= |
This is text ._~:/?#[]@!$&'()*+,;= $&+,/:;=?@"<>#%{}|\^~[]` that could cause problems |
|
ParB |
= |
test2 |
|
B |
= |
1234567879 |
Then I prepared the links to send to the instance as follow:
You could generate the final links here
|
Link |
What is the link to the instance |
|
Direct URL |
<instance>/reviewurlparameters.do?ParA=A&ParB=B |
|
Direct URL when data contains reserved characters |
<instance>/reviewurlparameters.do?ParA=urlencode(urlencode(A))+ & + ParB= + urlencode(urlencode (B)) |
|
Redirection link URL |
<instance>/nav_to.do?uri=reviewurlparameters.do%3F + urlencode (ParA=) + urlencode (urlencode (A)) + urlencode(&) + urlencode (ParB=) + urlencode (urlencode(B)) |
|
Redirection link URL when data contains reserved characters |
<instance>/nav_to.do?uri=reviewurlparameters.do%3F + urlencode (ParA=) + urlencode (urlencode (urlencode (A))) + urlencode (&) + urlencode (ParB=) + urlencode (urlencode (urlencode (B))) |
The following are the results:
|
Link |
Expected URL |
Parameters passed to the example |
Result |
|
Direct URL |
ParA=A&ParB=B |
test1=This is text ._~:/?#[]@!$&'()*+,;= $&+,/:;=? @"<>#%{}|\^~[]` that could cause problems&test2=1234567879 |
Data is truncated* Parameter test2 is missing |
|
Direct URL when data contains reserved characters |
ParA= urlencode (urlencode(A)) & ParB= urlencode(urlencode (B)) |
test1=This%2520is%2520text%2520._~%253A %252F%253F%2523%255B%255D%2540! %2524%2526%2527()*%252B%252C%253B %253D%2520%2524%2526%252B%252C %252F%253A%253B%253D%253F%2540 %2522%253C%253E%2523%2525%257B %257D%257C%255C%255E~%255B%255D %2560%2520that%2520could%2520cause %2520problems&test2=1234567879 |
It will increase the length of the link but it will work fine on all cases. URLdecode is required for the data |
|
Redirection Link URL |
urlencode (ParA=) urlencode (urlencode (A)) urlencode(&) urlencode (ParB=) urlencode (urlencode(B)) |
test1%3DThis%20is%20text%20._~%3A/ %3F%23%5B%5D%40!%24%26%27()*%2B %2C%3B%3D%20%24%26%2B%2C/ %3A%3B%3D%3F%40%22%3C%3E%23 %25%7B%7D%7C%5C%5E~%5B%5D%60 %20that%20could%20cause%20problems %26test2%3D1234567879 |
Data is truncated** and parameter test2 is missing |
|
Redirection Link URL when data contains reserved characters |
urlencode (ParA=) urlencode (urlencode (urlencode (A))) urlencode (&) urlencode (ParB=) urlencode (urlencode (urlencode (B))) |
test1%3DThis%252520is%252520text %252520._~%25253A%25252F%25253F %252523%25255B%25255D%252540!%252524 %252526%252527()*%25252B%25252C %25253B%25253D%252520%252524%252526 %25252B%25252C%25252F%25253A%25253B %25253D%25253F%252540%252522%25253C %25253E%252523%252525%25257B%25257D %25257C%25255C%25255E~%25255B %25255D%252560%252520that%252520could %252520cause%252520problems%26test2 %3D1234567879 |
The problematic parameter data needs to be URLencoded three (3) times. It requires the data to be URLdecoded to be used. |
On my example, an URL passing the parameters correctly look like this:
Here are the results that distinguish a problematic URL because the data get truncate or/and some parameters get missing:
|
Link |
Example of URL parameters passed |
Parameters received |
|
*Direct URL |
test1=This is text ._~:/?#[]@!$&'()*+,;= $&+,/:;=?@"<>#%{}|\^~[]` that could cause problems&test2=1234567879 |
test1 = This is text ._~:/? (truncated) <parameter test2 missing> |
|
**Redirection link URL |
test1%3DThis%20is%20text%20._~%3A%2 F%3F%23%5B%5D%40!%24%26%27()*% 2B%2C%3B%3D%20%24%26%2B%2C%2 F%3A%3B%3D%3F%40%22%3C%3E%23 %25%7B%7D%7C%5C%5E~%5B%5D%6 0%20that%20could%20cause%20problems %26test2%3D1234567879 |
test1 = This is text ._~:/? (truncated) <parameter test2 is missing> |
On my example, a URL having problems passing the data looks like this:
After the testings, I can confirm the normal links will work if the parameters do not contain reserved characters. Just removing those characters would make them work again. Otherwise, if you need the links to work on all cases, you will need to ensure the parameters are URL encoded appropriately and decode the parameters when received.
|
Link |
Construct the URL as follow |
Recommendation based on testings |
|
Direct URL |
ParA=A&ParB=B |
It works if parameters do not contain reserved characters |
|
Direct URL when data contains reserved characters |
ParA= urlencode (urlencode(A)) & ParB= urlencode(urlencode (B)) |
It work on all cases. Parameters need to be URL encoded two (2) times. It requires the data to be URL decoded once |
|
Redirection Link URL |
urlencode (ParA=) urlencode (urlencode (A)) urlencode(&) urlencode (ParB=) urlencode (urlencode(B)) |
It works if parameters do not contain reserved characters |
|
Redirection Link URL when data contains reserved characters |
urlencode (ParA=) urlencode (urlencode (urlencode (A))) urlencode (&) urlencode (ParB=) urlencode (urlencode (urlencode (B))) |
It works on all case. Parameters need to be URL encoded three (3) times. It requires the data to be URL decoded to be used. |
I have tested this using Fuji and Chrome as browser. Hopefully you find it useful.
More information here:
- Authentication Resources (KB0546974)
- Docs: Multiple provider single sign-on
- Docs: Service Portal Single Sign On, logins, and URL redirects
- Docs: Navigate by portal URL
- Docs: Content Management security
- Docs: Get started with Service Portal
- My other blogs
Thanks kbcheung!
2 Comments
