Friday, July 11, 2014

PowerShell Script: Add a Trusted Security Token Issuer and Principal Permissions

Topic:Configuration
Level:Advanced
Intended Audience:Administrator, Architect, and IT Professional


If you read my recent post on how to use PowerShell to remove a Trusted Security Token Issuer and Principal Permissions, you will love this post in which I show you have to add a Trusted Security Token Issuer as well as a App Principal Permission.

Just save the following into a .PS1 file. You just need to provide the app display name, Issuer ID (or leave it blank for a random GUID), SSL certificate location, SharePoint site URL, the scope for which the app's principal should be registered (Site, SiteCollection, or SiteSubscription), and the permission that the application should have (Read, Write, Manage, or FullControl). Again, it is that easy.

if((Get-PSSnapin -Name Microsoft.SharePoint.PowerShell -ErrorAction SilentlyContinue) -eq $null)
{
    Add-PsSnapin Microsoft.SharePoint.PowerShell
}

# Stop if there is a problem with this cmdlet
$ErrorActionPreference = "Stop"

# Set our required variables
$appDisplayName = Read-Host "What is your app's display name?"
$issuerID = Read-Host "What is the Issuer ID? Leave blank to auto generate a GUID. Must be unique to the site.”
if ($issuerID -eq "") { $issuerID = [guid]::NewGuid() }
$publicCertPath = Read-Host "Please type in the .CER path location. For example, C:\mycertificate.cer"
$siteUrl = Read-Host "Please type in the SharePoint site URL. For example, https://sp2013.myspsite.com”
$site = Get-SPSite $siteUrl
$appScope = Read-Host "What scope should this application have access too? [Site] [SiteCollection] [SiteSubscription]"
$appPerm = Read-Host "What permission should this application have? [Read] [Write] [Manage] [FullControl]"

# Get our full application identifier
$web = Get-SPWeb $siteUrl
$certificate = Get-PfxCertificate $publicCertPath
$realm = Get-SPAuthenticationRealm -ServiceContext $web.Site
$fullAppIdentifier = $issuerId + '@' + $realm

# Add the trusted root authority, security token issuer, register the app principal, and set app permissions
New-SPTrustedRootAuthority -Name $appDisplayName -Certificate $certificate
New-SPTrustedSecurityTokenIssuer -Name $appDisplayName -Certificate $certificate -RegisteredIssuerName $fullAppIdentifier
Register-SPAppPrincipal -NameIdentifier $fullAppIdentifier -Site $web -DisplayName $appDisplayName
$appPrincipal = Get-SPAppPrincipal -NameIdentifier $fullAppIdentifier -Site $site.RootWeb
Set-SPAppPrincipalPermission -Site $site.RootWeb -AppPrincipal $appPrincipal -Scope $appScope -Right $appPerm

iisreset

PowerShell Script: Remove Trusted Security Token Issuer and Principal Permissions

Topic:Configuration
Level:Advanced
Intended Audience:
Administrator, Architect, and IT Professional

I recently wrote a PowerShell script that can be used to easily remove a Trusted Security Token Issuer as well as any App Principal Permission that has been setup for the SharePoint 2013 on-premise (AKA Provider-Hosted) App. Just save the following into a .PS1 file. You just need to provide the SharePoint site URL, app name, and the scope for which the app's principal was originally registered (Site, SiteCollection, or SiteSubscription). It is that easy.

if((Get-PSSnapin -Name Microsoft.SharePoint.PowerShell -ErrorAction SilentlyContinue) -eq $null)
{
    Add-PsSnapin Microsoft.SharePoint.PowerShell
}

# Stop if there is a problem with this cmdlet
$ErrorActionPreference = "Stop"

# Set our required variables
$siteUrl = Read-Host "Please type in the SharePoint site URL. For example, https://sp2013.myspsite.com”
$site = Get-SPSite $siteUrl
Write-Host ""
Write-Host "SharePoint Apps:"
Get-SPTrustedSecurityTokenIssuer | select Name | fl
$issuerID = Read-Host "What is the app's name?"
$realm = Get-SPAuthenticationRealm
$fullIssuerID = $issuerID + '@' + $realm
$tokenIssuer = Get-SPTrustedSecurityTokenIssuer | Where-Object { $_.RegisteredIssuerName -eq $issuerID }
$appScope = Read-Host "What is the app's registered scope? [Site] [SiteCollection] [SiteSubscription]"
$appPrincipal = Get-SPAppPrincipal -NameIdentifier $fullIssuerID -Site $site.RootWeb

