Web Services Federation

Web Services Federation (WS-Federation) is an identity federation specification that defines the mechanism of allowance for different security realms or domains to transfer information on identities, identity attributes and authentication tokens.

You can configure Enterprise Application Access (EAA) as an identity provider (IdP) to work with an application as a relying party that uses the WS-Federation protocol in passive requestor profile mode. In the context of WS-Federation specification, EAA IdP is a Security Token Service (STS) provider. As an STS provider, EAA IdP supports only SAML 1.1 tokens.

The WS-Federation protocol is the only identity federation protocol of choice for many legacy Microsoft applications such as Sharepoint.

Below diagram describes the communication between the federation server in service provider (SP) realm, the federation server in the EAA IdP realm, and the user's computer and browser. It allows the authenticated user access on-premise applications such as Sharepoint.

IWS-Federation flowIWS-Federation flow

Authentication of a user to access a custom SaaS application like Sharepoint using WS-Federation protocol:

  1. User requests access to a service, like Sharepoint server, which is protected by SP federation server.

  2. The SP verifies that there is no authenticated session and that the requester (browser) did not present a WS-Federation trust token from a trusted STS provider. It then redirects the requester to the trusted STS provider with an authentication request.

  3. The STS provider validates the request and establishes the user identity using the configured authentication schemes. If the user had previously logged into the IdP, the identity is established by the existing session.

  4. User information is retrieved by the IdP federation server using user's attributes in LDAP or AD for authorization.

  5. The IdP federation server generates a SAML 1.1 assertion and returns it to the SP federation server, through the browser.

  6. The SP verifies the received SAML 1.1 token (authentication statement, attribute statement, and signature) based on pre-established trust. If the SAML 1.1 token and the user identity embedded in the token are acceptable to the SP, it generates a new session that grants access to the requester for a duration that may depend on its local session policy.

  7. The requester is granted access to the application resources scoped by the user's identity and other attributes such as group membership for the duration of the session.

Configure EAA as the STS provider to access a SaaS application

Configure Enterprise Application Access (EAA) as the identity provider (IdP) that acts as the secure token service (STS) provider for a SaaS application that supports WS-Federation protocol.

  1. Log in to Enterprise Center.

  2. In the Enterprise Center navigation menu, select Application Access > Applications > Applications.

  3. Click Add Application (+).

  4. Enter a name and an optional description. In Type Select New SaaS App, and in protocol select WS-Federation.

  5. Click Add Application.
    The application Settings opens.

  6. In the Application URL field, enter the external URL of the application, like the Sharepoint site. The application URL is the path that users get to access the application. For example: http://sharepoint.secperimeter.com/.

    1. You can select Hide Application from Login Portal.
  7. Click Authentication and enable Authentication.

  8. Select an Akamai IdP and associate a directory source such as Active Directory (AD) or Lightweight Directory Access Protocol (LDAP).

  9. Click WS-Federation Settings.
    The STS provider settings fields are pre-populated and non-editable.

FieldValue
Sign-in URLThe sign-in URL of STS provider using a WS-Federation passive protocol.
Sign-out URLThe sign-out URL of STS provider configured in a WS-Federation supported application.
Signing certificateIdentity provider signing certificate to trust STS token.

If you use a self-signed certificate, download the certificate and the root certificate that was used to generate the self-signed certificate. Copy them to two notepad files and upload them to the Sharepoint server. For example, WS-FED-Cert.crt is the self-signed certificate and SohaCA.crt is the root certificate. If you use a certificate from a well-known certificate authority (CA), you need to download only this certificate, and upload it to Sharepoint server.

  1. Copy the sign-in URL of the STS provider settings.

  2. Click Save. Do not deploy the application at this time.

Next, configure the Sharepoint administration server to allow EAA to act as an STS provider and add users of EAA IdP to access Sharepoint application with specific permissions.

  1. Upload the certificates into the Sharepoint server. Assign the certificate to variables using Powershell:
$cert = New-Object System.Security.Cryptography.X509Certificates.X509Certificate2("C:\Shared\WSED- Cert.crt")
$root = New-Object System.Security.Cryptography.X509Certificates.X509Certificate2("C:\Shared\SohaCA.crt")
  1. Add this to the TrustedRoot of Sharepoint:
