Previous Topic: Mapping Assertion Attributes to Application Attributes (SAML only)Next Topic: Authentication Context Processing

Federation Guides › Partnership Federation Guide › Partnership Creation and Activation › Sign and Encrypt Federation Messages › User Provisioning at the Relying Party

User Provisioning at the Relying Party

In a federated network, the relying party can establish accounts for users federating from different asserting parties. Dynamic provisioning supports the process of creating client accounts with the necessary account rights and access privileges for accessing data and applications.

Remote Provisioning

Remote provisioning employs a third-party provisioning application to create a user account. The application then passes the necessary information back to the Policy Server at the federation system with Federation Manager. The Policy Server uses the data to create a user credential.

Remote provisioning occurs at the relying party. The following figure shows a remote provisioning setup.

Provisioning set up at the relying party

The high-level provisioning process is as follows:

  1. The Policy Server at the relying party receives a request for a resource along with an assertion. However, the user cannot be found in the user directory.
  2. With provisioning enabled, the Policy Server processes an active response containing assertion data and generates a cookie with the assertion data. Additionally, a cookie that keeps state is generated to indicate a provisioning request is in place.
  3. The browser is redirected with an open-format cookie or headers to a provisioning application.
  4. The provisioning application typically prompts the user to log in. After the user logs in, the application reads the cookie or the headers. The application uses the assertion data and the login credentials to establish a user account.

    The provisioning application can consume the open-format cookie using the Federation Manager Java or .NET SDK.

  5. The browser redirects the user back to the assertion consumer service at the relying party after an account has been provisioned. A cookie that maintains state information about provisioning is examined to verify that the user has been provisioned. A credential is created and passed to the authentication scheme.

    Note: The provisioning application must know the URI of the assertion consumer service at the relying party. For example, the SAML 2.0 URI for SiteMinder as the relying party is https://sp_server:port/affwebservices/public/saml2assertionconsumer.

  6. The Policy Server attempts user disambiguation a second time. Assuming that provisioning is successful, the user is authenticated and cookies or headers are sent to the target application.

    The redirect mode that you select for the target application determines the data delivery method to the target application.

  7. The user is redirected to the target resource.
Delivery of Assertion Data to the Provisioning Application

To accomplish remote provisioning, SiteMinder redirects the browser with the assertion data to the provisioning application.

SiteMinder can pass the assertion data using one of these methods:

Open format cookie

Delivers SAML assertion information in an open-format cookie. The cookie contains a login ID based on the assertion data.

Note: If you use the open-format cookie, the SiteMinder system and the remote provisioning system must be in the same domain.

The cookie can be created in one of two ways:

HTTP Headers

SiteMinder can also pass assertion information as HTTP headers. If you use HTTP headers, the SiteMinder system and the remote provisioning system can be in different domains.

Learn more about using HTTP headers to pass assertion data and how to protect the headers.

The delivery option is configurable in the Application Integration step of the partnership wizard.

After the user is redirected to the provisioning application, SiteMinder no longer has control over the process. If provisioning a user account is a time-consuming process, the provisioning application is responsible for handling this situation. For example, by the application can send a message to the user explaining that provisioning is in process. This information lets the user know not to keep trying to log in before a user account is available.

Remote Provisioning Configuration

To configure remote provisioning, determine a delivery option for the assertion data and supply the URL of the provisioning server.

In addition to configuring remote provisioning, you can select the Allow IdP to create User Identifier option. This option enables the IdP to create a persistent identifier if no identifier for the user exists. This Allow/Create feature is not exclusively for provisioning using local account linking, though it is required for the local method.

When you want the IdP to generate a user identifier that is sent with other attributes, you can enable the Allow/Create feature together with remote provisioning. The application at the remote provisioning server determines how it uses the generated identifier. The application can perform local account linking, but not SiteMinder local account linking.

To configure remote provisioning

  1. Begin at the Application Integration step of the partnership wizard.
  2. Select the provisioning type in the User Provisioning section.
  3. If you select Remote as the provisioning type, complete the additional fields that are displayed.

    Click Help for a description of the fields.

  4. Select the Confirm step and click Finish to save your changes.

You have completed remote provisioning configuration.

Failed Authentication Handling Using Redirect URLs (Relying Party)

Assertion-based authentication can fail at the site that consumes assertions. If authentication does fail, you can configure the Policy Server to redirect the user to different applications (URLs) for further processing. For example, when user disambiguation fails, you can configure SiteMinder to send the user to a provisioning system. Setting up redirect URLs is optional and is only configurable at the relying party.