#Remove the security token issuer and the app principal permission
Remove-SPTrustedSecurityTokenIssuer -Identity $issuerID -Confirm
Remove-SPAppPrincipalPermission -AppPrincipal $appPrincipal -Site $site.RootWeb -scope $appScope -Confirm

# Show confirmation that the issuer has been removed
Get-SPTrustedSecurityTokenIssuer | select Name,RegisteredIssuerName | fl

Tuesday, June 3, 2014

My First SharePoint 2013 Timer Job - App Project

Topic:Programming
Level:Advanced
Intended Audience:Architect and Developer

Welcome back. This is part two of my series on creating a SharePoint 2013 Timer job. Specifically I am going to cover the high-trust provider-hosted app project inside of Visual Studio. And, how to configure this app to use a App Only policy. So this part of the series is a little more tailored towards the developer and not so much the admin / IT professional.

I will warn that these instructions are really meant for a Development or Test server type scenario. For Production there are several changes that I am hoping common sense would dictate you change. For example, you would not use a password of password in a Production environment. Nor would you store your .PFX on the local machine you are doing development on. Use your own discretion and work closely with your admins / IT professionals in a Production scenario.

So what is the difference between high, low, and full trust?


A high-trust app is a provider-hosted app that uses digital certificates to establish trust between the remote web application (your app server) and SharePoint (your SharePoint server). The high-trust app can take over the identity of any user without knowing the user's password. SharePoint will then allow the app to work on the behalf of that user. This does not imply that the app can take over an administrator's account and have access to everything they have. The app has a specific manifest file that dictates the permissions it has. And, the user has to be okay with this when the app is being instantiated inside of SharePoint. So it is not a full fledged take over of that user's account.

Now, a high-trust application is not the same as a full-trust solution. A high-trust app must still make app permission requests as I explained. The full-trust solution scenario has the same permissions as the SharePoint environment itself. Meaning that the solution is installed and ran on the SharePoint server itself like you used to do in SharePoint 2010 (e.g., good ole WSP packages). The high-trust app should be installed on it's own isolated server and not on the SharePoint server itself.

A low-trust app uses a trust broker, such as Microsoft Azure Access Control Services (ACS), to act as a token issurer between SharePoint and the application. Low-trust applications can not "impersonate" or do actions on the behalf of other users like a high-trust application can. The low-trust app uses it's own app identity when communicating with the server and when requesting a token. This makes low-trust a great option for Office 365. It should also be noted that this low-trust scenario utilizes OAuth.

What are app authorization policies?


SharePoint has three types of authorization policies. User-only, User and App, and App-only.

The user-only policy is the policy that was always applied in SharePoint 2010. This policy takes into account only the user identity. In example, when a user is accessing resources directly without using an app at all they are using the user-only policy for authorization checks.

The user and app policy takes into account both the user identity and the app identity. When authorization is occurring this policy checks to see if both the current user and the app have permission to perform the action being requested. This is useful when the app does not run on the SharePoint server and whats to act on the behalf of the user to get access to the user's specific resources.

The app-only policy only takes into account the app identity. When authorization occurs SharePoint checks to see if the app has permission to perform the action in question regardless of what access the current user or any user might have. In example, the person who installs the app has the rights that the app needs and gives permission for the app to perform those actions for users even though those users might not have permission themselves to directly act. I should note that certain APIs require user context. Thus, they can not be executed with an app-only policy alone. For example, there are many APIs for interacting with Project Server 2013 and for performing search that an app-only policy may not be the appropriate policy choice for your app.


Setting Up Your Solution in Visual Studio 2013

