Configuring an S2S trust
The first step in configuring an S2S trust for a provider-hosted app
is generating a public/private key pair by creating an X.509
certificate. To obtain an X.509 certificate for use on production
servers, it is recommended that you go through an established
certification authority (CA) that has experience creating
professional-grade certificates. For development and other scenarios
with lower-security concerns, you can create the required X.509
certificate with a public/private key pair by using two command-line
tools named makecert.exe and certmgr.exe, both of which are available
on any web server on which SharePoint 2013 has been installed.
The Windows PowerShell script shown in Example 1
demonstrates how to create an X.509 certificate with a public/private
key pair. You use the makecert.exe tool to create a certificate file
named appserver.wingtip.com.cer
that contains both the public key and the private key. Use the
certmgr.exe tool to register the certificate with IIS so that it can be
used to enable SSL on an IIS website.
Example 1. A Windows PowerShell script creating an X.509 certificate with a public/private key pair
$makecert = "C:\Program Files\Microsoft Office Servers\15.0\Tools\makecert.exe"
$certmgr = "C:\Program Files\Microsoft Office Servers\15.0\Tools\certmgr.exe"
# specify domain name for SSL certificate (optional)
$domain = "appserver.wingtip.com"
# create output directory to create SSL certificate file
$outputDirectory = "c:\Certs\"
New-Item $outputDirectory -ItemType Directory -Force -Confirm:$false | Out-Null
# create file name for SSL certificate files
$publicCertificatePath = $outputDirectory + $domain + ".cer"
$privateCertificatePath = $outputDirectory + $domain + ".pfx"
Write-Host "Creating .cer certificate file..."
& $makecert -r -pe -n "CN=$domain" -b 01/01/2012 -e 01/01/2022 -eku
1.3.6.1.5.5.7.3.1
-ss my -sr localMachine -sky exchange -sy 12
-sp "Microsoft RSA SChannel Cryptographic Provider"
$publicCertificatePath
Write-Host "Registering certificate with IIS..."
& $certmgr /add $publicCertificatePath /s /r localMachine root
# get certificate to obtain thumbprint
$publicCertificate = Get-PfxCertificate -FilePath $publicCertificatePath
$publicCertificateThumbprint = $publicCertificate.Thumbprint
Get-ChildItem cert:\\localmachine\my |
Where-Object {$_.Thumbprint -eq $publicCertificateThumbprint} |
ForEach-Object {
Write-Host " .. exporting private key for certificate (*.PFK)"
$privateCertificateByteArray = $_.Export("PFX", "Password1")
[System.IO.File]::WriteAllBytes($privateCertificatePath,
$privateCertificateByteArray)
Write-Host " Certificate exported" -ForegroundColor Gray
}
There is code at the end of the Windows PowerShell script in Example 1 that exports the certificate’s private key to a password-protected file named appserver.wingtip.com.pfx.
This means that the remote web requires access to this PFX file and the
password in order to retrieve the private key to sign access tokens.
After you have created the .cer
file with the public key, you must copy it to a web server in the
hosting SharePoint farm to create a trusted security-token issuer. The
Windows PowerShell script in Example 2 shows how to create the trusted security-token issuer by using a SharePoint PowerShell cmdlet named New-SPTrustedSecurityTokenIssuer.
Note that a trusted security-token issuer is registered with an
identifying GUID. You should record this GUID because it must be used
from the provider-hosted app.
Example 2. A SharePoint PowerShell script to register a trusted security-token issuer
Add-PSSnapin "Microsoft.SharePoint.PowerShell"
$issuerID = "11111111-1111-1111-1111-111111111111"
$targetSiteUrl = "http://wingtipserver"
$targetSite = Get-SPSite $targetSiteUrl
$realm = Get-SPAuthenticationRealm -ServiceContext $targetSite
$registeredIssuerName = $issuerID + '@' + $realm
$publicCertificatePath = "C:\Certs\appserver.wingtip.com.cer"
$publicCertificate = Get-PfxCertificate $publicCertificatePath
Write-Host "Create token issuer"
$secureTokenIssuer = New-SPTrustedSecurityTokenIssuer
-Name $issuerID
-RegisteredIssuerName $registeredIssuerName
-Certificate $publicCertificate
-IsTrustBroker
Although this example demonstrates registering a trusted
security-token issuer by using a public key from a .cer file,
SharePoint 2013 also supports registering one by using a metadata
endpoint exposed by the provider-hosted app. This is typically the way
registry is done when the app is a product such as Microsoft Exchange
2013 or Workflow Manager.
After you have registered a trusted security-token issuer, the next
step is to register an app principal. This can be done by using the AppRegNew.aspx
page in the exact same way as you would register an app principal for
an app that uses OAuth. You can also register the app principal for an
S2S trust by using a SharePoint PowerShell cmdlet named Register-AppPrincipal as shown in Example 3.
Example 3. Registering the app principal for an S2S trust by using Register-AppPrincipal
# register an app principal for a provider-hosted app using an S2S trust
$appDisplayName = "My S2S High Trust App"
$clientID = "22222222-2222-2222-2222-222222222222"
$targetSiteUrl = "https://intranet.wingtip.com"
$targetSite = Get-SPSite $targetSiteUrl
$realm = Get-SPAuthenticationRealm -ServiceContext $targetSite
$fullAppPrincipalIdentifier = $clientID + '@' + $realm
Write-Host "Register new app principal"
$registeredAppPrincipal = Register-SPAppPrincipal
-NameIdentifier $fullAppPrincipalIdentifier
-Site $targetSite.RootWeb
-DisplayName $AppDisplayName
There are a few scenarios in which the Register-SPAppPrincipal cmdlet does not provide enough control to properly configure an app principal. More specifically, the Register-SPAppPrincipal
cmdlet does not allow you to configure an app domain for the remote web
nor a redirect URI. For scenarios in which you need to configure an app
principal with an app domain and/or a redirect URI, you can write a
SharePoint PowerShell script that uses the SPAppPrincipalManager class in the server-side object model, as shown in Example 4.
Example 4. Registering an app principal by using the SPAppPrincipalManager class
Add-PSSnapin "Microsoft.SharePoint.PowerShell"
# set intialization values for new app principal
$appDisplayName = "App Principal for My High Trust App"
$clientID = "33333333-3333-3333-3333-333333333333"
$appHostDomainUrl = "http://localhost:43002/"
$appRedirectUrl = $appHostDomainUrl + "redirect.aspx"
# provide site isnide target tenancy (aka realm)
$targetSiteUrl = "http://wingtipserver"
# get App Principal Manager
$web = Get-SPWeb $targetSiteUrl
$appPrincipalManager = [Microsoft.SharePoint.SPAppPrincipalManager]::
GetManager($web)
# initialize creation parameters for App Principal host domain
$applicationEndPointAuthorities = new-object System.Collections.Generic.
List[string]
$applicationEndPointAuthorities.Add($appHostDomainUrl);
# initialize creation parameters for App Principal security credentials
$symmetricKey = New-Object System.Security.SecureString;
$datetimeNow = [System.DateTime]::Now
$credential = [Microsoft.SharePoint.SPAppPrincipalCredential]::CreateFromSymmetr
icKey($symmetricKey,
$datetimeNow,
$datetimeNow)
# create new object for App Principal creation parameters
$creationParameters =
New-Object Microsoft.SharePoint.SPExternalAppPrincipalCreationParameters(
$clientID,
$appDisplayName,
$applicationEndPointAuthorities,
$credential)
# assign redirect Uri to creation parameters
$creationParameters.RedirectAddresses.Add( (New-Object System.Uri
$appRedirectUrl) )
# create app principal
$appPrincipal = $appPrincipalManager.CreateAppPrincipal($creationParameters)