Follow these steps:

  1. Begin at the Application Integration step of the partnership wizard.

    In the Status Redirect URL section of the dialog, specify redirects only for the specific failure conditions that you want. For SAML 2.0, you can also configure redirects for specific HTTP error conditions.

    Click Help for a description of the fields.

  2. For each redirect option you configure, specify the method by which SiteMinder redirects the user. The options are:
    302 No Data (default)

    Redirects the user with an HTTP 302 redirect and no data.

    HTTP Post

    Redirects the user with the HTTP Post protocol.

Configuration of the redirect URLs is complete.

Partnership Confirmation

Review the partnership configuration before saving it.

Follow these steps:

  1. Review the settings in the Confirm step of the Partnership wizard.
  2. Click Modify in each group box to change any settings.
  3. Click Finish when you are satisfied with the configuration.

The partnership configuration is complete.

Partnership Activation

After you configure all the required settings for a partnership, activate it to use it. You can also deactivate a partnership using the same process.

Follow these steps:

  1. Select Federation, Partnership Federation, Partnerships.

    The Partnerships dialog opens.

  2. From the Actions menu, select Activate or Deactivate next to the partnership of interest.

    A confirm dialog displays.

    Note: Activate is only available for a partnership in DEFINED or INACTIVE status. Deactivate is only available for a partnership in ACTIVE status.

  3. Click Yes to confirm your selection.

    The status of the partnership is set and the display is refreshed.

Important! Deactivate a partnership before you modify it.

Exporting a Partnership

You can use metadata as a basis for creating remote entities and forming a partnership. Metadata makes partnership configuration more efficient because many aspects of an entity are already defined in the metadata file. The file can then be imported to create partnership or remote entity.

You do not have to complete a partnership before exporting it. You can configure a portion of the partnership and then export it.

In the Administrative UI, you can export metadata from an existing partnership entry.

Note: In the Administrative UI, you can export metadata from an existing local asserting or relying entity. When you export SAML 1.1 data, the terms used in the resulting metadata file are SAML 2.0 terms. This convention is part of the SAML specification. When you import the SAML 1.1 data, the terms are imported correctly using SAML 1.1 terminology.

When exporting from the partnership, the selected partnership is used as the basis of the export. You are not allowed to define a new partnership name. SiteMinder uses the name from the selected partnership.

Follow these steps:

  1. Select Federation, Partnership Federation, Partnerships.

    The Partnership dialog displays.

  2. Click the Action pull-down menu next to the appropriate entry in the list and select Export Metadata.

    The Export Metadata dialog opens.

  3. Complete the fields on the dialog.

    If you are exporting a partnership in ACTIVE status, most of the fields are read-only. Only the Validity Duration field and the alias drop-down list are modifiable.

  4. Click Export to finish.
  5. A dialog prompting you to open or save the metadata file displays. You can open it to view it.
  6. Save the data to an XML file on your local system.

The metadata is exported to the specified XML file.

Links to Servlets which Initiate Single Sign-on

When designing a site for federated content, that site includes a page with specific links to trigger single sign-on. These links are URLs to servlets for the Single Sign-on service or the AuthnRequest Service.

To initiate single sign-on, the user can begin at the asserting or relying party. Configure the appropriate links at each site to initiate single sign-on operation.

Producer-initiated SSO (SAML 1.1)

At the producer, create pages that contain links that direct the user to the consumer site. Each link represents an intersite transfer URL. The user has to visit the intersite transfer URL. The URL makes a request to the producer-side web Agent before the user is redirected to the consumer site.

For SAML Artifact and POST profile, the syntax for the intersite transfer URL is:

http://producer_host:port/affwebservices/public/intersitetransfer?
CONSUMERID=consumer_entity_ID&TARGET=http://consumer_site/target_url

The variables and query parameters in the previous intersite transfer URL are as follows:

producer_host:port

Specifies the server and port number where the user is authenticated.

CONSUMERID

(Required) Identifies the consumer. On the producer side, the producer-to-consumer partnership has a name, and the remote consumer entity has an ID. The CONSUMERID is the entity ID of the remote consumer. The entity ID is case-sensitive. Enter it exactly as it appears in the Administrative UI.

You can use the parameter NAME in place of CONSUMERID, but not both.

If you use NAME, specify the name of the producer-to-consumer partnership as defined at the producer.

consumer_entity_ID

Identifies the consumer site the user wants to visit from the producer site. The entity ID is case-sensitive. Enter it exactly as it appears in the Administrative UI.

TARGET

(Optional) Identifies the requested target resource at the consumer.

The TARGET parameter is optional. You are required to define the target; however, you can define it in the consumer-side partnership instead of the intersite transfer URL. The target is defined in the Application Integration step of the Partnership wizard. Be sure to define the target in the URL or in the partnership.