These next steps assume that you have successfully completed the steps found in my previous article of this series.

  1. Open Visual Studio 2013 and click on Start | New Project... or File | New | Project....
  2. Select the App for SharePoint option under the Office/SharePoint menu.

  3. You will be asked to specify a site that you want to use for debugging your app. This is a site collection that is using the Developer Site template. You can have your administrator do this by going through Central Administration | Application Management | Create site collections. If you have already done this point the wizard to that location. Also make sure that Provider-hosted is selected. Click Next.

  4. Specify the ASP.NET Web Forms Application as the type of project you want to create.

  5. On the Configure authentication settings screen you will select the Use a certificate (for SharePoint on-premises apps using high-trust) option. In the appropriate fields you will enter some of the settings set from the previous blog article:

    Certificate location: C:\Certs\HighTrustApps.pfx
    Password: password
    Issuer ID: You can open the .CER file in C:\Certs and use the Issued By name.

  6. Click Finish.

You have just created your first high-trust provider-hosted app! You will need to configure SharePoint 2013 to use the certificate and configure it to trust your app. Again, I warn that this instruction is really only for Development purposes. To package and publish high-trust apps for SharePoint 2013 in Production read this article instead.

Enter the following PowerShell commands:


$publicCertPath = "C:\Certs\HighTrustAppsCert.cer"

$certificate = New-Object System.Security.Cryptography.X509Certificates.X509Certificate2($publicCertPath)

New-SPTrustedRootAuthority -Name "HighTrustAppsCert" -Certificate $certificate

$realm = Get-SPAuthenticationRealm

Next, you need to run this command. Your app will use an access token to get access to SharePoint data. This must be issued by a token issuer that SharePoint trusts. In this case, and for all high-trust apps, the certificate IS the token issuer. This command constructs an issuer ID in the format that SharePoint requires:

$specificIssuerId = "I used my Issued By name here"

$fullIssuerIdentifier = $specificIssuerId + '@' + $realm

In Production the $specificIssuerId must be a GUID because in Production each certificate must have a unique issuer. However, for development purposes you can hard code the value in like I have done.

Continue you along by entering the following:

New-SPTrustedSecurityTokenIssuer -Name "High Trust Apps Cert" -Certificate $certificate -RegisteredIssuerName $fullIssuerIdentifier -IsTrustBroker

The following commands are only ran in the Development scenario. If you do not run this you will get 403 Forbidden errors.

$serviceConfig = Get-SPSecurityTokenServiceConfig

$serviceConfig.AllowOAuthOverHttp = $true

$serviceConfig.Update()

You can save all of those commands into a file called HighTrustConfig-ForDebugOnly.ps1 and later run it again using the ./HighTrustConfig-ForDebugOnly.ps1 command inside the SharePoint Management Shell.

Test your application inside of Visual Studio by hitting your F5 key. If you are presented with the following messages...
































...just click Yes and continue.

You should then see a web page being hosted by localhost (Visual Studio in this case via virtual directory) that contains the name of your Developer Site.

Congratulations! You should see a blank screen with the title of the SharePoint site you are running this app against. If everything is successful, continue now with the instructions on making your app use an App Only policy.

The first step is adding the AllowAppOnlyPolicy to the app's manifest. In Visual Studio this is found under the App Project. You will see two files initially. An AppIcon.png and a AppManifest.xml. You want to open the code for the app's manifest.



















You will add the following code directly above the </app> closing tag.

<AppPermissionRequests AllowAppOnlyPolicy="true" >
    <AppPermissionRequest Scope="http://sharepoint/content/sitecollection/web/list" Right="Read" >
        <Property Name="BaseTemplateId" Value="101" />
    </AppPermissionRequest>
</AppPermissionRequests>

Or you can do this through the GUI just by double-clicking on AppManifest.xml. Then go to the Permissions tab.











NOTE: The BaseTemplateId property you see listed in the example really applies to Lists. If the identifier is not set it means your app will have that permission level on all types of Lists. The 101 listed there means, for example, that the app only has Read to Document Libraries. You can view the full list by visiting http://msdn.microsoft.com/en-us/library/office/ms415091(v=office.15).aspx and looking at the Type attribute.

