PUBLIC

SAP Single Sign-On 3.0 SP02Document Version: 1.0 – 2017-05-26

Policy Scripts Implementation Guide

Content

1 Policy Scripts Implementation Guide. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 31.1 Policy Scripts Installation Guide. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 31.2 Policy Scripts Operation Guide. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 5

Working with Policy Scripts. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 5Reusing Policy Scripts. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 8Examples of Policy Scripts. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 8

2 P U B L I CPolicy Scripts Implementation Guide

Content

1 Policy Scripts Implementation Guide

The policy scripts are used to customize access to business applications.

Prerequisites

1. You have deployed the installation file.For more information, see Policy Scripts Installation Guide [page 3].

2. You have created the policy and defined its script. The active version of the selected policy script is the one to be executed.For more information, see Policy Scripts Operation Guide [page 5].

Authentication Mechanisms

You implement the policy scripts in the Policy Script Administration Console by writing the logic in JavaScript. The following authentication mechanisms are supported with policy scripts:

● Authentication via TOTPLoginModuleThese policy scripts are used to customize access to business applications based on risk and contextual information, such as time, origin, authentication method, or device. The login module processes the active version of the specified script and decides which type of authentication to use.To use the policy scripts for authentication via a login module, see One-Time Password Login Module Options and Risk-Based Authentication Login Module Options.

● Authentication via an Identity Provider (IdP)For the IdP authentication, you specify policy scripts for IdP extensions as you can set policies for a trusted service provider or for all trusted service providers. These policy scripts can define which authentication method should be used, whether or not an assertion should be issued, and can define the attributes passed to the issued SAML 2.0 assertion.To use policy scripts for IdP extensions, you need to configure the scripts and the extensions. For more information about this configuration, see Configuring Policy Scripts for Identity Provider Extensions in Identity Provider Implementation Guide.

1.1 Policy Scripts Installation Guide

This section explains the requirements and the procedure for installing the library containing the policy scripts.

To use policy scripts for login modules or IdP extensions, you need to install SSO AUTHENTICATION LIBRARY 3.0.

Policy Scripts Implementation GuidePolicy Scripts Implementation Guide P U B L I C 3

System Requirements

You can install SSO AUTHENTICATION LIBRARY 3.0 on SAP NetWeaver Application Server (AS) Java 7.30 or higher.

Installation Steps

To install SSO AUTHENTICATION LIBRARY 3.0, perform the following steps:

1. Go to the SAP Software Download Center

2. In the navigation pane, choose SAP Software Download Center Support Packages and Patches .3. In the A-Z Index, navigate to the N section.

4. Navigate to the following product: SAP NW SINGLE SIGN ON SAP NW SINGLE SIGN ON 3.0 Comprised Software Component Versions SSO AUTHENTICATION LIBRARY 3.0

5. Download SCA SSOAUTHLIB <release>.sca.6. Deploy the SCA to the AS Java.

Required Authorizations

Users can only access the Policy Script Administration Console if they have been assigned the corresponding role or action. Provided you have permission to access SAP NetWeaver Administrator, you can assign roles to the corresponding user management engine (UME) groups, roles, or users. For more information, see Assigning Principals to UME Roles or Groups.

You should assign the following policy script roles to the UME groups or users that use the Policy Script Administration Console:

● RBA_POLICY_ADMIN This role is assigned to administrators to use the Policy Script Administration Console.

If you decide not to use this role, you need to assign the following actions to the UME roles that you will use for managing policy scripts:

● RBA_POLICY_WRITE This is an action for administrators using the Policy Script Administration Console.

● RBA_POLICY_READ This action gives read-only access to the Policy Script Administration Console.

4 P U B L I CPolicy Scripts Implementation Guide

Policy Scripts Implementation Guide

1.2 Policy Scripts Operation Guide

This section is intended to help you create and configure your policy scripts so that they meet your user access requirements.

Related Information

Working with Policy Scripts [page 5]Reusing Policy Scripts [page 8]Examples of Policy Scripts [page 8]

1.2.1 Working with Policy Scripts

In the Policy Script Administration Console, you can create and configure policy scripts, create new versions and view the history of changes made to a policy script.

Context

The Policy Script Administration Console contains three screen sections: Policies, Versions of Policy <policy name> and Content of Version <version of policy>.

Policies

In the table below Policies, you can see the policies that have already been created or migrated (if you have used policy scripts in SAP Single Sign-On 2.0 and have upgraded to SAP Single Sign-On 3.0), together with their status, type, name, UID (unique ID) and description. If you want to see details about the versions of a policy script, select the policy script in the Policies section. All the versions of the selected policy script will appear in the Versions of Policy <policy name> section.

In this section, you can perform the following operations:

Table 1:

Operation Description

Create... Create a policy script of type Procedure or Library.

When you save the new policy script, it has the status Draft.

Policy Scripts Implementation GuidePolicy Scripts Implementation Guide P U B L I C 5

Operation Description

Policy Script of Type Procedure

Enter the name of the policy. If you are not go­ing to reuse the policy in another policy script, select the Procedure type and specify the script under the Content field. Write the code in Java­Script language.

For more information, see Examples of Policy Scripts [page 8].

Policy Script of Type Library

Enter the name of the policy script, select the Library type and specify the script under the Content field. Write the code in JavaScript lan­guage.

NoteThe scripts of type Library cannot be executed independently. They can only be reused in a policy script of type Procedure.

For more information, see Reusing Policy Scripts [page 8].

Delete Delete a policy script if you are not using it.

CautionOnce deleted, the policy script is removed from the list of policies, and you cannot revert it. If you are not using a policy script, we recommend disabling it.

Edit... Edit the name, description or type of the policy script.

NoteIf you change the name of a policy script of type Library, which is included in other policy scripts, you also have to change the name manually in all policy scripts which include it.

To edit a specific version of the policy script, see Edit... in theVersions of Policy <policy name> sec­tion.

Enable Enable a disabled policy script if you want to use it.

Disable Disable the policy script if you don’t want to use it. If you need to use it again, you have to enable it first.

NoteA disabled policy script of type Procedure cannot be executed.

An enabled policy script of type Procedure cannot be executed if it includes a disabled policy script of type Library.

Import... Import a policy script from a TXT file.

6 P U B L I CPolicy Scripts Implementation Guide

Policy Scripts Implementation Guide

Operation Description

Export... Export the selected policy script in a TXT file. Choose whether to export the Active Version, Selected Version or All Versions of the policy script. If you export the selected version or the active version, you will get a single TXT file. If you export all versions, you get a ZIP file with the versions as TXT files.

Versions of Policy <policy name>

In the table below Versions of Policy <policy name>, you can see all the versions of the policy script selected in the Polices section, which is the active version, together with the number of the version, its status, and comments.

In this section, you can perform the following operations:

Table 2:

Operation Description

New Draft Create a new version of a released policy script.

You can only have one draft version of a policy script.

Edit... Edit the selected version.

If you edit a draft policy script, the changes are made in the existing draft version.

If you edit a released version, you can only change the comments to the policy script. You can’t change the content of the script.

Release Release a policy script version to be able to create new versions of the policy script. Once released, a policy script cannot be set back to status Draft.

To edit the content of a released policy script version, you have to create a new draft.

Activate Activate the selected version. Only the activated versions of the policies can be used for au­thentication via a Login Module or via an Identity Provider (IdP).

History... View the history of the selected version.

Content of Version <version of policy>

In this section, you see the content of the policy script version selected in the Versions of Policy <policy name> screen section.

Procedure

1. Log on to the Policy Script Administration Console at http(s)://<host>:<port>/ssoadmin/scripts.

2. Configure the policy scripts.

For examples of policy scripts, see Examples of Policy Scripts [page 8].3. Save your configurations.

Policy Scripts Implementation GuidePolicy Scripts Implementation Guide P U B L I C 7

1.2.2 Reusing Policy Scripts

You can create a policy script for the purpose of reusing it in another policy script.In the second policy script, which must be of type Procedure, you can then reuse the active version of the policy script of the first policy with the include directive.

Context

To include a policy in another policy, proceed as follows:

Procedure

1. Log on to the Policy Script Administration Console at http(s)://<host>:<port>/ssoadmin/scripts.

2. Choose the Create... button to create a new policy script.3. Select Library type and enter the name.4. In the Content field, enter the script to be included in the other policy.

5. Include this policy in another policy of type Procedure.

You have to use the include directive in the following format:

#include “<name of library access policy>”

At runtime, this directive line is replaced with the code of the referenced library, exactly as it appears in the library.

For examples, see Examples of Policy Scripts [page 8].

Note○ If you change the name of a policy script of type Library, which is included in other policy scripts, you

also have to change the name manually in all policy scripts which include it.○ An enabled policy script of type Procedure cannot be executed if it includes a disabled policy script of

type Library.

1.2.3 Examples of Policy Scripts

These are a few examples for policy scripts of type Procedure and Library.

8 P U B L I CPolicy Scripts Implementation Guide

Policy Scripts Implementation Guide

Examples

Write the code in JavaScript language.

ExampleExample for a script of type Procedure