consumer_site

Specifies the server at the consumer site.

target_url

Indicates the target application at the consumer site.

Note: Query parameters for the SAML Artifact binding must use HTTP-encoding.

Example of an intersite transfer URL for the Artifact and POST profile:

http://www.smartway.com/affwebservices/public/intersitetransfer?
CONSUMERID=ahealthco&TARGET=http://www.ahealthco.com:85/
smartway/index.jsp
IdP-initiated SSO (SAML 2.0 Artifact or POST)

If a user visits a SiteMinder Identity Provider before going to the Service Provider, an unsolicited response at the Identity Provider must be initiated. To initiate an unsolicited response, create a hard-coded link that generates an HTTP Get request that SiteMinder accepts. This HTTP Get request must contain a query parameter that provides the Service Provider ID. The Identity Provider must generate the SAML assertion response. A user clicks this link to initiate the unsolicited response.

Note: This information applies to Artifact or POST bindings.

To specify the use of artifact or POST profile in the unsolicited response, the syntax for the unsolicited response link is:

http://idp_server:port/affwebservices/public/saml2sso?SPID=SP_ID&
ProtocolBinding=URI_for_binding&RelayState=target_URL

idp_server:port

Identifies the web server and port hosting SiteMinder.

SP_ID

Specifies the Entity ID of the Service Provider defined in the partnership. The entity ID is case-sensitive. Enter it exactly as it appears in the Administrative UI.

URI_for_binding

Identifies the URI of the POST or Artifact binding for the ProtocolBinding element. The SAML 2.0 specification defines this URI.

Note: A binding must also be enabled for the partnership for the request to work.

target_URL

Specifies the URL of the federation resource target at the Service Provider.

Note the following:

Important! If you configure indexed endpoint support for Assertion Consumer Services, the value of the ProtocolBinding query parameter overrides the binding for the Assertion Consumer Service.

Unsolicited Response Query Parameters Used by the IdP

An unsolicited response that initiates single sign-on from the IdP can include the following query parameters:

SPID

(Required) Specifies the ID of the Service Provider where the Identity Provider sends the unsolicited response. The entity ID is case-sensitive. Enter it exactly as it appears in the Administrative UI.

ProtocolBinding

Specifies the ProtocolBinding element in the unsolicited response. This element specifies the protocol for sending the assertion response to the Service Provider. If the Service Provider is not configured to support the specified protocol binding, the request fails.

RelayState

Indicates the URL of the target resource at the Service Provider. By including this query parameter, it tells the IdP to redirect the user the appropriate resource at the Service Provider. This query parameter can be used in place of specifying a target URL when configuring single sign-on.

Required Use of the ProtocolBinding Query Parameter

The ProtocolBinding query parameter is required only if the artifact and POST binding are enabled for the Service Provider properties. In addiiton, the user wants to only use artifact binding.

Note: HTTP coding the query parameters is not necessary.

Optional Use of the ProtocolBinding Query Parameter

When you do not use the ProtocolBinding query parameter, the following information applies:

Example: Unsolicited Response without ProtocolBinding

The link redirects the user to the Single Sign-on service. Included in this link is the Service Provider identity, which the SPID query parameter specifies. The ProtocolBinding query parameter is not present. After the user clicks this hard-coded link, they are redirected to the Single Sign-on service.

http://fedsrv.fedsite.com:82/affwebservices/public/saml2sso?
SPID=http%3A%2F%2Ffedsrv.acme.com%2Fsmidp2for90

Example: Unsolicited Response with ProtocolBinding

The link redirects the user to the Single Sign-on service. Included in this link is the Service Provider identity, which the SPID query parameter specifies and the artifact binding is being used. After the user clicks this hard-coded link, they are redirected to local Single Sign-on service.

http://idp-ca:82/affwebservices/public/saml2sso?SPID=
http%3A%2F%2Ffedsrv.acme.com%2Fsmidp2for90&
ProtocolBinding=urn:oasis:names:tc:SAML:2.0:bindings:HTTP-Artifact

ForceAuthn and IsPassive Processing at the IdP

If Service Provider initiates single sign-on, the Service Provider can include a ForceAuthn or IsPassive query parameter in an AuthnRequest message.

When a Service Provider includes ForceAuthn or IsPassive in the AuthnRequest, a SiteMinder Identity Provider handles these query parameters as follows:

ForceAuthn Handling

When a Service Provider includes ForceAuthn=True in the AuthnRequest message, a SiteMinder Identity Provider challenges the user for their credentials. The challenge even when a SiteMinder session exists.

