SelfSTS: when you need a SAML token NOW, RIGHT NOW

Artikkeli
08/23/2010

A little new toy for you claims-based identity aficionados to play with! Available here.

systray

Tokens are the currency on the identity market. Any identity solution you develop will require you to acquire & consume tokens (& associated claims) at some point.
ADFS2 is super-easy to install, but does require Active Directory and as a result it is not always readily available at development time, especially if you are not targeting a departmental application or a classic federation scenario. And even in that case, you don’t always have a test endpoint set up. When you test a payment service you don’t move real money right away, there’s no reason to do the same with identities: do you have a test account for all the role values you want to test?
The standard solution, one that has been used big time also in out training kit and other examples, is creating a custom STS. Almost three years have passed since the very first preview we gave in Barcelona of what became WIF, and I still remember Barry in the first row facepalming at the sight of one STS built in under 10 minutes. Well, with the WIF SDK tooling now that happens in seconds (or less, if your machine has an SSD ;-)) hence it’s incredibly easy to set up a test STS. However, after you’ve done that hundreds of times (and believe me, I did) even that can start to wear you off; writing new fed metadata every time you change something takes time; and above all, creating many custom STSes can litter your IIS and certificates stores if you are not disciplined in keeping things clean (I’m not). Also, if you are packing your solution for others (in my case for making labs and sample code available to you, more commonly you need to do that when something is not working and you want the help of others) you need to include some setup, which has requirements (IIS, certificate stores, etc) and impact on the target machine.

Well, enter SelfSTS.

SelfSTS is a little winform app which will not deny a token to anyone. It’s an EXE which exposes one endpoint for a passive STS, and one endpoint with the corresponding fed metadata document. The claim types and values are taken from a config section, which can be edited directly in the SelfSTS UI. The tokens are signed with simple self-signed certificates from PFX files, the certificates tore remains untouched. You can even create new self-signed certs with a simple UI, instead of risking to conjure mystical beasts by mistake if you write the wrong makecert parameter.

With SelfSTS you can produce test input for your apps very easily: you start it, point the Add STS Wizard to to the metadata endpoint, and hit F5. If you want the token to have a different claim type or value, you just go to the claims editing UI and change things accordingly. If you need more than one STS at once, you just copy the exe, the config and the PFX certificate you want to another folder, you change the port on which the STS is listening and you fire it up; here you go, you can now do all the home realm discovery experiments you want. I already heard people considering to use this for testing SharePoint even in situations in which you don’t have the WIF SDK installed: that’s right, it just requires the WIF runtime! I am sure you’ll come out with your own creative ways to use that. I am even considering using it instead of many of the custom STSes in the next drops of the training kit…

I feel silly even at having to say that, but for due diligence… SelfSTS is obviously ABSOLUTELY INSECURE. It is just a test toy, and as such it should be used. It gives tokens without even checking who the caller is, and it does that on plain HTTP. It signs tokens with self-signed certificates, and it stores the associated passwords in the clean in the web config. It is the very essence of insecurity itself. Do not use it for anything else than testing applications at development time, on non production systems.

Below there’s an online version of the readme we packed in the sample. Have fun!

Overview

Securing web applications with Windows Identity Foundation require the use of an identity provider, which may not always be available at development or test time. The standard solution to the issue is creating a test STS. The WIF SDK templates make it very easy to create a minimal STS; however it requires you to write code for customizing the claims it emits and, if you want to be able to use the WIF tooling to its fullest, customize the metadata generation code. What’s worse, you need to repeat the process for every new application.

SelfSTS is a quick & dirty utility which provides a minimal WS-Federation STS endpoint and its associated federation metadata document. You can use SelfSTS for testing your web applications by simply pointing WIF’s Add STS Wizard to its metadata endpoint.

selfsts1
Figure 1
The main SelfSTS screen

SelfSTS is a simple .EXE file, which does not require IIS and never touches the certificates store. There is no installation required, you just need the .EXE file itself, its configuration file and the PFX file of the certificate you want to use for signing tokens. Its only requirements are .NET 4.0, the WIF runtime and (if you want to generate extra certificates) the Windows SDK.

SelfSTS provides a simple UI for easily editing the types and values of the claims it will emit: the metadata document will be dynamically updated accordingly.

SelfSTS offers a UI for simplified creation of self-signed X.509 certificates, which you can use if you need to use a signing certificate with a specific subject or if for some reason you cannot use the certificate provided out of the box.

WARNING: SelfSTS is not, and is not meant to be, secure by any measure. All traffic takes place in the clear, on HTTP; requests are automatically accepted regardless of who the caller is; certificates are handled from the file system, without specific passwords protections. This is all by design, SelfSTS is just meant to help you to test web applications by providing you with an easy way of obtaining tokens via WS-Federation.

Using SelfSTS

The simplest way of using SelfSTS is launching the .EXE, hitting the start button (marked as (a) in figure 2), using the (e) button for copying to the clipboard the metadata address, and pasting that address in the Add STS Reference wizard in your web application. Just hit F5 and you’ll get your token right away: SelfSTS does not attempt any form of authentication.

Figure 2
The elements of the main SelfSTS UI and their function

The button Hide (f) will minimize SelfSTS to the system tray, but the endpoint will remain active until you don’t hit the button Stop again.

