org.jboss.seam.security.external.saml.api
Interface SamlIdentityProviderApi

All Known Implementing Classes:

SamlIdpSingleUser

public interface SamlIdentityProviderApi

API to the SAML Identity Provider (IDP) of Seam security. In order to use this API, one of the following alternative beans needs to be activated:

• SamlIdpInApplicationScopeProducer
• SamlIdpInVirtualApplicationScopeProducer

The former will install the Identity Provider in application scope, the latter will install it in virtual application scope. The virtual application scope allows for using different provider configurations depending on the server name. See VirtualApplicationScoped.

This API (implemented by the framework) comes along with an SPI: SamlIdentityProviderSpi (implemented by the client application). Dialogues are used to bridge corresponding API and SPI calls (see Dialogued).

Most methods in this API require that the HTTP response is passed as a parameter. The implementation needs the response, in order to redirect the browser to the relying party. Beware not to touch the HTTP response after one of these method returns.

Author:

Marcel Kolsteren

Method Summary

void	authenticationFailed(HttpServletResponse response) This is one of the possible responses that relate to the SPI call SamlIdentityProviderSpi.authenticate(org.jboss.seam.security.external.api.ResponseHolder).
void	authenticationSucceeded(HttpServletResponse response) This is one of the possible responses that relate to the SPI call SamlIdentityProviderSpi.authenticate(org.jboss.seam.security.external.api.ResponseHolder).
SamlNameId	createNameId(String value, String format, String qualifier) Creates a name identifier with the given properties.
SamlIdpSession	getSession() Gets the current SAML session.
void	globalLogout(HttpServletResponse response) Globally logs out the current user.
void	localLogin(SamlNameId nameId, List<AttributeType> attributes) Creates a local SAML session for the user with the given name and attributes.
void	localLogout() Removes the local SAML session for the current user.
void	remoteLogin(String spEntityId, String remoteUrl, HttpServletResponse response) Logs the user in remotely in the application of the given service provider.

Method Detail

localLogin

void localLogin(SamlNameId nameId,
                List<AttributeType> attributes)

Creates a local SAML session for the user with the given name and attributes. This call is typically done before a remoteLogin(java.lang.String, java.lang.String, javax.servlet.http.HttpServletResponse) or an authenticationSucceeded(javax.servlet.http.HttpServletResponse) call.

Parameters:

nameId -

attributes -

createNameId

SamlNameId createNameId(String value,
                        String format,
                        String qualifier)

Creates a name identifier with the given properties. Needed for constructing the nameId parameter of a localLogin(org.jboss.seam.security.external.saml.api.SamlNameId, java.util.List) call.

Parameters:

value - value (required)

format - format (optional)

qualifier - qualifier (optional)

Returns:

the name identifier

remoteLogin

void remoteLogin(String spEntityId,
                 String remoteUrl,
                 HttpServletResponse response)

Logs the user in remotely in the application of the given service provider. If the remote URL is specified, the service provider will redirect the user to that URL within the service provider's application. Otherwise, the service provider will determine for itself which page is shown to the user.

In SAML terms, this call results in an "unsolicited login" at the side of the service provider.

Parameters:

spEntityId - the entity id of the remote service provider

remoteUrl - the URL where the user agent needs to be redirected to by the service provider (can be null)

response - the HTTP servlet response

authenticationSucceeded

void authenticationSucceeded(HttpServletResponse response)

This is one of the possible responses that relate to the SPI call SamlIdentityProviderSpi.authenticate(org.jboss.seam.security.external.api.ResponseHolder). If should be called in the same dialogue context as the corresponding SPI call. It instructs the SAML identity provider to send a positive authentication result back to the service provider, using the local SAML session, which must have been established before this call is done (by a previous call to localLogin(org.jboss.seam.security.external.saml.api.SamlNameId, java.util.List)).

Parameters:

response - the HTTP servlet response

authenticationFailed

void authenticationFailed(HttpServletResponse response)

This is one of the possible responses that relate to the SPI call SamlIdentityProviderSpi.authenticate(org.jboss.seam.security.external.api.ResponseHolder). If should be called in the same dialogue context as the corresponding SPI call. It instructs the SAML identity provider to send a positive authentication result back to the service provider.

Parameters:

response - the HTTP servlet response

getSession

SamlIdpSession getSession()

Gets the current SAML session. This contains information about the logged in user, and the external service providers that take part in this session.

Returns:

the session

localLogout

void localLogout()

Removes the local SAML session for the current user. This use case is considered out of scope by the SAML spec (see the SAMLv2 Profiles document, section 4.4). External service providers that take part in the session are not informed about the fact that the shared session has been removed at the identity provider side.

globalLogout

void globalLogout(HttpServletResponse response)

Globally logs out the current user. This leads to a "single logout" where the identity provider logs out the user from all service providers that participate in the current session. The result of the global logout is reported asynchronously through the SPI.

Parameters:

response - the HTTP servlet response