Why so opaque?

If you’ve done much sifting through Lync Server logs, you have probably noticed the SIP URIs that have an extra parameter tacked on the end named opaque. You may have wondered what all of this opaque stuff means, and what purpose it serves. This post will explain the opaque parameter, so that you can interpret it in Lync logs, use it in your applications, and impress your friends at parties (actually, maybe only at Lync user group meetings).

First, let me get a little bit of jargon out of the way. The part of a SIP URI that contains opaque is a URI parameter, meaning it is something that is stuck onto the end of the SIP URI to add information.

After the sip: prefix, a SIP URI in Lync starts with a “user at host” portion, which looks like this:

me@example.com

At the end of the “user at host” part of the URI, you can add parameters like opaque, consisting of key/value pairs in the format key=value. Parameters are separated by semicolons, like so:

sip:me@example.com;onething=stuff;otherthing=morestuff

There’s one more jargony thing that is important here. In Lync (and, in fact, any SIP-based communication platform), each user has something called an address of record, or AOR, which is sort of the “official” SIP address for that user: the one that you call if you want to reach that user regardless of what device(s) he or she is logged into. (Why would you call anything other than the address of record? One reason might be if you want to call someone on a specific endpoint, not anywhere they happen to be.)

Lync uses the opaque parameter to add extra pieces of information onto an address of record, for routing or other purposes, while keeping the address of record intact in the URI. There are two main uses for it in Lync: to construct GRUUs, and to identify specific services (e.g., voice mail or conferencing) that belong to a user.

Lync builds GRUUs using the opaque parameter so that the user’s primary SIP URI (the address of record) is completely included within the GRUU. By looking at it, you can figure out what user it belongs to. Basically it adds an opaque parameter with an ID, and also the gruu parameter at the end, which has no value, to make it clear that the whole thing is a GRUU and not just a SIP URI with some random ID added onto it.

Another thing Lync does with the opaque parameter is identify services that belong to users. These usually take the form

sip:me@example.com;opaque=app:<service>

For instance, a user’s UM voice mail box is identified by a SIP URI like the following:

sip:me@example.com;opaque=app:voicemail

Then you have conferences, which are always owned by one Lync user. For example, a conference focus has a SIP URI like this:

sip:me@example.com;gruu;opaque=app:conf:focus:id:8B028AB

Once you understand how these URIs work, you can manipulate them and take them apart in your applications. You can look at a SIP URI for a voice mail box or conference and figure out who the owner is. For a conference, you can look at parts of the opaque parameter to get the conference ID.

In theory, there is also nothing preventing you from creating your own uses for the opaque parameter. If you create a new service that is tied to users, you could identify it by adding ;opaque=yourservice to the user’s SIP URI. You could then have an MSPL script that looks for that parameter and routes those requests to your custom application to be handled, rather than proxying them to the user.