Sample

SelfSTS
Lab version: 1.0.0 Last updated: 5/31/2012

CONTENTS SELFSTS README ..................................................................................................................................... 3

SelfSTS ReadMe
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. Whats 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 WIFs Add STS Wizard to its metadata endpoint.

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 youll 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 dont 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 youll 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="http://schemas.xmlsoap.org/ws/2005/05/identity/claims/emailaddress" displayname="Email Address" value="test@company.com" /> <add type="http://schemas.xmlsoap.org/ws/2005/05/identity/claims/givenname" displayname="Given name" value="Joe" /> <add type="http://schemas.xmlsoap.org/ws/2005/05/identity/claims/surname" displayname="Surname" value="Doe" /> <add type=http://schemas.xmlsoap.org/ws/2005/05/identity/claims/otherphone displayname="Other Phone" value="555-5555-5555" /> <add type="http://schemas.xmlsoap.org/ws/2005/05/identity/claims/name" displayname="Name" value="joe" /> <add type="http://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!