To begin, you need to trust the IP from the perspective of
SharePoint. Therefore, you need to retrieve the certificate of the
IP/STS and register it in the list of trusted issuers of SharePoint. If
you are consuming an STS published by a third-party IP, then you can
extract the public key of the certificate from the
FederationMetadata.xml file, selecting the following XPath node:
EntityDescriptor/RoleDescriptor/KeyDescriptor/KeyInfo/X509Data/X509Certificate
You can simply copy the content of that XML node into a text file and save it with a .cer file extension.
Otherwise, if you are working with an IP/STS published by the same
machine on which you are running SharePoint, you can export the .cer
certificate file from the local-machine certificate store. You then can
import the .cer file into the private SharePoint 2013 certificate store
either by using a Windows PowerShell script or the UI of the SharePoint
Central Administration (SPCA). In Windows PowerShell, use the following
syntax:
$cert = New-Object System.Security.Cryptography.X509Certificates.
X509Certificate2("IPSTSCert.cer")
New-SPTrustedRootAuthority -Name "DevLeap Sample IP/STS" -Certificate $cert
With this cmdlet, you can retrieve an instance of the X509Certificate2 class by referencing the .cer file path, and then load it by invoking the New-SPTrustedRootAuthority
cmdlet specific to SharePoint 2013. If the certificate is not trusted
by the servers in your SharePoint 2013 farm—for example, if it is a
custom self-created certificate—you will have to trust the whole
certificate chain in the SharePoint 2013 farm. Executing the script on
a single server is sufficient to trust the whole farm.
If you prefer to use the UI of SPCA, browse to the Security section,
select Manage Trust, and then in the Trust Relationships ribbon group,
click the New button to add a new item. You will have to provide a name
and the path to the .cer file to the Establish Trust Relationship page,
as shown in Figure 6.
Registering the IP and mapping claims
Now
you are ready to register the custom IP/STS in SharePoint 2013. To
begin, define the claims that you would like to manage, and then map
them to claims that will be available on the SharePoint side. Each time
you authenticate a subject by using an external IP/STS, you have the
capability to map the claims emitted by the STS in the security token
to claims of the SharePoint side. For example, the custom IP/STS
discussed earlier returns a claim of type http://schemas.devleap.com/Claims/Gender,
which represents the gender of the current user from the IP/STS
viewpoint. In SharePoint, you will have the opportunity to map this
claim to another claim type, or you can leave it as-is. The
claims-based authentication infrastructure of SharePoint will translate
claims for you during user authentication.
Important
The claims-mapping capability is extremely useful and important,
because you could have multiple IPs registered for a single web
application, and the capability to translate claims from one type to
another allows SharePoint to normalize claims during authentication.
You also have the capability to implement custom claim providers,
inheriting from the class SPClaimProvider, to augment claims of a current principal during the authentication phase.
To
register claims mapping, you can use a few commands in Windows
PowerShell. Here are the commands for mapping the claims issued by the
custom STS:
$map1 = New-SPClaimTypeMapping -IncomingClaimType "http://schemas.xmlsoap.org/ws/2005/05/identity/claims/emailaddress" -IncomingClaimTypeDisplayName "Email" -SameAsIncoming
$map2 = New-SPClaimTypeMapping -IncomingClaimType "http://schemas.xmlsoap.org/ws/2005/05/identity/claims/gender" -IncomingClaimTypeDisplayName "Gender" -SameAsIncoming
$map3 = New-SPClaimTypeMapping -IncomingClaimType "http://schemas.devleap.com/SampleIPSTS/claims/favoritecolor" -IncomingClaimTypeDisplayName "FavoriteColor" -SameAsIncoming
Here, any email, gender, and favoritecolor claims are left as they are when they come in (see the argument -SameAsIncoming).
The last step for registering an external IP is to create a new
entry for the IP in the list of available providers. Again, you can use
a Windows PowerShell script to accomplish this:
$realm = "http://claims.sp2013.local/_trust/default.aspx"
$signinurl = "https://localhost:44334/Issue.aspx"
New-SPTrustedIdentityTokenIssuer -Name "DevLeap Sample IP/STS" -Description "DevLeap Sample IP/STS" -Realm $realm -ImportTrustCertificate $cert -ClaimsMappings $map1,$map2,$map3
-SignInUrl $signinurl -IdentifierClaim $map1.InputClaimType
The script defines the $realm variable, which corresponds to the realm of the claims-consumer site. The value of this URL (/_trust/default.aspx,
relative to the target SharePoint site) corresponds to a page that will
be automatically added to the root folder of your SharePoint web
application when you activate a trusted IP as an authentication
technique. That page will be almost empty in terms of ASP.NET markup,
and it will inherit its behavior from the page TrustedProviderSignInPage, defined in the Microsoft.SharePoint.IdentityModel.Pages namespace. This page will only redirect the user’s browser to the IP/STS logon page.
Another variable defined in the script is the URL of the logon page of the IP/STS ($signinurl). Finally, the script registers a new SPTrustedIdentityTokenIssuerNew-SPTrustedIdentityTokenIssuer.
The arguments provided to this cmdlet in the previous example are for
the name and description of the new IP, the realm of the target
SharePoint site, the X.509 certificate of the IP/STS, and the sign-in
URL, claims mappings, and type of the claim that will be considered as
the identifier claim for the authenticated subject. instance by invoking the cmdlet
3.2 Configuring the target web application
To
complete the configuration process, you need to add the new IP to the
list of authentication providers for the target web application. On the
SPCA page, in the Application Management section, click Manage Web
Applications. A window appears that presents the list of all the
available web applications. Choose the web application for which you
want to enable the IP/STS as one of the authentication methods. Next,
on the ribbon, click the Authentication Providers command. In the
window that appears, click the Default Configuration hyperlink. The
Edit Authentication configuration page opens, as shown in Figure 7. Here, you can select the new IP.
That’s it! Now you’re ready to authenticate your users by using the custom IP/STS. Figure 8 shows the authentication options that are presented to any end user willing to authenticate.
The DevLeap Sample IP/STS option will redirect the user to the logon
page of the IP/STS. Of course, if you configure the IP as the unique
authentication provider, your users will be redirected automatically to
the IP/STS without stepping into the authentication method selection
page.
Now you will also be able to configure users authenticated by the IP
as specific SharePoint users and give them specific permissions. Figure 9 shows the Share dialog window, with a search result obtained by searching against the currently configured IP.
If
you try to access the sample site you defined in the “Building a
relying party” section, you will be authenticated automatically and
have access to the site. Thus, you are experiencing a real
single-sign-on user experience.
