iTunes U Administration Guide: Generating the Token Data

Generating the Token Data

To establish a session when the user clicks an iTunes U link in your webpage, you must send an authorization token to iTunes U authorizing the user to iTunes U. This authorization token contains the user’s credential information, and, optionally, information identifying the user, as well as the token creation time and a digital signature. By default, the authorization token is only valid for 90 seconds from the time you create it. Therefore, be sure to send the authorization token to iTunes U within 90 seconds of the time you create it.

Note: A user’s access to specific iTunes U pages or groups depends on the credentials sent in the authorization token as well as the access levels you define for those credentials within iTunes U. For more information, see “Controlling User Access.”

To construct the token data:

Concatenate credential, identity, and time key-value pairs in alphabetical order in the form: key1=value1&key2=value2&key3=value3. For example: credentials=foo&identity=<jdoe@example.edu>"jdoe"&time=1139331600
URL-encode the key-value string result from step 1. The token string becomes: credentials=foo&identity=%3Cjdoe@example.edu%3E%22jdoe%22&time=1139331600
Create a final UTF-8 encoded token data string from the result in step 2.

Important:

You must specify the key-value pairs in alphabetical order: credentials, identity, time.
Apple uses the Java URL encoding style for signature matching. Using this style, all characters except the following are encoded: letters, numbers, periods (.), dashes (-), underscores (_), and asterisks (*).