Last, but not least, how do you use the TokenHelper to utilize the S2S protocol? Open your TokenHelper.cs file in the AppWeb part of the Visual Studio project to look at some of the code there. Specifically take a look at the GetS2SAccessTokenWithWindowsIdentity and the GetClientContextWithAccessToken methods. In your application you would pass a null for the WindowsIdentity parameter to get back a valid OAuth access token

string appOnlyAccessToken = TokenHelper.GetS2SAccessTokenWithWindowsIdentity(_hostWeb, null);

You can then obtain the Client Side Object Model (CSOM) client context to perform actions on the behalf of the user.

using (ClientContext clientContext = 
    TokenHelper.GetClientContextWithAccessToken (_hostWeb.ToString(), appOnlyAccessToken))
{
    List list = clientContext.Web.Lists.GetByTitle("Announcements");
    ListItemCreationInformation info = new ListItemCreationInformation();
    Microsoft.SharePoint.Client.ListItem item = list.AddItem(info):
    item["Title"] = "Created via CSOM";
    item["Body"] = "Created via CSOM on " + DateTime.Now.ToLongTimeString();

    item.Update();
    clientContext.Load(item);
    clientContext.ExecuteQuery();
}

Then to test just deploy your app and log on as a user who only has read permissions to the list. Execute the code and a new item will be created using the application's permissions. If you had included a user identity instead of a null you would see a message stating "...by Application on behalf of User".

In my next article I will explain the process of creating a Windows Service solution that will be used to handle the timing / schedule part of our application.

Sources:
http://msdn.microsoft.com/en-us/library/office/dn268593(v=office.15).aspx

Wednesday, May 21, 2014

My First SharePoint 2013 Timer Job - Setup

Topic:Environment, Configuration, and Programming
Level:Advanced
Intended Audience:Administrator, Architect, Developer, and IT Professional

I have decided to tackle what I considered to be a great starting point for first time app creators. I wanted to show you how I created the equivalent of a traditional SharePoint timer job (what used to be done via a sharepoint solution in sharepoint 2010) inside of SharePoint 2013's App model. Specifically for an on-premise SharePoint farm. This is mostly tailored towards the Developer but, there is a lot of useful information here for Admins, Architects, and IT Pros as well.

Microsoft Developer Network (MSDN) and various blog posts detail bits and pieces of what the IT Professional / Admin, the Developer, or the Architect need to know. Here I will take you from end-to-end. And, hopefully explain a bit along the way. I am assuming very little familiarity here with SharePoint 2013 but at least some understanding of the previous versions of SharePoint.

So what is on-premise?


On-premise software is installed and ran on servers within your organization rather than using servers that reside in the cloud. Opposite of on-premise would be a cloud based computing platform such as Microsoft Azure.

So what is a provider-hosted app?


A provider-hosted app is an application that is deployed and hosted outside the SharePoint farm. So where your solutions used to get installed directly onto the farm in the form of deployed WSP files, these applications do not. They are installed to the host web, but their remote components are hosted on another server. See the following example:


I will be making a few assumptions at this point. But just in case something seems off to you I will let you know in advance what servers I am on and those other types of details. Also, a lot of these steps will not need to be repeated for all of your projects moving forward. For example, you likely will not have to create a certificate every time. You can reuse the same self-signed certificate from your first project. A lot of these steps, however, will need to be repeated or changed a little based on the environment you are working in.

Setting Up Your Project (Development Environment)


The first thing we need to do is generate a self-signed certificate. The SharePoint project is going to require a certificate and for the initial phase of debugging a self-signed certificate works best.

  1. When you are debugging a high-trust app for SharePoint in Visual Studio, the remote web application is hosted in IIS Express on the machine where Visual Studio is installed. So the remote web application computer does not have an IIS Manager where you can create the certificate. For this reason, you use the IIS on the SharePoint test server to create the certificate. In IIS Manager, select the ServerName node in the tree view on the left.
  2. Select the Server Certificates icon, as shown below.

    Server Certificates option in IIS
  3. Select the Create Self-Signed Certificate link from the set of links on the right side, as shown below.

    Create Self-Signed Cerificate link
  4. Name the certificate HighTrustApps, and then choose OK.
  5. Right-click the certificate, and then select Export, as shown below.

    Exporting a test certificate
  6. In Windows, or at the command line, create a folder called C:\Certs.
  7. Back in IIS Manager, export the file to C:\Certs and give it a password. In my example above I used the password of password.
  8. If your test SharePoint installation is not on the same computer where Visual Studio is running, create a folder C:\Certs on the Visual Studio computer and move the HighTrustApps.pfx file to it. This is the computer where the remote web application runs when you are debugging Visual Studio.