If you want to configure things by hand, you can get the endpoint address in the clipboard via (d). The details of the signing certificate are shown on the UI, but remember that the certificate itself is not present in the store.

Editing Claims

You can easily change the claim types and values issued by SelfSTS.

Figure 3
The Edit Claims Dialog

Clicking on (b) from Figure 2 opens the dialog shown in Figure 3.

You can edit existing claims in place through (a), (b) and (c). (a) is a dropdown populated with all the claim types which come out of the box with WIF; however you can explicitly type in (a) an arbitrary URI if you need to define a custom claim.

If you want to delete a claim entry you can just press on the corresponding X button (d).

You can add a new entry using the button add (e): of course you can have as many instances of the same time as you want (for example, you will often have multiple entries with the Group claim type).

If you hit Save the current configuration will be committed to the config file of SelfSTS. Please consider that SelfSTS does not make a lot of validation checks, hence if you leave things in messed state you may have to go to the config and fix things manually afterwards.

If you hit Cancel you’ll be back to the main UI, and all the changes will be lost.

Generating a New Certificate

SelfSTS comes with its own default certificate file. However there will be times in which you will want to use a different certificate, for example if there is a specific subject you want to assign to the issuer or if you need to simulate multiple issuers.

SelfSTS offers you a wrapper on top of MakeCert and similar utilities, allowing you to easily create a new self-signed certificate.

Figure 4
The New Certificate Generation Dialog

One interesting side effect of generating a PFX is that the underlying utilities will prompt you for the certificate password multiple times, as shown in Figure 5. Make sure you always use the same password!

Figure 5
Creating a new certificate will result in multiple password prompts

Once the certificate generation is done, SelfSTS changes its config accordingly and will use the new certificate for signing form now on. The certificate password is saved in clear in the config.

WARNING: Needless to say, this is all astonishingly insecure. SelfSTS is not meant to provide a token securely, or to have access to certificates actually in use for business functions. NEVER use a certificate that has actual business uses with SelfSTS.

SelfSTS Configuration Section

The SelfSTS UI is largely an editor for the SelfSTS custom config section. There are things you can do only by touching the config directly.

 <SelfSTSSettings port="8000"
                 signingcertificate="SelfSTS.pfx"
                 signingcertificatepassword="Passw0rd!"
                 issuername="SelfSTS">
  <claims>
    <clear />
    <add type="https://schemas.xmlsoap.org/ws/2005/05/identity/claims/emailaddress"          displayname="Email Address" value="test@company.com" />
    <add type="https://schemas.xmlsoap.org/ws/2005/05/identity/claims/givenname"          displayname="Given name" value="Joe" />
    <add type="https://schemas.xmlsoap.org/ws/2005/05/identity/claims/surname"          displayname="Surname" value="Doe" />
    <add type=https://schemas.xmlsoap.org/ws/2005/05/identity/claims/otherphone         displayname="Other Phone" value="555-5555-5555" />
    <add type="https://schemas.xmlsoap.org/ws/2005/05/identity/claims/name"          displayname="Name" value="joe" />
    <add type="https://schemas.xmlsoap.org/claims/Group" 
         displayname="Group" value="Sales" />
  </claims>
</SelfSTSSettings>

The config format is very straightforward.

You might want to edit the config directly if you want more than one instance of SelfSTS to run at the same time (in which case you can just copy the exe and the config in a new folder, and edit the port value to avoid collisions). You might also want to edit the config for pointing to a certificate you already have as opposed to the default or newly generated ones (NEVER use a certificate you are using in production or that has any business value).

Finally, sometimes you may end up in a messed state when using the UI (say if the certificate generation fails at mid-operation) and you may come here to fix the values before being able to restart SelfSTS.

Summary

SelfSTS can help you to test your web application by providing a WS-Federation endpoint readily available and with little/no infrastructure requirements. Please use it only in test and dev environments and exclusively with self-issued certificates.

SelfSTS will help you to experiment with WIF and claims-based identity without worrying about finding a token source to test against. Have fun!

Comments

Anonymous
October 24, 2010
Dear Vittorio, I was wondering how you created the certificate which is present in the example ? When I create a certificate with for example makecert or this example it is missing the important "Key Usage" field in the certificate. Maybe you can shine some light on this problem ? I am unable to find how to create a self issued certificate which can work with WIF. Regards, Jean-Paul van Mackelenbergh
Anonymous
October 24, 2010
Hi Jean-Paul, you can refer to the source of the sample for the code we use for generating the certificate. The certificates we produce do work for signing and decrypting messages, including for WIF+WCF. If you get a specific error I sugegst you capture it and post it along with soem context about the problem to social.msdn.microsoft.com/.../threads Best, V.
Anonymous
December 15, 2010
This is probably a dumb question but when I try to use this I get the error "Certificate file must contain only one valid X509 certificate without private keys." I am not sure but is there a way to create a Public Key with SelfSTS? Thanks!
Anonymous
February 09, 2011
Hi John, That's weird. What is the exact scenario? SelfSTS can create new self-signed certificates, saved as PFX files (whih hcontain both the certificate itself, which IS the public key, and associated private key). If you want a file contianing just the certificate you could modify the code that spits out the PFX to retain the .CER; or you can install the cert in the local store and then export a .CER out of it

Jaa