How to Configure OAuth using Server2Server Trust in SharePoint 2013

How to Configure OAuth using Server2Server Trust in SharePoint 2013

How to Configure OAuth using Server2Server Trust in SharePoint 2013

 

​Recently I was asked to integrate a SharePoint environment with a K2 environment. Usually this is not very complicated as K2 provides a setup.exe which you can run on your SharePoint farm which configures this automatically. Unfortunately, due to security policies of my customer this was not possible, so I ended up doing this manually. If everything had worked at the first go I probably would not have written this article. So here are the steps and also some caveats you should know in order you need to troubleshoot your setup. Basically this procedure works for any OAuth in an on-premises environment where you are ususally using high trust (S2S instead of Azure ACS) for your remotely hosted app.

1.Create a security token service on your SharePoint farm. This is component is responsible to manage incoming security tokens. The token is used to authenticate incoming requests from the remote application when it accesses resources in SharePoint. You will need to be a SharePoint farm admin in order to run the following script.

 param (
$spUrl, # i.e. "https://webapp1.yoursite.com/sites/AppCatalog"
$remoteAppUrl, # i.e. "https://app.yoursite.com"
$publicCertPath, # i.e. ".\TokenSigningCert.cer"
$appId, # i.e. "ff08eaff-d056-4a32-9b1d-563f81bf0031"
$appName, # i.e. "AppName for SharePoint"
)

Add-PsSnapin Microsoft.SharePoint.PowerShell

$legacyAppName = $appName;

# Get the website where you are installing your app.
$spweb = Get-SPWeb $spUrl

# Get the authentication realm for your SharePoint site.
$realm = Get-SPAuthenticationRealm -ServiceContext $spweb.Site

# Use appId and realm as security token service id
$fullAppIdentifier = $appId + '@' + $realm

# Create a trusted security token service.
$certificate = Get-PfxCertificate $publicCertPath
New-SPTrustedSecurityTokenIssuer -Name $appName -Certificate $certificate -RegisteredIssuerName $fullAppIdentifier -IsTrustBroker -Confirm:$false

2.Register app principals on all SharePoint web applications. This is only required when your app accesses resources in SharePoint and depends on what your app does. So this must be changed according to the requirements of your app. Ask your app developer what exactly is required for your app.

  param (
$spUrl, # i.e. "https://webapp1.yoursite.com/sites/AppCatalog"
$appId, # i.e. "ff08eaff-d056-4a32-9b1d-563f81bf0031"
$appName, # i.e. "AppName for SharePoint"
$appCatalogList = @(
"https://webapp1.yoursite.com/sites/AppCatalog",
"https://webapp1.yoursite.com/sites/AppCatalog"
)
)

# Get the website where you are installing your app.
$spweb = Get-SPWeb $spUrl

# Get the current authentication realm for your SharePoint site.
$realm = Get-SPAuthenticationRealm -ServiceContext $spweb.Site

# Get the app Id together with the realm value.
$fullAppIdentifier = $appId + '@' + $realm

foreach ($appCatalog in $appCatalogList)

{

# Register the app principal with the app management service, so that you can grant app permissions.

$appPrincipal = Register-SPAppPrincipal -NameIdentifier $fullAppIdentifier -Site $appCatalog -DisplayName $appName

# Grant Permissions

Set-SPAppPrincipalPermission -Site $appCatalog -AppPrincipal $appPrincipal -Scope SiteCollection -Right Manage

}

3. Add the token signing certificate used in the first script to your trusted root authorities in SharePoint. If the app is using a self-signed certificate – which is perfectly fine when using S2S – then you will use the certificate itself. In case this is a certificate issued by your enterprise CA or a public CA then you will need to add the root certificate of your chain, I assume.

a. In SharePoint Cenral Admin navigate to Security > Manage Trust
b. In the ribbon click New Trust
c. Type in a friendly name – as a best practice I am using the same string I used as $appName in the scripts
d. Browse to the certificate used in the first script
e. Leave the box un-ticked (we already created a security token service)
f. Click OK

Done.

After you uploaded your app to an app catalog you can add the app to any site collection in your web application and use it.

Troubleshooting

If you receive error messages while using your app – especially 401 (see IIS logs) response codes sent to your app – then the following troubleshooting advices may help.

  • Be aware that SharePoint caches security token service information. This means if you change anything in the configuration described above, this will not take effect immediately. In order clear the cache, recycle the application pools of your IIS web applications and start the SharePoint timer job „Refresh trusted security token metadata feed“ manually.
  • To change specifics in your security token, just remove it completely and re-run the script (step 1) again with your new parameters.

Remove-SPTrustedSecurityTokenIssuer -Identity $appName -ErrorAction:SilentlyContinue -Confirm:$false

  • If you change the certificate of your security token service, also remember to remove the trusted root authority for that certificate in Central Admin and add your new certificate instead.

Schreibe einen Kommentar

Deine E-Mail-Adresse wird nicht veröffentlicht. Erforderliche Felder sind mit * markiert.

Time limit is exhausted. Please reload the CAPTCHA.