Token Data Key	Token Data Value
credential	A text string containing one or more of the user’s attributes and the user’s unique identifier. You can specify up to 1024 bytes per credential. For example: Student@urn:mace:example.edu:psych101.3.200609. You can specify up to 100 credentials per user, separated by semicolons (;). However, the credential itself cannot contain semicolons (;), backslashes (\), or control characters. If you do not want to specify any credentials, define the key as `credentials=` with no space between the empty credential and the ampersand (&) delimiter separating the next key-value pair. If you do not specify any credentials, the user can only access publicly available content. For an example of how to implement the credential key, see the example written in Java in “Credential Key Example.” Note: You use this credential information again when you define user access to pages and groups within your iTunes U site. For this reason, you may find it helpful to create a consistent naming scheme for all your user credential information. For information on MACE and middleware infrastructure, see http://middleware.internet2.edu/MACE/. For information on Internet2-LDAP representations of eduCourse attributes, see http://middleware.internet2.edu/courseid/docs/internet2-mace-dir-courseid-educourse-ldap-200507.html.
identity	An optional text string representing a specific user. For example: "Jane Doe" <janedoe@example.edu> (jdoe) [42]. It is recommended that you define unique identity values for every user in your system. If you do not want to specify any identity information, define the key as `identity=` with no space between the empty identity and the ampersand (&) delimiter separating the next key-value pair. If you do not specify any identity information, iTunes U cannot distinguish one user from another and restrict certain actions. For example, all users with Drop Box access can browse the content uploaded by other users. The identity key value is defined by: `"displayName"<emailAddress>(username)[userIdentifier]`, where: `displayName` is the full name of the user, used to identify the user within iTunes U. For example: Jane Doe. To use special characters in the `displayName` key value, escape the character with a backslash (\). For example, to use a double quote ("), type \". If you provide `displayName`, the iTunes U 8 or earlier navigation bar displays "displayName@SiteName" and the iTunes 9 or later navigation bar displays "SiteName - displayName". Where SiteName represents your site’s display name as specified in the Edit Site Settings page. If you do not provide `displayName`, iTunes U displays only SiteName in the navigation bar. `emailAddress` is the user’s email address. For example: janedoe@example.edu. The `emailAddress` key value cannot contain spaces or these characters: <, > (less than or greater than). For more information, see Section 3.4.1 of RFC 2822 – Internet Message Format at http://www.faqs.org/rfcs/rfc2822.html. `username` is the user’s unique login name. For example: jdoe. You can include a domain name if your institution shares information with other domains. For example: jdoe@example.edu. The `username` key value cannot contain these characters: (, ) (open or closed parentheses). `userIdentifier` is a unique identifier associated with the specified user. For example: 42. The `userIdentifier` key value can be any string that allows your institution to uniquely identify a user. The `userIdentifier` key value cannot contain these characters: [, ] (open or closed brackets). If your institution has a central IT system, you probably already have an internal User ID associated with each user in your system that you can use as the `userIdentifier`. You are not required to send iTunes U any user information that would violate your privacy policies. You may send an opaque or other identifier that does not contain private user information. If you send iTunes U identity key values, iTunes U can provide more detailed information about your users and the actions they perform. For example, if you send identity information to iTunes U, you can see information about the user who uploaded a track, instead of simply the time when a track was uploaded. For an example of how to implement the identity key, see the example written in Java in “Identity Key Example.”
time	The time, in seconds, when you generate the token data. Specify time as the number of seconds from the epoch (midnight January 1, 1970), normalized to Greenwich Mean Time (GMT). Specify time as base 10, without leading zeros or trailing decimals. For example: 1139331600. If your server’s clock is not synchronized with the iTunes U server, authentication fails. To ensure that your time is synchronized with the iTunes U server time, set your institution’s server time to network time (NTP). iTunes U uses the token generation time to establish a login session. A login session is the duration of time, 90 seconds by default, that your authentication and authorization privileges are valid. If you access iTunes U after the token generation time has expired, iTunes U directs you to the site’s login page. For a site available to the public, iTunes U ignores the token, logs you in as a public visitor, and displays only public information in the site.

Token Data Key

Token Data Value

credential

A text string containing one or more of the user’s attributes and the user’s unique identifier. You can specify up to 1024 bytes per credential. For example: Student@urn:mace:example.edu:psych101.3.200609.

You can specify up to 100 credentials per user, separated by semicolons (;). However, the credential itself cannot contain semicolons (;), backslashes (\), or control characters. If you do not want to specify any credentials, define the key as credentials= with no space between the empty credential and the ampersand (&) delimiter separating the next key-value pair. If you do not specify any credentials, the user can only access publicly available content.

For an example of how to implement the credential key, see the example written in Java in “Credential Key Example.”

Note: You use this credential information again when you define user access to pages and groups within your iTunes U site. For this reason, you may find it helpful to create a consistent naming scheme for all your user credential information.

For information on MACE and middleware infrastructure, see http://middleware.internet2.edu/MACE/.

For information on Internet2-LDAP representations of eduCourse attributes, see http://middleware.internet2.edu/courseid/docs/internet2-mace-dir-courseid-educourse-ldap-200507.html.

identity

An optional text string representing a specific user. For example: "Jane Doe" <janedoe@example.edu> (jdoe) [42].

It is recommended that you define unique identity values for every user in your system. If you do not want to specify any identity information, define the key as identity= with no space between the empty identity and the ampersand (&) delimiter separating the next key-value pair. If you do not specify any identity information, iTunes U cannot distinguish one user from another and restrict certain actions. For example, all users with Drop Box access can browse the content uploaded by other users.

The identity key value is defined by:

"displayName"<emailAddress>(username)[userIdentifier], where:

displayName is the full name of the user, used to identify the user within iTunes U. For example: Jane Doe. To use special characters in the displayName key value, escape the character with a backslash (\). For example, to use a double quote ("), type \".
If you provide displayName, the iTunes U 8 or earlier navigation bar displays "displayName@SiteName" and the iTunes 9 or later navigation bar displays "SiteName - displayName". Where SiteName represents your site’s display name as specified in the Edit Site Settings page. If you do not provide displayName, iTunes U displays only SiteName in the navigation bar.
emailAddress is the user’s email address. For example: janedoe@example.edu. The emailAddress key value cannot contain spaces or these characters: <, > (less than or greater than). For more information, see Section 3.4.1 of RFC 2822 – Internet Message Format at http://www.faqs.org/rfcs/rfc2822.html.
username is the user’s unique login name. For example: jdoe. You can include a domain name if your institution shares information with other domains. For example: jdoe@example.edu. The username key value cannot contain these characters: (, ) (open or closed parentheses).
userIdentifier is a unique identifier associated with the specified user. For example: 42. The userIdentifier key value can be any string that allows your institution to uniquely identify a user. The userIdentifier key value cannot contain these characters: [, ] (open or closed brackets). If your institution has a central IT system, you probably already have an internal User ID associated with each user in your system that you can use as the userIdentifier.

You are not required to send iTunes U any user information that would violate your privacy policies. You may send an opaque or other identifier that does not contain private user information. If you send iTunes U identity key values, iTunes U can provide more detailed information about your users and the actions they perform. For example, if you send identity information to iTunes U, you can see information about the user who uploaded a track, instead of simply the time when a track was uploaded.

For an example of how to implement the identity key, see the example written in Java in “Identity Key Example.”

time

The time, in seconds, when you generate the token data. Specify time as the number of seconds from the epoch (midnight January 1, 1970), normalized to Greenwich Mean Time (GMT). Specify time as base 10, without leading zeros or trailing decimals. For example: 1139331600.

If your server’s clock is not synchronized with the iTunes U server, authentication fails. To ensure that your time is synchronized with the iTunes U server time, set your institution’s server time to network time (NTP).

iTunes U uses the token generation time to establish a login session. A login session is the duration of time, 90 seconds by default, that your authentication and authorization privileges are valid. If you access iTunes U after the token generation time has expired, iTunes U directs you to the site’s login page. For a site available to the public, iTunes U ignores the token, logs you in as a public visitor, and displays only public information in the site.

Note: For the identity token data key, iTunes U displays user information in the log and reporting files based on the following identity key value order:

userIdentifier
username@domainName
emailAddress
displayName@domainName
member@itunesu.com (displayed if no identity information provided)

If a user is visiting a public site, iTunes U displays visitor@itunesu.com in the log and reporting files.

In this section:

Credential Key Example
Identity Key Example