Now we need to create a corresponding .cer file.

  1. On the SharePoint server, be sure that the app pool identity for the following IIS app pools have Read rights to the C:\Certs folder:
    • SecurityTokenServiceApplicationPool
    • The app pool that serves the IIS web site that hosts the parent SharePoint web application for your test SharePoint website. For the SharePoint - 80 IIS website, the pool is called OServerPortalAppPool.
    • You can see the Identity to use by looking under the Application Pools located under the ServerName node in the tree view on the left. Then just update the folder permissions to give that Identity Read access.
  2. In IIS manager, select the ServerName node in the tree view on the left.
  3. Double-click Server Certificates.
  4. In Server Certificates view, double-click HighTrustApps to display the certificate details.
  5. On the Details tab, choose Copy to File to launch the Certificate Export Wizard, and then choose Next.
  6. Use the default values and choose Next.
  7. Choose Browse, browse to C:\Certs, name the certificate HighTrustAppsCert, and then choose Save. The certificate is saved as a .cer file.
  8. Choose Next.
  9. Choose Finish.
If this has not been done yet we need to configure services in SharePoint 2013 for server-to-server app use.

  1. Ensure that the app management service and the user profile application are configured. The steps are as follows:
    • In Central Administration, under Application Management, select Manage service applications.
    • On the Service Applications page, ensure that the following services are started:
      • User Profile Service Application
      • App Management Service
    • Under Application Management, select Manage services on server.
    • On the Services on Server page, ensure that the following services are started:
      • User Profile Service
  2. Ensure that at least on profile is created in the User Profile Service Application. The steps are as follows:
    • In Central Administration, under Application Management, select Manage service applications.
    • Next, select User Profile Service Application.
    • On the Manage Profile Service: User Profile Service Application page, under People, select Manage User Profiles.
    • On the Manage User Profiles page, select New Profiles.
    • On the Add User Profile page, type your account name and email address.
    • Select Save and Close.
      • NOTE: If you get a message saying that the profile you are trying to create already exists, simply Cancel and Go Back.
    • Back on the Manage User Profiles page, you should see Total number of profiles: 1.
Again, if you have not done so already you need to install the Visual Studio 2013 developer tools found at http://msdn.microsoft.com/en-US/office/dn448479. This allows some key components of app development.

As an additional tip, you can enable verbose logging inside of Visual Studio 2013 by doing the following:
  1. Open the registry using regedit and navigate to HKEY_CURRENT_USER\Software\Microsoft\VisualStudio\12.0\SharePointTools.
  2. Add a DWORD key named EnableDiagnostics.
  3. Give the key the value 1.


