Introduction

This document will be used to outline the process for implementing Azure’s ACS namespace as a trusted identity provider to an on-premise SharePoint environment, utilizing external identity providers such as Facebook, Yahoo, or Windows Live ID to pass manipulated claims as a standardized trusted token to SharePoint

Preface, Considerations, Prerequisites

  • Azure ACS authentication with SharePoint is a free service as of 12/2014. The service requires a subscription to Azure, but costs no money. A $0 spending limit can be set to prevent the possibility of any charges coming through from this account.
  • The Azure ACS system can utilize any Identity Provider that can export an OpenID claim
  • SharePoint 2013 does not support SAML 2.0, SAML 1.1 must be used
  • As of 12/2014, Windows Live ID can only export a nameidentifier claim, but this can be mapped to an email address claim to use as a UPN for login
  • An x.509 SSL certificate needs to be uploaded to Azure to sign tokens, and to explicitly trust in SharePoint

Definitions/References:

Azure ACS – ACS (access control system) is a free feature of Azure that allows the developer to create a namespace that can tie external Identity Providers incoming tokens to a single claim to a web application
Azure Namespace – the item in Azure that provides the URL for all Identity Providers, Relying Party Applications, Rule Group Settings, and Certificates and Keys to be trusted
Identity Provider – an external service, such as Yahoo!, Facebook, or Windows Live ID, that provides the inherently trusted authentication to SharePoint
Relying Party Application – these are the web applications that are connected to the namespace that receive the token that is output from the Azure ACS namespace. In this walkthrough, SharePoint 2013 is our Relying Party Application
Rule Groups – Rule groups are the list of incoming claims tied to claim issuers/identity providers, how they may be mapped when exported, as well as any customizations that need to happen for the token itself

Azure Setup

Creating the Namespace
  1. Login to the Azure management portal at https://manage.windowsazure.com with the Azure account created prior to this work. Note: Ensure that this account has a subscription set up prior to continuing any further, any work created with a trial account will expire once the trial is over, and are unable to be transferred to a setup account
  2. Once logged into the management console, click the large NEW button at the bottom left of the screen to begin the process of creating a namespace
  3. Azure1

  4. Navigate App Services > Active Directory > Access Control > Quick Create:
  5. Azure2

  6. Give the namespace a name that makes sense for the authentication set up (this won’t be an actively used URL by an end-user). Select your region, and the subscription that has been set up (Pay-As-You-Go, or another valid subscription, NOT free trial). The namespace status will change from creating to active:
  7. Azure3

  8. Click on the newly created namespace, and click the manage button on the bottom ribbon, this will take you to the Silverlight based Windows Azure Platform Access Control Service control panel:
  9. Azure4

  10. Utilize the Getting Started steps that appear on the homepage of this control panel for much of the work. You will now want to set up the Identity Providers:
Making Windows Live ID Work for SharePoint 2013 Authentication

Since the Windows Live ID Identity Provider is a preset default in the Azure ACS namespace, I will use it as a full example on configuring the claim issuer for authentication in SharePoint, and will later lead into how to configure additional Identity Providers.

