This is a step by step guide on how to configure an ASP.NET client with the WSO2 Identity Server Passive STS. We'll be using a simple ASP.NET client and will be configuring everything from scratch. You need to have a recent version of WSO2 Identity Server (V3.2.3 or later). Date: Mon, 12th Dec, 2011 Level: Introductory Reads: 1554 Comments: 3 | Login or register to post comments

Chintana Wilamuna ATL WSO2

Introduction

This article will guide you through the steps of configuring WSO2 Identity Server passive STS with a .Net client. Through the .Net client you'll be able to see the claims that you're sending from the Identity Server passive STS (Security Token Service). We'll be using Windows to configure everything. First let's go through some terminology and a pictorial view of the entire system to find out what I mean by a passive STS and how the interaction is done with the .Net client.

Applies To

Table of contents

• Why active/passive STS?
• Message flow in a passive STS
• Configure IIS with HTTPS support
• Importing WSO2 Identity Server certificate
• Configuring the .Net client
• Configuring Identity Server
• Notes
• References

Why active/passive STS?

An STS, as the name implies is a service that issues security tokens. When an authentication request comes, STS authenticates the user with the credentials provided in the message and issues a token with a set of claims. A claim can be a name, key, privilege, capability etc...). Usually the interaction with the STS is done through XML messages. Then the client who interacts with the STS should be able to generate XML messages. In this scenario it's called an active STS. This is fine if you're developing a program. When it comes to interaction with a web browser, this is not possible because browsers cannot generate custom XML messages. Passive STS are there for a browser to be able to interact with an STS. So in WS-Federation specification there are two profiles, named Active Requestor Profile and Passive Requestor Profile.

Message flow in a passive STS

1. User tries to access a resource through a web browser
2. Resource tells the browser that it needs authentication and the location of the passive STS
3. Browser then redirects to the passive STS
4. Passive STS then present a screen to the user where he has to give credentials to login
5. Once authenticated, passive STS issues a token to the user
6. Browser then passes the token to the actual service in order to access it
7. Resource find the token to be valid and return the response to the user

Let's see how we can configure a .Net client to talk to WSO2 Identity Server passive STS. Before configuring the .Net client we need to complete some prerequisites. Since we'll be using our ASP.NET client in HTTPS we have to configure IIS with HTTPS support. In order to configure HTTPS we have to have a certificate. We'll be using this certificate for IIS as well as we'll use it in our ASP.NET application.

Configure IIS with HTTPS support

We're going to enable HTTPS support in IIS server. In order to enable HTTPS support, you have to have a certificate. We'll create a certificate that you can use to configure HTTPS support. The same certificate will be used later on to sign the request sent to the Identity Server from the .Net client.

In Windows you can use makecert command to create a public/private keypair.

makecert -r -pe -n "CN=mycert" -sky exchange -sv mycert.pvk mycert.cer

After creating a keypair, we need to import this into the Windows certificate store. We cannot import the certificates as it is to the Windows certificate store. We have to convert these to PFX (Personal Information Exchange - also known as PKCS) format.

pvk2pfx -pvk mycert.pvk -spc mycert.cer -pfx mycert.pfx

Now we have to import this to the certificate store. Run mmc and add a Certificate snap-in. Browse into Trusted People and and import mycert.pfx. Click Next when it prompts for a private key password.

Run mmc to start Windows Management Console

Add a Certificate Snap-In by clicking File -> Add/Remove Snap-in

Click OK to add the certificate snap-in

Microsoft Management Console should look like this when you add the certificate snap-in

Let's import the certificate we just created. Browse to Trusted People -> Certificates. Right click and click All Tasks -> Import. Click Next in the Certification Import Wizard

Browse and give the path of the certificate we just created

In the next wizard we don't have to change anything, just click Next.

Now we're ready to import the certificate. Click Finish to complete the importing process.

Once the import is successful you should see your certificate in the certificate store.

Now, start IIS manager. Expand the Default Web Site and click on Bindings

Click Add on the binding configuration dialog

Then add an HTTPS binding. Select the certificate we just imported

IIS is now configured with HTTPS support.

Importing WSO2 Identity Server certificate

We need to import WSO2 Identity Server certificate that it'll be using to sign the response. Otherwise our .Net application will not be able to identify the response returned by the Identity Server. Browse into the location where you've unzipped WSO2 Identity Server and go to repository\resources\security. Open a command window here and type the following. When you're prompted for the keystore password type "wso2carbon" (without quotes).

keytool -keystore wso2carbon.jks -export -alias localhost -file localhost.cer

Then just like when you import mycert.cer, import this certificate to the same location. After importing your certificate should look like the following.

Configuring the .Net client

Download the sample ASP.NET application on to your hard drive. Then follow the below steps to add it to IIS as an application.

In IIS manager right click Default Web Site and click Add Application.

Once you add the application successfully, IIS manager should display the newly added app.

Now you need to change the thumbprints in the .Net client to match your certificates. You can find the thumbprints of the certificates by double clicking a certificate in the certificate store and navigating to the Details tab.

Open up Web.config in the .Net client application and change the serviceCertificate thumbprint to match the certificate we just created using makecert.

Then add the thumbprint of the Identity Server certificate as a trusted issuer.

You don't need to change anything else in the ASP.NET client program. You can leave them to their default values.

Configuring Identity Server

Now our client is configured. The final bit of the story is configuring Identity Server. First we need to import the certificate we created to the Identity Server keystore. This will be used by the Identity Server to validate the signed message sent by the ASP.NET client.

Start Identity Server and browse to https://localhost:9443/. Login as admin/admin. Click Configure -> Key Stores.

Click Import Cert

Browse and select mycert.cer we just created and click Import.

Then let's configure Identity Server STS. Click Main -> Security Token Service.

Then click on Passive STS Configuration.

Fill up the form as in the following screenshot. Give the Service Realm Name the URL of your application which is https://localhost/RPWebApp. And select some claims. I selected the given name and the email address as default claims. Click Apply to save your settings.

We've finished configuring everything. Browse to https://localhost/RPWebApp. You'll be redirected to the Identity Server passive STS. Login as admin/admin. Then you'll be redirected to RPWebApp again and you'll be able to see the claims.

Notes

In order to configure the passive STS you have to have an Identity Server 3.2.3 or later version. You can download latest WSO2 Identity Server from here.

References

• WS-Federation: Passive Requestor Profile [PDF]

Author

Chintana Wilamuna, Associate Tech Lead, WSO2, chintana@wso2.com