Set Up Links at the IdP or SP to Initiate Single Sign-on

Federation Security Services Guide › Configure SiteMinder as a SAML 2.0 Identity Provider › Set Up Links at the IdP or SP to Initiate Single Sign-on

Set Up Links at the IdP or SP to Initiate Single Sign-on

To initiate single sign-on, the user can begin at the Identity Provider or the Service Provider. You need to configure the appropriate links at each site to trigger single sign-on operation.

Identity Provider-initiated SSO (POST or artifact binding)

If a user visits the Identity Provider before going to the Service Provider, the Identity Provider must generate an unsolicited response. To initiate an unsolicited response, create a hard-coded link that generates an HTTP Get request that includes a query parameter with the Service Provider ID. The Identity Provider generates an assertion response for this ID. The Federation Web Service application and the Assertion Generator must accept the GET request.

A user clicks the link you establish to initiate the unsolicited response.

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

idp_server:port: Identifies the web server and port hosting the Web Agent Option Pack or SPS federation gateway.
SP_ID: Service Provider ID value.
URI_for_binding: Identifies the URI of the POST or Artifact binding for the ProtocolBinding element. The SAML 2.0 specification defines this URI.

Also specify the binding in the SAML Service Provider properties for the unsolicited response to work.

Note the following information:

If there is no ProtocolBinding parameter in the link and only one binding in the Service Provider properties, the Service Provider uses the one binding.
If the artifact and POST bindings are enabled in the Service Provider properties, POST is the default. Therefore, if you want to only use artifact binding, include the ProtocolBinding query parameter in the link.

Important! If you configure indexed endpoints for the Assertion Consumer Services, the ProtocolBinding query parameter overrides the binding for the Assertion Consumer Service.

More information:

Unsolicited Response Query Parameters Used by a SiteMinder IdP

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

SPID
ProtocolBinding
RelayState

SPID

(Required) Specifies the ID of the Service Provider where the Identity Provider sends the unsolicited response.

ProtocolBinding

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

Required Use of the ProtocolBinding Query Parameter

Using the ProtocolBinding parameter is required only if the artifact and POST bindings are enabled in the Service Provider properties. If both profiles are enabled, use the query parameter only to use artifact binding.

The URI for the artifact binding from the SAML 2.0 specification is:
urn:oasis:names:tc:SAML:2.0:bindings:HTTP-Artifact
The URI for the POST binding from the SAML 2.0 specification is:
urn:oasis:names:tc:SAML:2.0:bindings:HTTP-POST

You do not need to set this parameter for HTTP-POST single sign-on.

Note: Do not HTTP-encode the query parameters.

Example: Unsolicited Response with ProtocolBinding

This link redirects the user to the Single Sign-on service. In this link is the Service Provider identity. The SPID query parameter indicates the identity. Additionally, the bindings query parameter indicates that the artifact binding is in use. After the user clicks this hard-coded link, they are redirected to the 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

Optional Use of the ProtocolBinding Query Parameter

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

If the ProtocolBinding is not specified in the unsolicited response, the profile for the Service Provider is used.
Both profiles can be enabled for the Service Provider. If the ProtocolBinding is not in the unsolicited response, the Service Provider uses the POST profile by default.
Example: Unsolicited Response without ProtocolBinding

This link redirects the user to the Single Sign-on service. Included in this link is the Service Provider identity. The SPID query parameter indicates the identity. No ProtocolBinding query parameter exists. After the user clicks this hard-coded link, they are redirected to the local Single Sign-on service.
```
http://fedsrv.fedsite.com:82/affwebservices/public/saml2sso?SPID=
http%3A%2F%2Ffedsrv.acme.com%2Fsmidp2for90
```

RelayState

Specifies the target at the Service Provider. Use the RelayState query parameter to indicate the target destination; however, this method is optional. There can be a configuration mechanism at the Service Provider to indicate the target.

URL-encode the RelayState value.

Example

http://ca.sp.com:90/affwebservices/public/saml2authnrequest?ProviderID=
http%3A%2F%2Ffedsrv.acme.com%2Fsmidp2for90&
RelayState=http%3A%2F%2Fwww.spdemo.com%2Fapps%2Fapp.jsp

Service Provider-initiated SSO (POST or artifact binding)

A user can visit the Service Provider first and then go to an Identity Provider. Therefore, create an HTML page at the Service Provider containing hard-coded links to its AuthnRequest service. The links in the HTML page redirect the user to the Identity Provider for authentication. The links also indicate what is in the AuthnRequest.

The hard-coded link that the user selects must contain specific query parameters. These parameters are part of the HTTP GET request to the AuthnRequest service at the Service Provider.

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/affwebservices/public/saml2authnrequest?ProviderID=IdP_ID&
ProtocolBinding=URI_of_binding

sp_server:port

Specifies the server and port number at the Service Provider hosting the Web Agent Option Pack or the SPS federation gateway.

IdP_ID

Specifies the identity that is assigned to the Identity Provider.

URI_for_binding

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

For the request to work, enable a binding for the SAML authentication scheme.

Note the following information:

If you do not include the ProtocolBinding query parameter in the AuthnRequest, the default binding is the one defined for the authentication scheme. If you have both bindings defined in the authentication scheme, then no binding is passed in the AuthnRequest. As a result, the default binding at the Identity Provider is used.
Artifact and POST can be enabled for the SAML authentication scheme. Include the ProtocolBinding query parameter in the link if you only want to use artifact binding.

AuthnRequest Query Parameters Used by a SiteMinder SP