If you want to create and deploy SharePoint-hosted apps on your SharePoint 2013 installation, you must create an isolated domain on the server where your apps for SharePoint will run. In this example I will show how to do this on the development workstation you are on. For development purposes, you can modify your hosts file as you need to route your development computer to a test instance of an app for SharePoint.

  1. Ensure that the spadmin and sptimer services are running by opening a command prompt and typing the following commands:

    net start spadminv4

    net start sptimerv4
  2. Create your isolated app domain by running the SharePoint Management Shell as an administrator and type the following command:

    Set-SPAppDomain "apps.mydevdomain.com"
  3. Ensure that the SPSubscriptionSettingsService and AppManagementServiceInstance services are running by typing the following command in the SharePoint Management Shell.

    Get-SPServiceInstance | where{$_.GetType().Name -eq "AppManagementServiceInstance" -or $_.GetType().Name -eq "SPSubscriptionSettingsServiceInstance"} | Start-SPServiceInstance
  4. You must specify an account under which the SPSubscriptionService and AppManagementServiceInstance service instances will run. This account must be an SPManaged account. You can create an SPManagedAccount by typing the following command in the SharePoint Management Shell. Please note, you will be prompted for the account DOMAIN\user and password.

    $account = New-SPManagedAccount
  5. Next you need to specify an account, application pool, and database settings for the SPSubscriptionService and AppManagementServiceInstance services by typing the following code into the SharePoint Management Shell. If you created a SPManagedAccount in the preceding step, use that account name here.

    $account = Get-SPManagedAccount "DOMAIN\user"

    $appPoolSubSvc = New-SPServiceApplicationPool -Name SettingsServiceAppPool -Account $account

    $appPoolAppSvc = New-SPServiceApplicationPool -Name AppServiceAppPool -Account $account

    $appSubSvc = New-SPSubscriptionSettingsServiceApplication -ApplicationPool $appPoolSubSvc -Name SettingsServiceApp -DatabaseName SettingsServiceDB

    $proxySubSvc = New-SPSubscriptionSettingsServiceApplicationProxy -ServiceApplication $appSubSvc

    $appAppSvc = New-SPAppManagementServiceApplication -ApplicationPool $appPoolAppSvc -Name AppServiceApp -DatabaseName AppServiceDB

    $proxyAppSvc = New-SPAppManagementServiceApplicationProxy -ServiceApplication $appAppSvc
    • NOTE: When I ran this for the first time I got a "The timer job did not complete running within the allotted time." error. To resolve that error message or others you come across I had to do a few additional troubleshooting steps.
      • I first checked to ensure that the SharePoint Timer Service under Administrative Tools | Services was in fact running.
      • I checked that my cache cluster was up for Distributed Cache. To do so type in the following command into the SharePoint Management Shell:

        Get-CacheHostConfig -ComputerName $env:computername -CachePort 22233

        That command should give you information about the current cache host. If that command does not work you may have to create a new cache cluster. The details of which can be found at http://msdn.microsoft.com/en-us/library/ff921027.aspx.
      • If your cache is up and running, try the following commands:

        Remove-SPDistributedCacheServiceInstance

        Add-SPDistributedCacheServiceInstance
      • If you still get unexpected errors try the following command:

        Restart-CacheCluster
      • Also you should check your service account's file read access to "C:\Program Files\AppFabric 1.1 for Windows Server\DistributedCacheService.exe.Config". Your service accounts may need to be granted read access to the top-level AppFabric directory if you are seeing script errors in the SharePoint Management Shell.
      • And finally, if all else fails try the following commands:

        Export-CacheClusterConfig -path D:\clusterconfig.xml

        Stop-CacheCluster


        Check within the config file if the host name is correct (change to the netbiosname) and that the service account is the same as is listed for your AppFabric Caching Service in services.msc.

        To import the configuration again use the following command:

        Import-CacheClusterConfig -path D:\clusterconfig.xml

        Start-CacheCluster


        To confirm everything is working properly try the following:

        Get-Cache

        Get-CacheClusterHealth
  6. Next you need to specify your tenant by typing the following command into the SharePoint Management Shell.

    Set-SPAppSiteSubscriptionName -Name "app" -Confirm:$false
You now need to add your isolated app domain to your IE bypass list. This ensures that you can navigate to that domain after you deploy a SharePoint-hosted app. You can skip this if your environment does not use a proxy server.
  1. In Internet Explorer, go to Tools.
  2. Choose Internet options.
  3. On the Connections tab, choose the LAN Settings button.
  4. Clear the Automatically detect settings check box.
  5. Select the Use a proxy server for your LAN check box.
  6. Choose the Advanced button, and then add *.YourAppDomain.com to the Exceptions list.
  7. Choose the OK button.
  8. Choose the OK button to close the Local Area Network (LAN) Settings dialog box.
  9. Choose the OK button to close the Internet Options dialog box.
EDIT: If you get a 401.1 Unauthorized Logon Failed message or logon prompts you may have to disable the loopback check. Just follow Method 2 of the following article to do this. That article can be found at http://support.microsoft.com/kb/896861.

That's it! Your server (isolated app) to server (SharePoint 2013 server) foundation is now setup. In my next post I will walk you through creating a high-trust provider hosted app for your SharePoint installation that uses a app only policy. Taking us one step closer to mimicking a SharePoint 2010 timer solution.