IsPassive Handling

A SiteMinder IdP does not support passive authentication. When a Service Provider includes IsPassive in the AuthnRequest and the Identity Provider cannot honor it, the IdP sends back one of these SAML responses:

SP-initiated SSO (SAML 2.0)

SP-initiated SSO requires that you have an HTML page at the Service Provider containing hard-coded links to the AuthnRequest service at the Service Provider. The links redirect the user to the Identity Provider to be authenticated and determining what is included in the AuthnRequest itself.

This information applies to Artifact or POST bindings.

The hard-coded link that the user selects must contain specific query parameters, which are used in an HTTP GET request to the AuthnRequest service.

Note: The page with these hard-coded links has to reside in an unprotected realm.

To specify the use of artifact or profile binding for the transaction, the syntax for the link is:

http://sp_server:port/affwebservices/public/saml2authnrequest?
ProviderID=IdP_ID&ProtocolBinding=URI_of_binding&
RelayState=target_URL

sp_server:port

Specifies the server and port number at the Service Provider that is hosting Federation Manager.

IdP_ID

Specifies the identity that is assigned to the Identity Provider. The entity ID is case-sensitive. Enter it exactly as it appears in the Administrative UI.

URI_of_binding

Identifies the URI of the POST or Artifact binding for the ProtocolBinding element. The SAML 2.0 specification defines this URI.

Also, enable a binding for the partnership for the request to work.

target_URL

Specifies the URL of the federation target at the Service Provider.

Note the following information:

AuthnRequest Query Parameters Used by an SP

The query parameters a SiteMinder SP can use in the links to the AuthnRequest Service are as follows:

ProviderID (required)

Entity ID of the Identity Provider where the AuthnRequest Service sends the AuthnRequest message. The entity ID is case-sensitive. Enter it exactly as it appears in the Administrative UI.

ProtocolBinding

Specifies the ProtocolBinding element in the AuthnRequest message. This element specifies the protocol for returning the SAML response from the Identity Provider. If the specified Identity Provider is not configured to support the specified protocol binding, the request fails.

If you use this parameter in the AuthnRequest, you cannot include the AssertionConsumerServiceIndex parameter also. They are mutually exclusive.

ForceAuthn

Instructs the Identity Provider that it must authenticate a user directly instead of relying on an existing security context. Use this query parameter when the Identity Provider is using Federation Manager, not if it is using third-party federation software.

Example

http://sp1.demo.com:81/affwebservices/public/saml2authnrequest?
ProviderID=idp1.example.com&ForceAuthn=yes

IsPassive

Instructs the Identity Provider to log in the user without challenging the user for credentials or interacting with the user in any way. A SiteMinder Identity Provider does not honor this query parameter unless the user has a session. If the user does not have a session, the Identity Provider returns an error.

AssertionConsumerServiceIndex

Specifies the index of the endpoint acting as the Assertion Consumer Service. The index tells the Identity Provider where to send the assertion response.

If you use this parameter in the AuthnRequest, do not include the ProtocolBinding parameter also. This parameter and the ProtocolBinding parameter are mutually exclusive. The Assertion Consumer Service has its own protocol binding, which could conflict with the ProtocolBinding parameter.

RelayState

Indicates the URL of the target resource at the Service Provider. By including this query parameter, it tells the Service Provider where to send the user. Otherwise, the default target for the partnership is used.

Required Use of the ProtocolBinding Query Parameter

The ProtocolBinding parameter is required if the artifact and POST bindings are enabled for the partnership, and the user wants to use only the artifact binding.

Optional Use of ProtocolBinding

If you do not use the ProtocolBinding query parameter the following conditions apply:

Note: You do not need to HTTP-encode the query parameters.

Example: AuthnRequest Link without the ProtocolBinding Query Parameter

This sample link goes to the AuthnRequest service. The link specifies the Identity Provider in the ProviderID query parameter.

http://ca.sp.com:90/affwebservices/public/saml2authnrequest?
ProviderID=http%3A%2F%2Ffedsrv.acme.com%2Fsmidp2for90

After a user clicks the link at the Service Provider, SiteMinder passes a request for an AuthnRequest message.

Example: AuthnRequest Link with the ProtocolBinding Query Parameter

http://ca.sp.com:90/affwebservices/public/saml2authnrequest?
ProviderID=http%3A%2F%2Ffedsrv.acme.com%2Fsmidp2for90&
ProtocolBinding=urn:oasis:names:tc:SAML:2.0:bindings:HTTP-Artifact

After a user clicks the link at the Service Provider, SiteMinder passes a request for an AuthnRequest message.