SAP integration plug-ins

Introduction and overview

SAP's products use SAP SSO logon tickets for integration into an SSO space. nevisAuth is capable of issuing, verifying and consuming such tickets, so that SAP products can be integrated seamlessly into a Nevis setup. SAP SSO logon tickets are built in the following way:

• A preamble defines the version of the ticket (currently always "2") and the SAP code page number in which the ticket is encoded (see the property encoding in the.
• A sequence of InfoUnits, values with numeric key identifiers. The properties of the AuthStateare transformed into such InfoUnits.
• A final InfoUnit containing a PKCS7 signature that signs the previous content of the ticket.
• The resulting byte string is encoded in Base64. Then, a translation of some Base64 characters is performed

Some SAP applications (in particular those running as native processes) do not support all possible character encodings. In such cases, error messages may be misleading. Usage of the encoding ISO8859-1 (ISO-LATIN-1) is encouraged as this seems to be supported by all SAP products.SAPTicketIssuer

The SAPTicketIssuer AuthState may be used to issue an SAP SSO logon ticket for consumption by SAP products and compatible applications. The issued ticket may either be propagated to the client as a cookie (for pseudo-federated scenarios based on shared cookie domain spaces) or propagated to a backend application behind a nevisProxy instance using a DelegationFilter with CookieDelegation.

Description

The following table describes the characteristics of the AuthState.

Topic	Description
Class	ch.nevis.esauth.auth.states.sap.SAPTicketIssuer
Logging	SAP
Auditing	none
Marker	none
Properties	userIdSource (string, "${request:userId}")Source of the user ID to set for the issued SAP ticket.
	applicationMappings (string, "${request
	ttl (time in seconds, 8h)Time-to-live for issued ticket. Note that the validity period of SAP tokens is specified in hours and minutes. Therefore, no finer granularity than minutes is possible. The specification in seconds of this property will be converted to hours and minutes automatically.
	encoding (string, "UTF-8")Encoding to use for the SAP token. Note that some SAP applications (in particular those running as native processes) do not support all encoding. In such cases, error messages may be misleading. Usage of the encoding "ISO8859-1 (ISO-LATIN-1)" is encouraged as this seems to be supported by all SAP products.
	systemId (string, "${system:host}")Identifier of issuing system (or issuer). This must match the key under which the issuer certificate was configured in the consuming service.
	systemClient (string, "000")Identifier of client. See SAP documentation of SAP SSO logon tickets for more information. Default value is SAP's default and should be correct for most cases.
	authScheme (string, "default")Authentication scheme associated with this ticket. See SAP documentation of SAP SSO logon tickets for more information. Default value is SAP's default and should be correct for most cases.
	recipientClient (string, -)See SAP documentation of SAP SSO logon tickets for more information. Setting no value for this property should be correct for most cases.
	recipientSID (string, -)See SAP documentation of SAP SSO logon tickets for more information. Setting no value for this property should be correct for most cases.
	cachingAllowed (boolean, -)If resolving to "true", this property enables the CachingAllowed flag in the issued ticket. See SAP documentation of SAP SSO logon tickets for more information.
	keystoreref, keyobjectref (reference to KeyStore and a KeyObject, -)This property configures the key and certificate to use when signing the SAP ticket.
	includeCertificate (boolean, false)When enabled, the signer's certificate is inserted into the issued SAP ticket.
	setCookie (string, -)If set, this property must specify the value of the HTTP header "Set-Cookie". The cookie will be issued to the client by nevisAuth such that a cookie-based SSO federation with SAP applications is possible. This property is evaluated after the ticket has been issued, so the variables listed in the topics "Notes" and "Output" can be used (see further below in this table).Example value for this property that sets the cookie as expected by SAP products: MYSAPSSO2=${outarg:sap.ticket}; Version=1; Path=/; Secure; HttpOnly; Max-Age=${notes:sap.ticket.maxAge}; Expires=${notes:sap.ticket.expires};
Methods	process (all events)
Input	none
Transitions	ok: Ticket issued successfully.
Output	sap.ticket: The SAP SSO logon ticket issued. Encoded in Base64 and with SAP's proprietary re-encoding applied.
Errors	none (throws AuthStateException)
Notes	sap.ticket.maxAge: TTL of issued ticket in seconds, for use in the MaxAge directive of the HTTP header "Set-Cookie".
	sap.ticket.expires: Expiration date of ticket issued, formatted for use in the Expires directive of the HTTP header "Set-Cookie".

Example

<AuthState name="IssueSapTicket" final="false"
 class="ch.nevis.esauth.auth.states.sap.SAPTicketIssuer" >
 <ResultCond name="ok" next="AuthDone"/>
 <Response value="AUTH_ERROR">
 <Gui name="AuthErrorDialog">
 <GuiElem name="lasterror" type="error" label="${notes:lasterrorinfo}" value="${notes:lasterror}" />
 </Gui>
 </Response>
 <property name="userIdSource" value="${notes:customSapUserId}" />
 <property name="applicationMappings" value="portal:${notes:customSapPortalUserId}" />
 <property name="encoding" value="ISO8859-1" />
 <property name="keystoreref" value="SAPKeyStore" />
 <property name="keyobjectref" value="Signer" />
</AuthState>

SAPTicketValidator

This AuthState may be used to validate and consume an SAP SSO logon ticket issued by an SAP product or by a nevisAuth instance.

Description

The following table describes the characteristics of the AuthState.

Topic	Description
Class	ch.nevis.esauth.auth.states.sap.SAPTicketValidator
Logging	SAP
Auditing	none
Marker	SAPTicket:token
Properties	ticket (string, "${cookie:MYSAPSSO2}")Source of SAP ticket.
	application (string, -)Identification of application played by nevisAuth. The user ID will be set according to mapping provided by the consumed ticket for this application.
	limitSessionLifetime (boolean, false)If enabled, the AuthState will limit the maximum lifetime of the session to match the lifetime of the consumed ticket.
	tolerance (duration in seconds, 10s)Tolerance to use when verifying tickets' validity period.
	keystoreref, keyobjectref (reference to KeyStore and a KeyObject, -)This property configures the certificates to use for verification of the SAP ticket.
	removeCookie (string, see below)The name of the cookie that shall be removed if the ticket verification or validation fails. If ticket is set to the default value, then this property will default to "MYSAPSSO2", the regular cookie name for SAP tickets. Otherwise, the property is not set by default.
Methods	process (all events)
Input	SAP SSO logon ticket, as configured by the property ticket.
Transitions	ok: Ticket validated and consumed successfully.
	failed: Ticket could not be verified, validated or consumed.
Output	sap.ticket: The issued SAP SSO logon ticket. Encoded in Base64 and with SAP's proprietary re-encoding applied.
Errors	1: Invalid SAP SSO ticket
Notes	sap.ticket.systemClientsap.ticket.systemIDsap.ticket.recipientClientsap.ticket.recipientSIDsap.ticket.authSchemesap.ticket.cachingAllowedsap.ticket.creationTimesap.ticket.codepageValues of well-known fields contained in the consumed ticket.
	sap.ticket.encodingsap.ticket.signer.subjectDNsap.ticket.signer.issuerDNsap.ticket.signer.serialNumbersap.ticket.signer.certificateValues derived of fields contained in the consumed ticket.

Example

<AuthState name="ConsumeSapTicket" final="false"
 class="ch.nevis.esauth.auth.states.sap.SAPTicketValidator" >
 <ResultCond name="ok" next="AuthDone"/>
 <Response value="AUTH_ERROR">
 <Gui name="AuthErrorDialog">
 <GuiElem name="lasterror" type="error" label="${notes:lasterrorinfo}" value="${notes:lasterror}" />
 </Gui>
 </Response>
 <property name="keystoreref" value="SAPKeyStore" />
</AuthState>