WS-Federation and WS-Trust

DirX Access supports federation via the WS-Federation framework (version 1.2) and employs the requesting protocol WS-Trust (version 1.3). The role of DirX Access as an identity federation provider is enabled by two services residing on the WS-Federation endpoint: Security Token Service (STS) and Passive Requestor Profile (PRP) service.

The WS-Trust protocol messages can carry the identity token. WS-Trust itself does not determine the standard used for the token’s syntax and semantics. DirX Access uses its ability to produce SAML messages and offers the administrator to choose either SAML 1.1 or SAML 2.0 as the token type (see the “RST Token Type” element in the section “Configuring WS-Federation STS Endpoint Settings” in the chapter “Administrative Tasks”).

Deployment

DirX Access enables you to deploy a Federation Endpoint (FEP) supporting the WS-Federation standard using the Federation | Web | WS-Federation section of DirX Access Manager. For details on how to use this section, see the “Administrative Tasks” chapter.

After a successful deployment, DirX Access Manager creates a wsfed WS-Federation FEP application under the Services webapps folder.

Security Token Service

STS provides the SOAP web services interface for the WS-Trust identity federation. The STS is accessible via the URL: https://your_dxa_server_name:_port_/wsfed/sts.

The security policy applied to the SOAP communication is configured via the dxa-common-sts-policy.wsdl file. You can make changes to this file; however, the changes need to be projected onto the STS configuration within DirX Access Manager (specifically, the “RST key type” and the cryptography-related elements).

DirX Access enables determining the user for which the identity tokens should be issued in two ways:

  • With the SOAP Message Originator. The originator of the SOAP message may include certain forms of its credentials in the SOAP Security Headers. These headers are inspected against the methods of authentication set in “Authentication method identifiers via SOAP Security headers”. On successful authentication, the user for which the identity tokens should be issued is the user authenticated via the Security Headers (which is typically the SOAP Message Originator).

  • With the OnBehalfOf Element Identity Reference. The OnBehalfOf element enables decoupling the user to authenticate from the message originator (the example of the typical use case is given below). The element enables including a reference to an identity (authentication method) in an arbitrary manner. DirX Access enables setting up the actual authentication method used via “Authentication method identifier via OnBehalfOf element”.
    Once the OnBehalfOf element is present, the identity is attempted to be resolved from the information in the element; otherwise, the SOAP Message Originator method is used.
    In the scenario where the contacted service provider offers the protected service of another party, it may ask the identity provider to issue the security token on behalf of the already authenticated user. In this case, the token resulting from the initial request (described in section above) is placed as content into the OnBehalfOf element in the new request. In this way, the user does not need to authenticate or ask for authorization each time s/he carries out the additional step at the service provider side.

Passive Requestor Profile

The Passive Requestor Profile (PRP) provides the Web agent-based binding for the WS-Trust identity federation. Using PRP, the complex construction of the Requested Security Token (RST) and the enveloping SOAP message is left to the server side and the initial identity federation request can be made easily in human-readable form (for more information, see the WS-Trust 1.3 standard). The PRP is accessible via the URL: https://your_dxa_server_name:_port_/wsfed/prp.

For detailed information about the PRP, see the WS-Federation specification. To summarize, the actual request is an HTTP GET method request containing specific parameters. The number and complexity of the parameters can vary and depend on the configuration of both the service provider and the identity provider (DirX Access). The configuration of DirX Access with respect to the WS-Federation endpoint is described in the section “Configuring the WS-Federation STS Endpoint Settings” in the chapter “Administrative Tasks”.

In PRP, the identity to be authenticated is determined using the usual DirX Access authentication process. The FEP is protected by a configured PEP and requires the client side to be authenticated. The authentication proceeds according to the PEP authentication configuration and a session identifying the client is established. This client’s identity is subsequently used as the one for which the identity tokens are issued during the identity federation process.

The simplest example of a PRP request is:

http://my-server.my-company.example:11114/wsfed/prp?wa=wsignin1.0&wtrealm=<realm_identifier>

The most complex ones can include the entire RST with any supported parameters (again, care must be taken on the security policies of the processing STS).

RSTR Claim Types Resolution