Configure Relying Party Applications
  1. Navigate to the Relying party applications management by clicking the URL on the left-hand side of the ACS administrative panel
  2. Click the Add URL at the top left of the Relying Party Applications table
  3. On the configuration page, enter in the following information:
    Name: a display name such as “SharePoint2013” is fine for this as it is simply a display name for SharePoint’s trust with ACS
    Realm: the realm will be equal the resolvable url for your SharePoint web application (https://winchestertonfieldville.ia.gov/) would work fine if this is your SharePoint web application URL
    Return URL: this is the URL in which ACS will return tokens to SharePoint. This will always be the same URL as the realm defined above, with “/_trust” appended to the end (https://winchestertonfieldville.ia.gov/_trust)
    Error URL (optional): This is the URL for an optional error page in case authentication fails
    Token Format: Choose SAML 1.1, SharePoint 2013 is NOT compatible with SAML 2.0
    Token lifetime (secs): This value represents the seconds that the token is valid before expiring, or how long the user will be able to hit the realm URL repeat times and be auto-authenticated back in to the environment. The default value of 600 seconds is typically on the low side. Set this value to 3600 seconds (equal to the default value in ADFS).
    Identity Providers: the list of Identity Providers that you would like to have as optional authentication methods when users hit the realm’s login page. Each Identity Provider will show in the login drop down
    Rule Groups: leave the check box to create a new rule group as we will be doing this in the next step
    Token Signing: Choose whether to Use service namespace certificate or Use a dedicated certificate. For the purposes of this walk through, I would recommend choosing Use a dedicated server and upload the X.509 certificate .pxf file to use for when signing. Browse to the file, upload, and input the password that was created when it was exported from the server.
  4. Click Save
Configure Rule Groups

The rule groups are the configuration for what claims Azure will receive from the Identity Providers, as well as how they will map these claims to the output token.

  1. Navigate to the Rule Groups page by clicking the URL on the left-hand navigation
  2. Click the “Default Rule Group for <RelyingPartyApplication>” that was automatically created when we set up the Relying Party Application
  3. On the Edit Rule Group page, feel free to edit the name for the rule group
  4. In the Rules table, click the Generate URL. You will notice that the Rules table currently shows “No rules have been added. Click Generate to generate rules automatically, or click Add to add rules manually.” Note – If additional Identity Providers are added at a later time, use this option to generate new rules for the new identity providers
  5. On the following page, click the checkbox next to Windows Live ID, and click Generate
  6. You will then see the that the nameidentifier output claim from Windows Live ID is listed as a rule. Click on the nameidentifier URL.
  7. On the resulting page, you can see how to configure the input/ouput of this claim for how ACS will prep it for the output token that will be trusted by SharePoint. By default, nameidentifier is not a usable claim for a login in SharePoint. To address this, we will map the output claim type to email address.
  8. For everything under the If section, leave default
  9. For the “Then” section, change the select type dropdown from http://schemas.xmlsoap.org/ws/2005/05/identity/claims/nameidentifier to http://schemas.xmlsoap.org/ws/2005/05/identity/claims/emailaddress to map the claim from the nameidentifier URI to a usable email address login
  10. You can leave all other items as default, or add information under “Rule Information” that will explain that we are mapping the Windows Live ID nameidentifier claim to an emailaddress output claim
Upload Token Signing Certificate

Azure ACS uses an X.509 certificate to digitally sign the tokens it generates. You can also increase the functionality of this certificate to include encryption/decryption of the tokens themselves. Many users will use the makecert utility to create a self-signed certificate for testing purposes, but do not do this in a production environment.

  1. Click the Certificates and Keys URL on the lefthand side of the Azure ACS configuration page
  2. Click the Add URL at the top of the Token Signing table
  3. On the “Add Token-Signing Certificate or Key” page, select the correct Relying Party Application in the dropdown.
  4. Select X.509 Certificate for type
  5. Click Choose file and upload the .pfx file. Note: On this page, it also shows how to use the MakeCert utility from the Microsoft SDK to make this certificate.
  6. Click Save

SharePoint 2013 Configuration

Within SharePoint, we will move forward in this walkthrough with the assumption that the Web Application within SharePoint 2013 has already been created with a friendly URL assigned to it.

  1. Log in to the Central Admin server
  2. Open a PowerShell ISE session as an administrator and run the following:
  3. I would recommend running the above code line by line to ensure you can identify any errors as they happen, rather than an error that you can’t attribute to a single line of code when bulk running the block
  4. Open Central Administration and click Manage Web Applications
  5. Click the web application that we have been using thus far, and click Authentication Providers in the ribbon.
  6. In the appropriate zone, you should be able to see empty check boxes for the newly created Trusted Identity Providers that we have set up. Check the boxes next to Windows Live ID
  7. Press Save
  8. SharePoint now knows to trust any SAML1.1 tokens that come from the specific Azure ACS namespace that we have created, and knows how to parse the claims within the token.

You are now complete! You now should be able to hit the SharePoint Web Application URL, be redirected to an Azure ACS hosted login page, be able to choose between windows authentication or Windows Live ID, be redirected to the Windows Live ID login page to authenticate, and automatically be pushed back to SharePoint. As of our current configuration performed thus far, the users will hit a “You are not authorized to view this page” SharePoint page. For security, I would recommend enabling Access Request settings for the root Site Collection, and setting the recipient to a HA individual, or a distribution group to be able to triage requests from possible users as they hit your environment.


8 Comments

kmon · March 27, 2015 at 8:17 am

“As of our current configuration performed thus far, the users will hit a “You are not authorized to view this page” SharePoint page.” So after setting up the ACS, user still can’t access the sharepoint pages? What are the things need to do further to be authorized ?

    jhladish · March 27, 2015 at 11:57 am

    This was done on purpose for security for this write up. I did not want simply any user that could authenticate to Windows Live, Facebook, or Yahoo to be able to access the SharePoint site. With them hitting a “This page has not been shared with you” page, I have enabled the invitation request and I can then set the permissions for each user as they hit the site for their first time.

    Alternatively, if you want users to be able to jump straight into the environment, you can set a user policy within the farm for the web application to allow all users from the OpenID provider “group” read access or something similar. This will allow them to get into the site without hitting that wall first. Hope this helps.

Sid · April 29, 2015 at 3:50 pm

Finally I found a tutorial that has everything all in one place! Thank you. Especially for the part that no other tutorial has mentioned, “nameidentifier is not a usable claim for a login in SharePoint”

I am running into an issue though. When I successfully login in on the Windows Live page, I am redirected back to the login page, even though I have the Redirect URL specified as https://mysite/_trust/.
The token time is set to 3600 and format to SAML 1.1

Not sure if it is related, but when I tried to add $map3 from the script, I got an error:
“http://schemas.xmlsoap.org/ws/2005/05/identity/claims/name is a reserved claim type.”
So I changed that line to this:
$map1 = New-SPClaimTypeMapping -IncomingClaimType “http://schemas.xmlsoap.org/ws/2005/05/identity/claims/name” -IncomingClaimTypeDisplayName “Name” -LocalClaimType “http://schemas.xmlsoap.org/ws/2005/05/identity/claims/upn”

Do you have any clue as to why I am stuck in a login loop?

Thanks in advance!

    jhladish · August 23, 2017 at 1:46 pm

    Sid – I’m estatic to hear that this walkthrough was helpful for you as I was experiencing the same issue when attempting to find a walkthrough when implementing this myself. Thankful for the positive feedback I’ve received for this.

    With that said, I’ll say that SharePoint is an application I have not worked with for around a year or so now, and before that, this project was done much before that even. The architecture within the system may have changed from then to now, so I can’t make a definitive answer.

    The reserved claims type sounds like an issue with trying to use an existing variable (name being an obviously common variable name) in conjunction with your configuration. Even those this comment is years old now, I would love to hear if you made any discoveries to get this working end to end so I could update this blog post for any others that get here.

    Unfortunately more, the client ended up scrapping this entire fun project I outlined here, so I never got to see it to fruition 🙁 I hope that you were able to come up with a solution!

Stephen Welch · September 4, 2015 at 2:49 pm

Can you give us some information about purchasing a x.509 cert for *.accesscontrol.windows.net? What specifically do you purchase? When you attempt to purchase a cert for a domain that you own (accesscontrol.windows.net) will it allow you to do that? In the past it contacts a domain owner doesn’t it?

    jhladish · August 23, 2017 at 1:51 pm

    As outlined, you can make your own using the makecert command. This will be self-signed, and many feel doesn’t give the security of a properly secured cert from an official/well-known CA issuer. Creating your own will also many times prompt a windows security message questioning whether or not the cert should be trusted which isn’t ideal in many implementations.

    Sites exist that give certs like this for free, and other locations require a purchase. This is a decision that your security team may have a strong opinion on to direct your choice that I would advise you review with them before moving forward (never want to cause an internal struggle or headache).

    Sorry for this being an EXTREMELY late response. I hope you found the information you were looking for. If you’d like, feel free to reply with any supplementary information you found and I’d gladly add it to this post for future references by others. Hope that you were able to resolve this.

wneiton · July 7, 2016 at 2:31 pm

Hi,

I thanks by the “nameidentifier is not a usable claim for a login in SharePoint”, I was struggling with it, now I can either login with Windows Live or Facebook, but the Users name is not showing up but rather their claim token. The username for example on the top right of the SP page is not displaying the email or the users name but a nasty claim token. The only one that is working fine is Google emailaddress.

Does anyone have any ideia?

Thanks
Wneiton

    jhladish · August 23, 2017 at 1:54 pm

    Wneiton –

    Late response, but as you may read in another comment, this project ended up getting scrapped by the client I was working with at the time, and this was the exact reason. The most usable IDPs were the least practical (who wants to auth using Facebook for a work-based application?!). I’m happy to hear that this was helpful for you. I have been out of the SharePoint world for coming up on two years now, so the architecture of this auth method may have changed since then and have given more capabilities/flexibility, or maybe it’s still an issue.

    If you came up with a solution for this, I’d love to have closure on this issue that I also experienced

Leave a Reply

Your email address will not be published. Required fields are marked *