Add a custom STS to ADFS

Introduction
Out of the box ADFS can authenticate with username/password against Active Directory. You can easily extend ADFS to use a custom STS. This makes it possible for example to authenticate against SQL Server. This blog post will show you how to do that.


Prerequisites
You need at least two machines:
Machine 1, which runs Windows Server 2008 R2 and needs the following:
Active directory installed
ADFS v2.0 installed


Machine 2, which will be used as a development machine and needs the following:
Windows Identiy Foundation
IIS 7


Create a Custom STS
Start Visual Studio 2010 as administrator. (If you don't run as administrator, you can get a access denied error when you create the website).


Create a new website:

Select ASP.Net Security Token Service:

Give it a name, for example: MyCustomSts
Make sure .NET Framework 4 is selected
Click OK


When the Solution is created, open the file CustomSecurityTokenService.cs.
Go to the method GetScope. At the end you will see this line:
scope.ReplyToAddress = scope.AppliesToAddress;


This line can cause problems, because our CustomSTS will not always redirect back to the correct url of ADFS. So we change it by hand to:
scope.ReplyToAddress = "https://[domain name of ADFS]/adfs/ls/";


When i insert my ADFS domain name the line will look like this:
scope.ReplyToAddress = "https://w2k8x64ad.dev.local/adfs/ls/";


Of course it's best to put this into the appsettings of the web.config. You can then use this:
scope.ReplyToAddress = WebConfigurationManager.AppSettings["AdfsAddress"];


Name of our Custom STS
We have to set the name (also know as Identifier) of our Custom STS in the web.config.
Find the following appsetting:
<add key="IssuerName" value="PassiveSigninSTS"/>


Change the value to the ID of our Custom STS, for example: MyCustomSts
<add key="IssuerName" value="MyCustomSts"/>


Token signing
Our CustomSTS will return tokens which have to be signed by a certificate. So we need to have a certificate and we have to let our Custom STS know that is has to use that certificate. out of the box the ASP.Net Security Token Service template will do that for us.   I think it's a good idea to create a custom signing-token for practice.


First we have to create a certificate with which our Custom STS will sign tokens.
1. Start IIS
2. Open the window for Server Certificates

At the right hand side of the window you can select the action Create Self-Signed Certificate...
Give the certificate a name: MyCustomStsCert.
Click OK.

You can see the certificate is created with the name we entered.


Next we install the certificate into the certificate store of the local machine. To do this export the certificate:

Give the exported certificate a name and a password:

To import the exported certificate into the local certificate store do this:
1. Open MMC (start -> run -> mmc)
2. In MMC select [file][add/remove add-in]
3. Select Certificates
4. Click Add
5. Select Computer Account
6. Click Next
7. Click Finish
8. Expand Certificates
9. Expand Personal
10. Right click on Certificates below Personal and select All Tasks and Import

Next select the certificate that we exported earlier.


After the certificate is imported, double click on it to see the details.



Find the subject on the Details tab. Copy the value and paste it into the web.config of our Custom STS:


<add key="SigningCertificateName" value="CN=Win7642"/>


Note: remove the spaces in the value, or else our Custom STS can'tfind the certificate.


So now we've made a certificate to sign the tokens and have let our Custom STS know that is has to use that certificate to sign the tokens. We only have to give our Custom STS the right to read the token. But before we can do that we have to deploy our Custom STS to IIS.


Deploy to IIS
We are finished with creating the Custom STS. Now we have to publish it from Visual Studio to for example [drive]\inetpub\wwwroot\MyCustomSTS. But you can choose any folder you want.


Because our Custom STS needs to run under https, we have to create a certificate. For now we can use a self-signed certificate. But when we you take this into production, you have to get a real certificate.
Next we create a new site in IIS with the published project from the previous part.
Use binding https.

Note: You have to use a certificate to run a website under https. You can use the certificate MyCustomStsCert we created earlier, but that would be not really the way to go, since in production you will never use the signing certificate to secure the website. So in our example i've used another self-signed certificate called STSTestCert.


Note: After you click OK and the website is created, don't forget to set the .Net Framework version to 4.0 on the app pool.


Connect Custom STS to ADFS
After we created a Custom STS in the previous steps, we now have to tell ADFS there is a new Claims Provider. We also have to give ADFS our signing certificate.


Export Signing certificate for ADFS
Go to MyCustomStsCert in MMC and select Export

Click Next on every screen and don't change the default settings.
Finally the certificate is exported. Copy the exported certificate to the ADFS server.


Import Signing certificate for ADFS
Everything we did previously was executed on the machine running our Custom STS. Now we move over to the ADFS server.


Go to AD FS 2.0 Management.
Right click on Claims Provider Trusts
Select Add Claims Provider Trust...


Click start on the Welcome screen.

Select Enter claims provider trust data manually.
Click Next.



Enter the name of the claims provider: MyCustomSts.



Click Next.



Select Enable support for the WS-Federation Passive protocol.
Enter the url to the Custom STS.
Click Next.

Note: make sure your Custom STS server can ping your ADFS server. And try browsing to the Custom STS url.


Enter an ID for the Custom STS.
Note: This ID must be the same as the IssuerName entered in the web.config of the Custom STS:
   <add key="IssuerName" value="MyCustomSts"/>
Click Next.



Add the signing certificate we exported and copied to the ADFS server.
Click Next.

Click Next.



Click Close.



Add a Claim Rule. Select Pass Through or Filter an Incoming Claim.
Click Next.



Our Custom STS delivers two claims out of the box: name and role. We can now add rules to set which claims are delivered from our Custom STS to ADFS.
Let's start with a rule for the Name claim. Enter a name for the claim rule, for example name.
select the incoming claim type. For example Name.
click Finish.



We get a warning we can ignore.
Click Yes.



We can now add another claim rule for the Role claim. Or Click Apply and OK.





Finished
We are finished now. if you browse to your relying party, you can authenticate with the new Custom STS.