Creating apps for SharePoint that use high-trust authorization
Learn about high-trust apps for SharePoint, which use digital certificates to establish trust between SharePoint and the remote components that access SharePoint.
Last modified: August 29, 2014
Applies to: apps for SharePoint | SharePoint Server 2013
Steve Peschka, Microsoft Corporation
Siew Moi Khor, Microsoft Corporation
In this article
Overview of high-trust apps for SharePoint
Two kinds of token issuers
Deciding between using one certificate or many for high-trust apps for SharePoint
Certificates are root authorities in SharePoint
Web application needs to know that it is a token issuer
IT staff responsibilities in the high-trust system
A high-trust app is a provider-hosted app for SharePoint that is installed to an on-premises SharePoint farm. It cannot be installed to Microsoft SharePoint Online or marketed through the Office Store. A high-trust app uses a certificate instead of a context token to establish trust.
This topic helps you understand the high-trust authorization system for apps for SharePoint. For practical information about creating and deploying high-trust apps, see the following topics:
In SharePoint 2013, the security token service (STS) provides access tokens for server-to-server authentication. The STS enables temporary access tokens to access other application services such as Exchange 2013, Lync 2013, and apps for SharePoint. A farm administrator establishes trust between SharePoint and the other application or app by using Windows PowerShell cmdlets and a certificate. Each certificate that is used must be trusted by SharePoint 2013 using the New-SPTrustedRootAuthority cmdlet. Also each certificate must be registered with SharePoint as a token issuer using the New-SPTrustedSecurityTokenIssuer cmdlet.
The STS isn't intended for user authentication. So, you won't see the STS listed on the user sign-in page, in the Authentication Provider section in Central Administration, or in the People Picker in SharePoint 2013.
The remote web application of a high-trust app for SharePoint is bound to a digital certificate. (For information about how this is done, see the two topics linked-to above.) The certificate is used by the remote web application to sign the access tokens that it includes in all its requests to SharePoint. The web application signs the token with the private key of the certificate and SharePoint validates it with the public key of the certificate. The certificate has to be registered with as a trusted token issuer before SharePoint will trust the tokens that it issues. There are two kinds of token issuers; some can only issue tokens for a particular app for SharePoint, others, called trust brokers, can issue tokens for multiple apps for SharePoint.
As a practical matter, SharePoint farm administrators determine which type of token issuer is created by the switches and parameter values they use with the New-SPTrustedSecurityTokenIssuer cmdlet. To create a token issuer that is a trust broker, add the –IsTrustBroker switch to the command line and use a unique value, other than an app's client ID, for the –Name parameter. The following is an edited example.
New-SPTrustedSecurityTokenIssuer –IsTrustBroker -RegisteredIssuerName "<full_token_issuer_name>" --other parameters omitted--
To create a non-broker token issuer, the –IsTrustBroker switch is not used. There is one other difference. The value of the -RegisteredIssuerName parameter is always in the form of two GUIDs separated by the "@" character; GUID@GUID. The GUID on the right side is always the ID of the authentication realm of the SharePoint farm (or site subscription). The GUID on the left side is always a specific ID for a token issuer. It is a random GUID when a trust broker token issuer is being created. But when a non-broker token issuer is being created, the specific issuer GUID must be the same GUID that is used as the client ID of the app for SharePoint. This parameter not only provides a name for the issuer, it tells SharePoint which app for SharePoint is the only one for which the certificate can issue tokens. The following is a partial example:
$fullIssuerIdentifier = "<client_ID_of_SP_app>" + "@" + "<realm_GUID>" New-SPTrustedSecurityTokenIssuer -RegisteredIssuerName $fullIssuerIdentifier --other parameters omitted--
Typically, the New-SPTrustedSecurityTokenIssuer cmdlet is used in a script that performs other tasks to configure SharePoint for high-trust apps. For more information about such scripts and complete examples of the New-SPTrustedSecurityTokenIssuer cmdlet, see High-trust configuration scripts for SharePoint 2013.
SharePoint and network administrator have two basic strategies to choose from when obtaining and managing certificates for use by high-trust apps for SharePoint:
Use the same certificate for multiple apps for SharePoint.
Use a separate certificate for each app for SharePoint.
This section discusses the pros and cons for each strategy.
The benefit of using the same certificate for multiple apps for SharePoint is that an administrator has fewer certificates to trust and manage. The disadvantage in this approach is that, when you encounter a situation where you want to break trust with a particular app for SharePoint, the only way the administrator can break trust is by removing the certificate as a token issuer or as a root authority. But removing the certificate also breaks trust with all other apps for SharePoint that use the same certificate, which causes them all to stop working.
To get the still trustworthy apps for SharePoint working again, the administrator would need to create a New-SPTrustedSecurityTokenIssuer object using a new certificate and include the -IsTrustBroker flag. Then the new certificate would have to be registered with each server that hosts any of the trustworthy apps and each of those apps would have to be bound to the new certificate.
The benefit of using one certificate per app is that it makes it easier to break trust with a particular app, because the certificates that are used by the still trustworthy apps are not affected when the administrator breaks trust with the certificate of the one app. The disadvantage in this strategy is that an administrator has more certificates to acquire and SharePoint must be configured to use each of them, which can be done with a reusable script as shown in High-trust configuration scripts for SharePoint 2013.
As mentioned briefly at the top of this article, SharePoint farm administrators have to make the certificate, of the remote web application in the high-trust app, a trusted root authority in SharePoint as well as a trusted token issuer. In fact, when there is a hierarchy of certificate issuing authorities behind the web application's certificate, all the certificates in the chain must be added to SharePoint's list of trusted root authorities.
Each certificate in the chain is added to SharePoint's list of trusted root authorities with a call of the New-SPTrustedRootAuthority cmdlet. For example, suppose that the web application's certificate is a domain certificate that is issued by an enterprise domain certificate authority on the LAN, and suppose that its certificate, in turn, was issued by a standalone, top-level certificate authority on the LAN. In this scenario, the certificates of the top-level CA, the intermediate CA, and the web application all have to be added to SharePoint's list of trusted root authorities. The following Windows PowerShell code would accomplish this.
$rootCA = New-Object System.Security.Cryptography.X509Certificates.X509Certificate2("<path_to_top-level_CA's_cer_file>") New-SPTrustedRootAuthority -Name "<name_of_certificate>" -Certificate $rootCA $intermediateCA = New-Object System.Security.Cryptography.X509Certificates.X509Certificate2("path_to_intermediate_CA's_cer_file") New-SPTrustedRootAuthority -Name "<name_of_certificate>" -Certificate $intermediateCA $certificate = New-Object System.Security.Cryptography.X509Certificates.X509Certificate2("path_to_web_application's_cer_file") New-SPTrustedRootAuthority -Name "<name_of_certificate>" -Certificate $certificate
The root and intermediate certificates should be added only once on a SharePoint farm. Typically, the web application's certificate is added in a separate script that does other configuration too, such as the call to New-SPTrustedSecurityTokenIssuer. For examples, see High-trust configuration scripts for SharePoint 2013.
If the web application's certificate is self-signed, as might be the case when the app is being developed and debugged, then there is no certificate chain and only the web application's certificate needs to be added to the list of root authorities.
For more information, see the blog post Root of certificate chain not trusted error with claims authentication. (Scroll past the section about exporting the certificate from Active Directory Federation Services (AD FS), assuming you created your certificate for your high-trust apps via some other means; for example, by using a commercial certificate issued by a Certificate Authority, a self-signed certificate, or a domain-issued certificate.)
The remote web application component of the app for SharePoint is bound to its certificate in IIS. This is sufficient for the traditional purposes of certificates: securely identifying the web application and encoding the HTTP requests and responses. However, in a high-trust app for SharePoint, the certificate has the additional task of issuing access tokens that the web application sends to SharePoint. For this purpose, web application has to know the issuer ID of the certificate that is used when registering the certificate as a token issuer with SharePoint. The web application gets this ID from the appSettings section of the web.config file, where there is a key named IssuerId. Instructions for how the app developer sets this value, and how the certificate is bound to the web application in IIS, are in How to: Package and publish high-trust apps for SharePoint 2013. Note that if the customer is using the strategy of having a separate certificate for each high-trust app for SharePoint, then the ClientId value is also used as the IssuerId value. This is not the case when multiple apps share the same certificate, because each app for SharePoint must have its own unique client ID, but the issuer ID is the identifier for a SPTrustedSecurityTokenIssuer object.
Following is an example of an appSettings section for a high-trust app for SharePoint. In this example, a certificate is being shared by multiple apps, so the IssuerId is not the same as the ClientId. Note that there is no ClientSecret key in a high-trust app for SharePoint.
<appSettings> <add key="ClientId" value="6569a7e8-3670-4669-91ae-ec6819ab461" /> <add key="ClientSigningCertificatePath" value="C:\MyCerts\HighTrustCert.pfx" /> <add key="ClientSigningCertificatePassword" value="3VeryComplexPa$$word82" /> <add key="IssuerId"" value="e9134021-0180-4b05-9e7e-0a9e5a524965" /> </appSettings>
Developers will have to understand the requirements for application security as described above, but IT Pros will be implementing the infrastructure required to support it. IT Pros must plan for the following operational requirements:
Create or purchase one or more certificates that will be used for trusted apps for SharePoint.
Manage the distribution of those certificates to developers who are building apps for SharePoint.
Keep track where each certificate is distributed, for both the apps using it and the developers who have received a copy. If a certificate has to be revoked, the IT staff muse work with each developer to arrange for a managed transition to a new certificate.