A SiteMinder Service Provider can use query parameters in the links to the AuthnRequest Service. The allowable query parameters are:

ProviderID (required)

ID of the Identity Provider where the AuthnRequest Service sends the AuthnRequest message.

ProtocolBinding

Specifies the ProtocolBinding element in the AuthnRequest message. This element specifies the protocol that the Identity Provider uses to return the SAML response. 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.

Required Use of the ProtocolBinding Query Parameter

The artifact and POST binding can be enabled for an authentication scheme. If you want to use only the artifact binding, the ProtocolBinding parameter is required.

The URI for the artifact binding from the SAML 2.0 specification is:
urn:oasis:names:tc:SAML:2.0:bindings:HTTP-Artifact
The URI for the POST binding as from the SAML 2.0 specification is:
urn:oasis:names:tc:SAML:2.0:bindings:HTTP-POST

You do not need to set this parameter for HTTP-POST single sign-on.

Example: AuthnRequest Link with ProtocolBinding
```
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 
```
A user clicks the link at the Service Provider. The Federation Web Services application requests an AuthnRequest message from the local Policy Server.

Optional Use of ProtocolBinding

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

If only one binding is enabled for the authentication scheme and the ProtocolBinding query parameter is not specified, the authentication scheme uses the enabled binding.
If both bindings are enabled and the ProtocolBinding query parameter is not specified, POST binding is used as the default.

Note: Do not HTTP-encode the query parameters.

Example: AuthnRequest Link without ProtocolBinding

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

A user clicks the link at the Service Provider. The Federation Web Services application requests for an AuthnRequest message from the local Policy Server.

ForceAuthn

Indicates whether the SP forces the Identity Provider to authenticate a user even if there is an existing security context for that user.

If ForceAuthn=True in the AuthnRequest message, and a SiteMinder session exists for a particular user, the IdP rechallenges the user for credentials. If the user successfully authenticates, the IdP includes the identity information from the existing session in the assertion. The IdP discards the session that it generated for reauthentication.
Note: A user can try to reauthenticate with different credentials than the existing session. The IdP then compares the userDN and the user directory OID for the current and existing sessions. If the sessions are not for the same user, the IdP returns a SAML 2.0 response. The response indicates that the authentication has failed.
If the SP sets ForceAuthn=True in the AuthnRequest message and there is no SiteMinder session, the SiteMinder IdP challenges the user for credentials. If the user successfully authenticates, a session is established.

Example

http://www.sp.demo:81/affwebservices/public/saml2authnrequest?ProviderID=idp.demo&ForceAuthn=yes

RelayState

Specifies the target at the Service Provider. You can use the RelayState query parameter to indicate the target destination, but this method is optional. Instead, you can specify the target configured in the SAML 2.0 authentication scheme. The authentication scheme also has an option to override the target with the RelayState query parameter.

URL-encode the RelayState value.

Example

http://www.spdemo.com:81/affwebservices/public/saml2authnrequest?
ProviderID=idp.demo&RelayState=http%3A%2F%2Fwww.spdemo.com%2Fapps%2Fapp.jsp

IsPassive

Determines whether the Identity Provider can interact with a user. If this query parameter is set to true, the Identity Provider must not interact with the user. Additionally, the IsPassive parameter is included with the AuthnRequest sent to the Identity Provider. If this query parameter is set to false, the Identity Provider can interact with the user.

Example

http://www.spdemo.com:81/affwebservices/public/saml2authnrequest?
ProviderID=idp.demo&RelayState=http%3A%2F%2Fwww.spdemo.com%
2Fapps%2Fapp.jsp&IsPassive=true

AssertionConsumerServiceIndex

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

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

Query Parameter Processing by a SiteMinder IdP

If a Service Provider initiates single sign-on, that Service Provider can include a ForceAuthn or IsPassive query parameter in the AuthnRequest message. When a Service Provider includes these two query parameters in the AuthnRequest message, a <stnmdr> Identity Provider handles these query parameters as follows:

ForceAuthn Handling

When a Service Provider includes ForceAuthn=True in the AuthnRequest, a SiteMinder Identity Provider takes the following actions:

ForceAuthn=True in the AuthnRequest message, and a SiteMinder session exists for a particular user. The SiteMinder IdP rechallenges the user for credentials. If the user successfully authenticates, the IdP sends the identity information from the existing session in the assertion. the IdP discards the session that it generated for the reauthentication.
A user can try to reauthenticate with different credentials than the original session. The SiteMinder IdP compares the userDN and the user directory OID for the current and existing sessions. If the sessions are not for the same user, it returns a SAML 2.0 response. The response indicates that the authentication has failed.
ForceAuthn=True in the AuthnRequest message and there is no SiteMinder session. The SiteMinder IdP challenges the user for credentials. If the user successfully authenticates, a session is established.

IsPassive Handling

When a Service Provider includes IsPassive in the AuthnRequest and the IdP cannot honor it, one of the following SAML responses is sent back to the Service Provider:

IsPassive=True in the AuthnRequest message and there is no SiteMinder session. The SiteMinder Identity Provider returns a SAML response. This response includes an error message because SiteMinder requires a session.
IsPassive=True in the AuthnRequest message and there is a SiteMinder session. The SiteMinder Identity Provider returns the assertion.
IsPassive and ForceAuthn are in the AuthnRequest message and both are set to True. The SiteMinder Identity Provider returns an error because the request is invalid. IsPassive and ForceAuthn are mutually exclusive.