IBM Tivoli Federated Identity Manager, Version 6.2.2.7

Supported macros for customizing an authentication login form

This topic describes the set of macros for customizing an authentication login form.

Tivoli® Federated Identity Manager supplies contextual authentication parameters in customizing login forms. When using WebSEAL as the point of contact server, these are query-string parameters to the login page. For WebSphere®, they are in the WASReqURL cookie when the login page is loaded. The parameters are macros in the configuration of the authentication callback for the point of contact server profile.

Note: When you use the WebSphere point of contact, the value of the query string parameter needs to be URL decoded twice.

Supported macros are:

Protocol independent macros
SAML protocol macros
OpenID protocol macros
OAuth protocol macros

Note: If the value of authentication.macros is longer than the permitted length of query string parameter, the WASReqURL cookie will not be present in the identity provider.

Protocol independent macros for customizing an authentication login form

The following macros are protocol independent and can be used regardless of the federation type used.

Table 1. Supported Protocol independent macros
Macro	Query-String Parameter name	Description
%FEDID%	FedId	Specifies a unique identifier (UUID) used internally by Tivoli Federated Identity Manager to identify the federation.
%FEDNAME%	FedName	Specifies the user-assigned name of the federation.

SAML protocol supported macros for customizing an authentication login form

The following macros are supported for SAML protocol. Macros are supported for both SAML 1.x and SAML 2.0, except as indicated.

Table 2. Supported SAML protocol macros
Macro	Query-String Parameter name	Description and value
%PARTNERID%	PartnerId	Represents the SSO partner that the user uses to sign in. SAML value: The value is the ProviderID of the partner.
%TARGET%	Target	Represents the target URL at the partner, if known. SAML value: The value is the value of the target parameter.
%SPRELAYSTATE%	SPRelayState	Supported for SAML 2.0 only. Represents RelayState data in accompanying the SSO request, if applicable. SAML value: The RelayState data that accompanies the SAML AuthnRequest.
%ACSURL%	AssertionConsumerURL	Represents the assertion consumer service URL of the partner, if applicable. SAML value: The value is the Partner ACS URL.
%AUTHNCONTEXT%	AuthnContext	Supported for SAML 2.0 only Represents the AuthnContext in request (if applicable). SAML value: The value is a base-64 encoded string representing the XML from the RequestedAuthnContext in the SAML AuthnRequest (if present).
%SSOREQUEST%	SSORequest	Supported for SAML 2.0 only Represents the entire SSO request (if applicable). SAML value: The value is a base-64 encoded string representing the XML from the entire SAML AuthnRequest.
%FORCEAUTHN%	ForceAuthn	Supported for SAML 2.0 only The value `true` or `false`. SAML value: If the ForceAuthn flag is set in the SAML 2 SSO request causing the user to re-authenticate, the value is `true`. Otherwise the value is `false`.

OpenID supported macros for customizing an authentication login form

The following macros are supported for the OpenID protocol.

Table 3. Supported OpenID protocol macros
Macro	Query-String Parameter name	Description and value
%PARTNERID%	PartnerId	Represents the SSO partner that the user uses to sign in. OpenID value: The value of the openid.trustroot parameter.
%TARGET%	Target	Represents the target URL at the partner, if known. OpenID value: The value of the openid.return_to parameter.
%SSOREQUEST%	SSORequest	Represents the entire SSO request (if applicable). OpenID value: The checkid_setup request as a base64-encoded version of the url-encoded SSO request.
%UNSATISFIEDPAPEPOLICIES%	UnsatisfiedPapePolicies	Represents a list of strings which represent PAPE policies. These strings are returned as "not yet satisfied" by the identity provider mapping rule in an OpenID identity provider federation. OpenID value: PAPE policies returned in the ContextAttributes Attribute openid.pape.to_be_satisfied_auth_policies
%FORCEAUTHN%	ForceAuthn	Specifies if authentication on the identity provider is forced. The values are `true` or `false`. OpenID value: The value is `true` if one of these criteria is satisfied: the PAPE max_auth_age was zero (meaning forced to authenticate again) the IDP mapping rule on the OpenID identity provider is forcing authentication due to unsatisfied PAPE policies the authentication time returned by the IDP mapping rule does not satisfy the (non-zero) max_auth_age requested by the RP Otherwise, the value is `false`.

OAuth protocol supported macros for customizing an authentication login form

The following table indicates how an OAuth federation populates the authentication macros.

Table 4. Supported OAuth protocol macros
Macro	Query-String Parameter name	Description and value
%PARTNERID%	PartnerId	The OAuth unique client identifier.
%TARGET%	Target	OAuth client redirection URI.
%SSOREQUEST%	SSORequest	A base-64 encoded string representing the query and body parameters from the OAuth request.

Feedback