Use secure URLs to grant limited access to a calendar

If your group has a Trumba® calendar that contains proprietary or other data that you want to keep secure, you might want to make the calendar available on your intranet or other secure server, where only the people who have access to your secure environment can access the calendar. You might also want them to be able to display the calendar without having to enter a shared user ID and password.

• Requirements for creating secure URLs
• Procedures for creating secure URLs

Before you attempt to create secure URLs (Requirements)

Creating secure URLs is an advanced, developer-level procedure.

This topic describes how you can create secure URLs by using PHP or ASP.Net with C#. The minimum requirements that you must meet before you attempt to create secure URLs are that you:

• Are proficient with ASP.Net, PHP, or a similar Web server scripting language.

Note Knowledge of HTML and CSS is also important for creating pages that host secure Trumba Connect spuds, but it is not sufficient. You must know a server scripting language.

• Have an environment in which you can build and view these pages in a browser.

  For the ASP.Net+C# example, typically that means Microsoft® Windows, Microsoft IIS, and the ASP.Net 2.0 Framework. For PHP, you can use any Web server (for example, Apache) that has PHP installed.

• Have publishing permission for the Trumba calendar and are familiar with calendar spud code.

If you do not meet the requirements for creating secure URLs, we recommend that you consult with a Web developer.

Steps for creating secure URLs

To make your calendar accessible in a secure environment, so that only the users who have access to your environment can see calendar, you complete these steps:

• Publish the calendar, and in the Publish Settings page, generate a secure key.
• Use code provided by Trumba development to create your secure URLs

  Use your secure key and your calendar's web name to replace the placeholder text in secure.aspx. This is a file that you download from this topic, which contains ASP.Net code created by Trumba development.

• In your web page that contains your calendar spud, in the spud code, instead of entering the static URL for your published calendar, enter code that follows the example in secure.aspx. The code calls the function in secure.aspx, which generates the secure URL that is returned to the user.

Note If you already have secure URLs set up on your site, and you want to update them (for example, if you think their security has been compromised), you can do so by opening the Publish Settings page and clicking the link to change your secure key. (Steps for opening the Publish Settings page appear in the next section.) When you get the new key, display it, copy it, and then paste it into the appropriate location of the code on your Web server.

Get a secure key for your published calendar

1. In your Trumba account, display the calendar you want to publish or have published, and click Publish.
2. If the calendar is already published, the Publishing Control Panel appears. On the Publish Settings tab, click Edit Publish Settings.
3. In the Publish Settings section of the Publish Settings page, for Access type, click Secure URL.
4. Click Set your secure key, and then in the form that appears, enter and confirm a password for your calendar, and then click Set.
5. In the Publish Settings page, click Display secure key.
6. Copy the secure key and paste it in a place where you will be able to access it when it's time to paste the information into secure.aspx, the file that contains the code you will use to create your secure URLs.
7. Make any other changes you want on the Publish Settings page, and then click OK.

Note Your calendar is published on a Trumba server. However, if someone tries to access it, Trumba Connect returns a page that is blank except for a message indicating that you cannot display the information without a secure URL.

Use code provided by Trumba development to create your secure URLs

After you get your secure key from the Trumba publishing settings, you need to use that key along with your calendar's web name in code that Trumba development has created for you to generate the secure URLs.

1. Download the sample code to use as a guideline for generating secure URLs.
   • ASP.Net
   • PHP

   The sample code returns a unique, secure URL to the user who requests the calendar page on your secure site. It does the following to create the URL:

   • Sets an expiration for the secure URL of one day from the time the user requests the calendar. (You can change the expiration time to whatever works best for your group.)
   • Uses your secure key and the expiration date to generate an MD5 hash, which it plugs into a hash parameter.
   • In the sample web page, instead of entering a static URL for displaying your calendar, it calls the CreateSecureHash() function, which generates and returns the secure URL. In the source code, client-side browsers will show the end result of the calculations, not the function.
2. In the code given, to plug your calendar into the example, do the following:
   • Paste the secure key you obtained in the publishing settings over the placeholder text YOUR KEY GOES HERE.
   • Replace the placeholder text YOUR WEBNAME GOES HERE with your published calendar's web name.
   • If appropriate, for LIFETIME = 1.0, change 1.0 to the number of days you prefer.
   • Save the file to a location where you can test it on your development server to make sure the sample HTML code displays your spuds correctly.
   • Use the code for your production content. The code can live in the same .aspx or .php file that contains your web page content, in the code-behind for the file, or in another file, as long as it's visible to the page in which you place your secure spuds.

Using your own code

You can use your own code to implement secure URLs instead of using the sample code provided by Trumba Development. However, we strongly recommend that you read the sample code, because it is a working example of how to generate the secure spuds. The rest of this section describes the steps you need to complete with your code.

Get the required parameters

Spud code that you enter in your page to display a calendar that is protected through secure URLs must carry two parameters:

• expires

  The expires parameter is a UTC date in yyyyMMddHHmm format . It tells Trumba Connect how long access to the calendar should be granted with the URL. The default duration is one day.

• hash.

  The hash parameter is a hexadecimal string that contains the MD5 hash of a query string that you build using your calendar name and the other two required parameters. The query string looks like the following:

  calendar=webname&expires=expiration&hash=yoursecurekey

  Where you replace the blue placeholder text with the appropriate values. The expires parameter requires the same date format described in the list above.

Plug the required parameters into the spud code

Once you have an MD5 hash of your query string, you provide the hash and your expires value to the $Trumba.addSpud() call. These values must appear in string fields on the url parameter.

Below is an example of a secure request.

Tip Take a look at the PHP example code to clarify the above example.

Additional information

When you create your secure key in the publishing settings, you cannot display your calendar any way other than by going through the process of generating an MD5 hash, as in the procedures above. Using your secure key with a hash parameter in a static URL will not work.

Your secure key is also stored on the Trumba server in association with your calendar. When a user requests to display your calendar, Trumba Connect generates an MD5 hash from your secure key. If the MD5 hash generated from Trumba Connect doesn't match yours, Trumba Connect cannot display your calendar.