NewSPTrustedRootAuthority -Name "Token Signing Cert Alpha-UITest-IWA-IDP" Certificate $cert
NewSPTrustedRootAuthority -Name "RootCA Alpha-UITest-IWA-IDP" Certificate $root`
  1. Add the claim types for the Sharepoint server. Sharepoint uses these claims to trust Enterprise Application Access as an STS provider when it sends SAML 1.1 tokens. For example, to add userprincipalname (UPN), role, and email address as claim types in Sharepoint, create these variables and assign these values:
$upnClaimMap = New-SPClaimTypeMapping -IncomingClaimType "http://schemas.xmlsoap.org/ws/2005/05/identity/claims/upn" - IncomingClaimTypeDisplayName "UPN" -SameAsincoming
$upnClaimMap = New-SPClaimTypeMapping -IncomingClaimType "http://schemas.microsoft.com/ws/2008/06/identity/claims/role" - IncomingClaimTypeDisplayName "Role" -SameAsincoming
$upnClaimMap = New-SPClaimTypeMapping -IncomingClaimType "http://schemas.xmlsoap.org/ws/2005/05/identity/claims/emailaddress" - IncomingClaimTypeDisplayName "EmailAddress" -SameAsincoming

You can add more or fewer claims, as required by your organization.

  1. Create a new variable called $realm and set it to the value as the EAA configuration for STS provider section. For example, $realm = "http://sharepoint.secperimeter.com/_trust".

  2. Create a new variable for the sign-in URL and assign the value from previous steps: $signInURL = "https://alpha-iwa-idp.secperimeter.com/wsfed/idp/sso".

  3. Create a trusted provider in Sharepoint using the previous variables. Create a new variable SPTrustedIdentityTokenIssuer with use of the variables you created in previous steps and configure it as following:

$iwaap = New-SPTrustedIdentityProviderTokenIssuer -Name "Alpha_UITest-IWA-IDP" -Description "EAA Trusted Identity Provider Alpha-UITest-IWA-IDP" -realm $realm -ImportTrustCertificate $cert -ClaimsMappings $emailClaimMap,$upnClaimMap,$roleClaimMap -SignInURL $signInURL -IdentifierClaim "http://schemas.xmlsoap.org/ws/2005/05/identity/claims/upn"
  1. The EAA STS provider appears as the Trusted Identity Provider in the Sharepoint server site. Select it as a Trusted Identity Provider.

  2. Click Security in Sharepoint server and select Specify web application user policy and allow users to edit and view on the Sharepoint site.
    Configure permissions for a specific user, or for all the users from the identity provider.

  3. Select the application you created in previous steps to complete the following:

    1. Click WS-Federation Settings.

    2. In Relying party settings configure the service provider realm.

    3. Copy Realm from previous steps and paste it in Realm.

    4. Copy Application URL from previous steps and paste it in Application URL.

    5. Select NameID format and NameID attribute values that apply.

    6. Enter a value [sec] for Token Life.

For example:

Realm: http://sharepoint.secperimeter.com/_trust
Application URL:http://sharepoint.secperimeter.com/_trust
FieldValue
RealmThe relying party identifier to be configured in a WS-Federation supported application. Same as the $realm variable in Sharepoint.
Application URLA URL on the application which initiates the WS-Federation login request to the STS provider.
NameID formatThe subject name identifier in SAML 1.1 sent in the STS token.
NameID AttributeSelect user attribute to be sent as NameID value. The selected value should comply with the specified NameID format. This is the directory value sent in the STS token.
Signout URLLogout endpoint of a WS-Federation supported application called by EAA for EAA IdP-initiated logout. The URL to trigger logout from the application.
Token lifeThe duration of a valid STS token, in seconds.
  1. In Claim statements configure all of the claim types that you specified in previous steps.
    This is needed to pass user-related attributes from user directories in the IdP realm to the SP realm when the same directory store is not present, and is used by the application.

  2. Click Save.

  3. Deploy the application.

Next, verify the EAA IdP setup.

  1. Access the Identity Portal URL and log in with your AD credentials. This is the application URL from previous steps (for example, http://sharepoint.secperimeter.com/).

  2. Click the application card for the Sharepoint application.
    It redirects you to the Sharepoint application portal.

  3. Sign in to access the Sharepoint application.

Configure WS-Federation for an access application

Use WS-Federation protocol as the application-facing authentication mechanism for an EAA access application. Create the app and configure it's advanced settings.

  1. Log in to Enterprise Center.

  2. In the Enterprise Center navigation menu, select Application Access > Applications > Applications.

  3. Click Add Application (+).

  4. Select New Access App for type. Type a name and optional description.

  5. Click Add Application.

  6. Complete all of the settings in the Settings, Connectors, Authentication, Access, and Services tabs. For more details, see Configure access parameters for an application.

  7. Click Advanced.

  8. In Application facing authentication mechanism select WS-Federation .

  9. In WS-Federation configure all the parameters as in above Configure EAA as the STS provider to access a SaaS application. But, set Application URL as an internal URL.

  10. Add Claim statements, just like above in Configure EAA as the STS provider to access a SaaS application.

  11. Click Save.

  12. Deploy the application.

Next, complete all of the configurations in the Sharepoint application as in above Configure EAA as the STS provider to access a SaaS application.