Claim types contained in the RSTR are determined according to the following algorithm:

  1. If the RST explicitly contains requested claim types, include claims of these types in the RSTR. If the STS can’t resolve a claim type, it is omitted from the RSTR.

  2. Otherwise, identify the relevant peer metadata in the following way:

    1. If the STS is requested directly, retrieve a peer identifier from the ReplyTo element of the SOAP Headers.

    2. If the STS is requested through PRP, gain a peer identifier from the requestor’s URL address.

Match the retrieved peer identifier with the declared endpoint addresses from the ApplicationServiceEndpoint elements of all available peers. Each peer metadata may contain multiple ApplicationServiceEndpoint elements. The matching algorithm is protocol-sensitive, so the full addresses of all allowed communication protocols (for example, HTTP, HTTPS) should be declared in the metadata:

  • If the identified metadata contains a non-empty ClaimTypesRequested element, include claims of the types in the RSTR. If the STS can’t resolve a claim type, it is omitted from the RSTR.

  • If the “Always include offered claims” switch of the STS configuration object is set to true, include the claims of the claim types declared in ClaimTypesOffered of the requested STS endpoint metadata.

  • Otherwise include no claims.

Microsoft SharePoint Support

DirX Access supports the WS-Federation Passive Requestor Profile for authentication and authorization in Microsoft SharePoint.

Configuration Steps for Microsoft SharePoint

Most of the configuration on the SharePoint server needs to be performed with the Windows PowerShell for SharePoint. The configuration outlined here assumes that the SharePoint Web application and site already exist. See the “Windows PowerShell for SharePoint Foundation reference” on Microsoft Technet for details about the security cmdlets used.

Open the SharePoint Management Shell with the Run As Administrator option.

  1. Set the following variables to the appropriate values:

    # Specify name for remote Identity Provider
$idpName = "My-Company Federation"
# Specify name of existing Web application in SharePoint
$webApplicationName = “http://my-server.my-company.example:8082/”
# Specify file with PEM-encoded signing certificate
$idpCertFile = "c:\DirXAccess\My-Company Signing.cer"
# Specify arbitrary name for trusted root CA to be created for IdP certificate
$idpTrustedRootCaName = "My-Company"
# Specify the URL of DirX Access WS-Federation Passive Requestor Profile
# endpoint
$idpSigninUrl = "https:/my-server.my-company.example:11125/wsfed/prp"

  2. Create a PowerShell certificate object from the certificate file that was exported from DirX Access:

    $cert = New-Object system.security.cryptography.x509certificates.x509certificate2($cert_path)

  3. Create a claim type mapping for the claims like email address:

    $map = New-SPClaimTypeMapping "http://schemas.xmlsoap.org/ws/2005/05/identity/claims/emailaddress" -IncomingClaimTypeDisplayName "emailaddress" -LocalClaimType http://schemas.xmlsoap.org/ws/2005/05/identity/claims/emailaddress

  4. Set the realm that SharePoint uses when communicating with the IdP:

    $realm = $webApplicationName

  5. Create the trusted identity token issuer in SharePoint:

    $idp = New-SPTrustedIdentityTokenIssuer -Name $idpName -Description "DirX Access with My-Company population" -Realm $realm -SignInUrl $idpSigninUrl -ImportTrustCertificate $cert -ClaimsMappings $map -IdentifierClaim $map.InputClaimType

  6. Add the self-signed IdP certificate to the list of trusted root certificates in SharePoint. You either need to use a self-signed certificate or you need to import the CA certificate here. The certificate also needs to be imported as a trusted root certificate in Windows.

    New-SPTrustedRootAuthority -name $idpTrustedRootCaName –Certificate $idpCertFile

  7. Change the authentication provider for the existing application to the newly created one:

    $webApplication = Get-SPWebApplication $webApplicationName
$idp = Get-SPTrustedIdentityTokenIssuer $idpName
Set-SPwebApplication $webApplication -AuthenticationProvider $idp -Zone Default

  8. Enforce the use of the “wreply” parameter (only needs to be invoked for changing the SPTrustedIdentityTokenIssuer):

    $idp = Get-SPTrustedIdentityTokenIssuer $idpName
$idp.UseWReplyParameter = $true

  9. Finally, update the SPTrustedIdentityTokenIssuer object:

    $idp.Update()

Configuration Steps for DirX Access

DirX Access supports the creation of the necessary Metadata object with the template “WS-Federation RP metadata”. This template accepts the following parameters:

Assign this Metadata object to the peer metadata IDs of the DirX Access WS-Federation endpoint.