// A policy script that requests second factor authentication for users which // country is not DE (Germany).//// The following objects (input parameters) are provided to the policy script// - naming : javax.naming.InitialContext - interface to JNDI// - logger - interface to the logging and tracing with methods:// -- traceError(message : String)// -- traceError(message : String, throwable : Object)// -- traceWarning(message : String)// -- traceWarning(message : String, throwable : Object)// -- traceInfo(message : String)// -- traceDebug(message : String)// -- traceDebug(message : String, throwable : Object)// -- logError(message : String)// -- logWarning(message : String)// -- logInfo(message : String)// - clientRequest with methods:// -- getClientIP() : String// -- getHeader(name : String) : String// -- getCookie(name : String) : String// - user : com.sap.security.api.IUser// - result - interface for providing output parameters from the script with methods:// -- put(key : String, value : Object)//// Expected output parameters:// - trigger.otp with value either true or false//logger.logInfo('Called script that enforces TFA for some users');var ip = clientRequest.getClientIP();logger.traceInfo('Request is coming from IP: ' + ip);var userCountry = user.getCountry();if (userCountry == 'DE') { result.put('trigger.otp', false);} else { result.put('trigger.otp', true);}

ExampleExample of Library Policy Script set_ip_as_saml_attribute

function setIpAsAttribute() { var ip = saml2AssertionDetails.getHttpRequest().getRemoteAddr(); logger.traceDebug('Request is coming from IP: ' + ip); var ipAttribute = saml2AttributeDatabag.addAttribute('IP', ip); }

ExampleExample Procedure Policy Script Reusing the Library Policy

#include "set_ip_as_saml_attribute";

Policy Scripts Implementation GuidePolicy Scripts Implementation Guide P U B L I C 9

logger.traceInfo('Called script that provides SAML 2.0 attributes for the assertions issued by the IdP');setIpAsAttribute(); result.put('saml2.attributes', saml2AttributeDatabag);

For more policy script examples, see One-Time Password Authentication Developer Guide.

10 P U B L I CPolicy Scripts Implementation Guide

Policy Scripts Implementation Guide

Important Disclaimers and Legal Information

Coding SamplesAny software coding and/or code lines / strings ("Code") included in this documentation are only examples and are not intended to be used in a productive system environment. The Code is only intended to better explain and visualize the syntax and phrasing rules of certain coding. SAP does not warrant the correctness and completeness of the Code given herein, and SAP shall not be liable for errors or damages caused by the usage of the Code, unless damages were caused by SAP intentionally or by SAP's gross negligence.

AccessibilityThe information contained in the SAP documentation represents SAP's current view of accessibility criteria as of the date of publication; it is in no way intended to be a binding guideline on how to ensure accessibility of software products. SAP in particular disclaims any liability in relation to this document. This disclaimer, however, does not apply in cases of willful misconduct or gross negligence of SAP. Furthermore, this document does not result in any direct or indirect contractual obligations of SAP.

Gender-Neutral LanguageAs far as possible, SAP documentation is gender neutral. Depending on the context, the reader is addressed directly with "you", or a gender-neutral noun (such as "sales person" or "working days") is used. If when referring to members of both sexes, however, the third-person singular cannot be avoided or a gender-neutral noun does not exist, SAP reserves the right to use the masculine form of the noun and pronoun. This is to ensure that the documentation remains comprehensible.

Internet HyperlinksThe SAP documentation may contain hyperlinks to the Internet. These hyperlinks are intended to serve as a hint about where to find related information. SAP does not warrant the availability and correctness of this related information or the ability of this information to serve a particular purpose. SAP shall not be liable for any damages caused by the use of related information unless damages have been caused by SAP's gross negligence or willful misconduct. All links are categorized for transparency (see: http://help.sap.com/disclaimer).

Policy Scripts Implementation GuideImportant Disclaimers and Legal Information P U B L I C 11

go.sap.com/registration/contact.html

© 2017 SAP SE or an SAP affiliate company. All rights reserved.No part of this publication may be reproduced or transmitted in any form or for any purpose without the express permission of SAP SE or an SAP affiliate company. The information contained herein may be changed without prior notice.Some software products marketed by SAP SE and its distributors contain proprietary software components of other software vendors. National product specifications may vary.These materials are provided by SAP SE or an SAP affiliate company for informational purposes only, without representation or warranty of any kind, and SAP or its affiliated companies shall not be liable for errors or omissions with respect to the materials. The only warranties for SAP or SAP affiliate company products and services are those that are set forth in the express warranty statements accompanying such products and services, if any. Nothing herein should be construed as constituting an additional warranty.SAP and other SAP products and services mentioned herein as well as their respective logos are trademarks or registered trademarks of SAP SE (or an SAP affiliate company) in Germany and other countries. All other product and service names mentioned are the trademarks of their respective companies.Please see http://www.sap.com/corporate-en/legal/copyright/index.epx for additional trademark information and notices.