1 About the Concur Connector

The Concur connector integrates Oracle Identity Manager with the Concur target system.

This chapter contains the following sections:

1.1 Introduction to the Concur Connector

Oracle Identity Manager is a centralized identity management solution that provides self service, compliance, provisioning and password management services for applications residing on-premise or on the Cloud. Oracle Identity Manager connectors are used to integrate Oracle identity Manager with the external and identity-aware applications. The Concur connector enables you to use Concur as a managed (target) resource of identity data for Oracle identity Manager.

The Concur connector uses OAuth 2.0 security protocol (Native Flow) for connecting to Concur and performing user authentication.

You can configure the Concur connector to run in the Account Management (or target resource management) mode. In this mode of the connector, information about users that are created or modified directly on Concur can be reconciled into Oracle identity Manager. This data is used to add or modify resources (that is, accounts) that are allocated to Oracle Identity Manager Users. In addition, you can use Oracle Identity Manager to provision or update Concur accounts that are assigned to Oracle Identity Manager Users.

Note:

At some places in this guide, Concur has been referred to as the target system.

1.2 Certified Components for the Concur Connector

These are the software components and their versions required for installing and using the connector.

Table 1-1 Certified Components

Component	Requirement
Oracle Identity Governance or Oracle Identity Manager	You can use one of the following releases of Oracle Identity Manager: Oracle Identity Governance 12c (12.2.1.4.0) Oracle Identity Governance 12c (12.2.1.3.0) Oracle Identity Manager 11g Release 2 PS2 BP09 (11.1.2.2.9) Oracle Identity Manager 11g Release 2 PS3 BP06 (11.1.2.3.6)
Target system	Concur
Connector Server	11.1.2.1.0
Connector Server JDK	JDK 1.6 or later

1.3 Certified Languages for the Concur Connector

These are the languages that the connector supports.

Arabic
Chinese (Simplified)
Chinese (Traditional)
Czech
Danish
Dutch
English (US)
Finnish
French
French (Canadian)
German
Greek
Hebrew
Hungarian
Italian
Japanese
Korean
Norwegian
Polish
Portuguese
Portuguese (Brazilian)
Romanian
Russian
Slovak
Spanish
Swedish
Thai
Turkish

1.4 Architecture of the Concur Connector

The Concur connector can be configured to run in the Account Management (or target resource management) mode, and is implemented using the Integrated Common Framework (ICF) component.

This connector enables the following operations:

Provisioning

Provisioning involves creating and updating users on Concur through Oracle Identity Manager. When you allocate (or provision) a Concur resource to an Oracle Identity Manager User, the operation results in the creation of an account on Concur for that user. In the Oracle Identity Manager context, the term "provisioning" is also used to mean updates (for example enabling or disabling) made to the Concur account through Oracle Identity Manager.
Target resource reconciliation

To perform target resource reconciliation, the Concur Recon scheduled job is used. The connector then fetches the user attribute values from Concur.

Figure 1-1 Architecture of the Concur Connector

Description of "Figure 1-1 Architecture of the Concur Connector"

As shown in Figure 1-1, Concur is configured as a target resource of Oracle Identity Manager. Through the provisioning operations that are performed on Oracle Identity Manager, accounts are created and updated on Concur for Oracle Identity Manager Users.

Through reconciliation, account data that is created and updated directly on Concur is fetched into Oracle Identity Manager and stored against the corresponding Oracle Identity Manager Users.

The Concur connector is implemented using the ICF component. The ICF component provides basic reconciliation and provisioning operations that are common to all Oracle Identity Manager connectors. In addition, ICF provides common features that developers would otherwise need to implement on their own, such as connection pooling, buffering, time outs, and filtering. ICF is distributed together with Oracle Identity Manager. Therefore, you do not need to configure or modify ICF.

During provisioning, the adapters invoke ICF operation, ICF invokes the Create operation on Concur Connector Bundle, and then the bundle calls the OAuth API. The OAuth API uses OAuth method (Native Flow) to connect to Concur. Concur accepts provisioning data from the bundle, carries out the operation, and returns the response back to the bundle. The bundle then passes it to the adapters.

1.5 Use Cases Supported by the Concur Connector

The Concur connector provides user management functionality that helps in managing users and their accounts in Concur through Oracle Identity Manager.

The following is a scenario in which the Concur connector can be used:

Organizations use Concur for managing their travel and expense (T&E) information. The administrator needs to create and grant login access to the concerned employees in the Concur portal. When the employee leaves the organization, the administrator needs to ensure that the employee must no longer be able to access the sensitive information using their Concur account. Doing these tasks manually for every employee is cumbersome and error-prone. The Concur connector enables automation of provisioning and deprovisioning of the user accounts in Concur. Whenever a new employee joins the organization, based on the access policies defined in Oracle Identity Manager, a Concur account is automatically provisioned to that employee with appropriate access rights. Similarly, upon quitting the organization, the same account is automatically deactivated. This saves time and provides robust security as there is little manual intervention.

1.6 Features of the Concur Connector

The features of the connector include support for connector server, full reconciliation, limited reconciliation, and reconciliation of deleted account data.

The Concur Connector supports the following features:

1.6.1 Full Reconciliation

In full reconciliation, all records are fetched from the target system to Oracle Identity Manager.

See Full Reconciliation for more information on performing full and incremental reconciliation.

1.6.2 Support for the Connector Server

Connector Server is one of the features provided by ICF. By using one or more connector servers, the connector architecture permits your application to communicate with externally deployed bundles.

See Installation for more information about the installation options for this connector.

1.6.3 Limited Reconciliation

You can reconcile records from the target system based on a specified filter criterion. To limit or filter the records that are fetched into Oracle Identity Manager during a reconciliation run, you can specify the subset of added or modified target system records that must be reconciled.

You can set a reconciliation filter as the value of the Filter Suffix attribute of the user reconciliation scheduled job. The Filter Suffix attribute helps you to assign filters to the API based on which you get a filtered response from the target system.

See Limited Reconciliation for the Concur Connector for more information on limited reconciliation.

1.6.4 Transformation and Validation of Account Data

You can configure validation of account data that is brought into or sent from Oracle Identity Manager during reconciliation and provisioning. In addition, you can configure transformation of account data that is brought into Oracle Identity Manager during reconciliation.

The following sections provide more information:

1.7 Lookup Definitions Used During Connector Operations

Lookup definitions used during reconciliation and provisioning are preconfigured. Preconfigured lookup definitions are automatically created in Oracle Identity Manager after you deploy the connector. These lookup definitions are either prepopulated with values or values must be manually entered in them after the connector is deployed.

The preconfigured lookup definitions are as follows:

1.7.1 Lookup.Concur.Configuration

The Lookup.Concur.Configuration lookup definition holds connector configuration entries that are used during the target resource reconciliation and provisioning operations.

Table 1-2 lists the default entries in this lookup definition.

Note:

Do not modify the entries in this lookup definition.

Table 1-2 Entries in the Lookup.Concur.Configuration Lookup Definition

Code Key	Decode	Description
Bundle Name	org.identityconnectors.genericrest	This entry holds the name of the connector bundle.
Bundle Version	1.0.1115	This entry holds the version of the connector bundle.
Connector Name	org.identityconnectors.genericrest.GenericRESTConnector	This entry holds the name of the connector class.
customAuthClassName	oracle.iam.connectors.concur.auth.ConcurNativeAuth	This entry holds the name of the Auth Class that is used for authorizing user access to the target system.
customParserClassName	oracle.iam.connectors.concur.parser.ConcurResponseParser	This entry holds the name of the Parser Class that is used for parsing responses for the connector operations that are not in the standard JSON format.
customPayload	"__ACCOUNT__.CREATEOP=<batch xmlns=\"http://www.concursolutions.com/api/user/2011/02\"><UserProfile><EmpId>$(EmployeeID)$</EmpId> <FeedRecordNumber>1</FeedRecordNumber><LoginId>$(__NAME__)$</LoginId><FirstName>$(FirstName)$</FirstName><LastName>$(LastName)$</LastName><Password>##$(__PASSWORD__)$##</Password><CtryCode>$(CountryofResidence)$</CtryCode><LocaleName>$(Locale)$</LocaleName><CrnKey>$(ReimbursementCurrency)$</CrnKey><Custom21>$(EmployeeAdministrationCountry)$</Custom21><Active>$(__ENABLE__)$</Active><EmailAddress>$(EmailAddress)$</EmailAddress><LedgerKey>$(Ledger)$</LedgerKey><Mi>$(MiddleName)$</Mi><ExpenseApproverEmployeeID>$(ExpenseApproverEmployeeID)$</ExpenseApproverEmployeeID></UserProfile></batch>",<UserProfile><EmpId>$(EmployeeID)$</EmpId><FeedRecordNumber>1</FeedRecordNumber><LoginId>$(__NAME__)$</LoginId><FirstName>$(FirstName)$</FirstName><LastName>$(LastName)$</LastName><Password>##$(__PASSWORD__)$##</Password><CtryCode>$(CountryofResidence)$</CtryCode><LocaleName>$(Locale)$</LocaleName><CrnKey>$(ReimbursementCurrency)$</CrnKey><Custom21>$(EmployeeAdministrationCountry)$</Custom21><Active>$(__ENABLE__)$</Active><EmailAddress>$(EmailAddress)$</EmailAddress><LedgerKey>$(Ledger)$</LedgerKey><Mi>$(MiddleName)$</Mi><ExpenseApproverEmployeeID>$(ExpenseApproverEmployeeID)$</ExpenseApproverEmployeeID></UserProfile></batch>","__ACCOUNT__.__PASSWORD__.UPDATEOP=<UserBatch xmlns=\"http://www.concursolutions.com/api/user/2011/02\"><User><LoginID>$(__UID__)$</LoginID><Password>##$(__PASSWORD__)$##</Password></User></UserBatch>"	This entry lists the request payload formats for all the connector operations that are not in the standard JSON format.
httpHeaderAccept	application/json	This entry holds the accept type expected from the target system in the header.
httpHeaderContentType	application/xml	This entry holds the content type expected by the target system in the header.
jsonResourcesTag	"__ACCOUNT__=Items"	This entry holds the JSON tag value that is used during reconciliation for parsing multiple entries in a single payload.
nameAttributes	"__ACCOUNT__.LoginID"	This entry holds the name attribute for all the objects that are handled by this connector. For example, for the __ACCOUNT__ object class that it used for User accounts, the name attribute is LoginID.
opTypes	"__ACCOUNT__.CREATEOP=POST","__ACCOUNT__.UPDATEOP=POST","__ACCOUNT__.SEARCHOP=GET","__ACCOUNT__.__PASSWORD__.UPDATEOP=POST"	This entry specifies the HTTP operation type for each object class supported by the connector. Values are comma separated and are in the following format: OBJ_CLASS.OP=HTTP_OP In this format, OBJ_CLASS is the connector object class, OP is the connector operation (for example, CreateOp, UpdateOp, SearchOp), and HTTP_OP is the HTTP operation (GET, PUT, or POST).
passwordAttribute	Password	This entry holds the name of the target system attribute that is mapped to the __PASSWORD__ attribute of the connector in OIM.
relURIs	"__ACCOUNT__.CREATEOP=/api/user/v1.0/users","__ACCOUNT__.UPDATEOP=/api/user/v1.0/users","__ACCOUNT__.__PASSWORD__.UPDATEOP=/api/user/v1.0/users/password","__ACCOUNT__.SEARCHOP=/api/v3.0/common/users/$(Filter Suffix)$"	This entry holds the relative URL of every object class supported by this connector and the connector operations that can be performed on these object classes. For example, the `__ACCOUNT__.CREATEOP=/api/user/v1.0/users` value implies that `/api/user/v1.0/users` is the relative URL for all create provisioning operations that are performed on the __ACCOUNT__ object class.
statusAttributes	"__ACCOUNT__.Active"	This entry lists the name of the target system attribute that holds the status of an account. For example, for the __ACCOUNT__ object class that it used for User accounts, the status attribute is Active.
uidAttributes	"__ACCOUNT__.LoginID"	This entry holds the UID attribute for the User object class that is handled by this connector. The value “__ACCOUNT__.LoginID” in decode implies that the __UID__ attribute (that is, GUID) of the connector for __ACCOUNT__ object class is mapped to LoginID, which is the corresponding UID attribute for user accounts in the target system.
User Configuration Lookup	Lookup.Concur.UM.Configuration	This entry holds the name of the lookup definition that stores configuration information used during user management operations.

1.7.2 Lookup.Concur.UM.Configuration

The Lookup.Concur.UM.Configuration lookup definition holds configuration entries that are specific teo the user object type. This lookup definition is used during user management operations in the target resource mode.

Table 1-3 lists the entries in this lookup definition.

Table 1-3 Entries in the Lookup.Concur.UM.Configuration Lookup

Code Key	Decode	Description
Provisioning Attribute Map	Lookup.Concur.UM.ProvAttrMap	This entry holds the name of the lookup definition that maps process form fields and target system attributes. This lookup definition is used during user provisioning operations.
Recon Attribute Map	Lookup.Concur.UM.ReconAttrMap	This entry holds the name of the lookup definition that maps resource object fields and target system attributes.. This lookup definition is used during reconciliation.

1.7.3 Lookup.Concur.UM.ProvAttrMap

The Lookup.Concur.UM.ProvAttrMap lookup definitions hold mappings between process form fields and target system attributes. This lookup definition is preconfigured, and is used during provisioning.

You can add entries in this lookup definition if you want to map new target system attributes for provisioning. See Adding User Attributes for Provisioning.

Table 1-4 lists the default entries in this lookup definition.

Table 1-4 Default Entries in the Lookup.Concur.UM.ProvAttrMap Lookup Definition

Code	Decode
Country of Residence	CountryofResidence
Email Address	EmailAddress
Employee Administration Country	EmployeeAdministrationCountry
Employee ID	EmployeeID
First Name	FirstName
Id	__UID__
Last Name	LastName
Ledger	Ledger
Locale	Locale
Login ID	__NAME__
Manager	ExpenseApproverEmployeeID
Middle Name	MiddleName
Password	__PASSWORD__
Reimbursement Currency	ReimbursementCurrency
Status	__ENABLE__

1.7.4 Lookup.Concur.UM.ReconAttrMap

The Lookup.Concur.UM.ReconAttrMap lookup definition holds mappings between resource object fields and target system attributes. This lookup definition is preconfigured, and is used during reconciliation.

You can add entries in this lookup definition if you want to map new target system attributes for target resource reconciliation. See Adding User Attributes for Reconciliation.

Table 1-5 lists the default entries in this lookup definition.

Table 1-5 Default Entries in the Lookup.Concur.UM.ReconAttrMap Lookup Definition

Code	Decode
Email Address	PrimaryEmail
Employee ID	EmployeeID
First Name	FirstName
IsActive	IsActive=__ENABLE__?'Y':'N'
Last Name	LastName
ID	__UID__
Login ID	__NAME__
Middle Name	MiddleName
Status	__ENABLE__

1.7.5 Lookup.Concur.BooleanValues

The Lookup.Concur.BooleanValues lookup definition maps boolean values that are used for some of the fields in the target system with the corresponding boolean values to be displayed in the fields of the OIM User form.

Table 1-6 lists the default entries in this lookup definition.

Table 1-6 Default Entries in the Lookup.Concur.BooleanValues Lookup Definition

Code	Decode
N	False
Y	True

1.7.6 Lookup.Concur.Locale

The Lookup.Concur.Locale lookup definition holds information about the supported locale codes for a target system account. This setting determines the display formats for date and time, users’ names, addresses, and commas and periods in numbers.

This is a static lookup definition. You must manually populate the entries of this lookup definition.

The following is the format of the Code Key and Decode values in this lookup definition:

Code Key: Supported locale code for a target system account
Decode: Name of the corresponding locale

Table 1-7 lists the sample entries in this lookup definition.

Table 1-7 Sample Entries in the Lookup.Concur.Locale Lookup Definition

Code	Decode
en_US	English (United States)

1.7.7 Lookup.Concur.CountryofResidence

The Lookup.Concur.CountryofResidence lookup definition holds information about countries that you can assign as a country of residence for a target system user account that you create through Oracle Identity Manager. This is a static lookup definition. You must populate the entries of this lookup definition manually.

The following is the format of the Code Key and Decode values in this lookup definition:

Code Key: 2–letter ISO code for a country
Decode: Country name

Table 1-8 lists the default entries in this lookup definition.

Table 1-8 Default Entries in the Lookup.Concur.CountryofResidence Lookup Definition

Code Key	Decode
US	UNITED STATES

1.7.8 Lookup.Concur.Currency

The Lookup.Concur.Currency lookup definition holds information about the currency codes that you can assign as a reimbursement currency for a target system user account.

You can either assign a default currency code based on the country that is configured for the user in the Lookup.Concur.CountryofResidence lookup definition or update the currency code by selecting a value from this lookup definition.

This is a static lookup definition, and you must manually populate the entries of this lookup definition.

The following is the format of the Code Key and Decode values in this lookup definition:

Code Key: 3–letter ISO code for a currency
Decode: 2–letter code of the corresponding country and the currency name

Table 1-9 lists the default entries in this lookup definition.

Table 1-9 Default Entries in the Lookup.Concur.Currency Lookup Definition

Code Key	Decode
USD	US, Dollar

1.7.9 Lookup.Concur.EmployeeAdminCountry

The Lookup.Concur.EmployeeAdminCountry lookup definition holds information about the country from where you want to administer the employee that you select for a target system account.

All of the policies of the specific country are applicable to the employee. For example, if you specify United States for an employee in Canada, the United States policies are applicable to the employee.

This is a static lookup definition. You must manually populate the entries of this lookup definition.

The following is the format of the Code Key and Decode values in this lookup definition:

Code Key: 2–letter country code from where you want to administer the employee
Decode: Name of the country

Table 1-10 lists the default entries in this lookup definition.

Table 1-10 Default Entries in the Lookup.Concur.EmployeeAdminCountry Lookup Definition

Code	Decode
US	United States

1.7.10 Lookup.Concur.Ledger

The Lookup.Concur.Ledger lookup definition holds the accepted account code ledger value for a target system user account.

Note:

Do not add entries or modify values of this lookup definition.

Table 1-11 lists the default entries in this lookup definition.

Table 1-11 Default Entries of the Lookup.Concur.Ledger Lookup Definition

Code	Decode
DEFAULT	DEFAULT

1.8 Connector Objects Used During Target Resource Reconciliation

Connector objects such as reconciliation rules, reconciliation action rules, and scheduled jobs are used for reconciling user records from the target system into Oracle Identity Manager.

The Concur Target Resource User Reconciliation scheduled job is used to initiate a reconciliation run. See Reconciliation Scheduled Job for Concur Connector for more information on this scheduled job.

1.8.1 User Fields for Target Resource Reconciliation

The Lookup.Concur.UM.ReconAttrMap lookup definition maps resource object fields with target system attributes. This lookup definition is used for performing target resource user reconciliation runs.

In this lookup definition, entries are in the following format:

Code Key: Reconciliation field of the resource object
Decode: Name of the target system attribute

Table 1-12 lists the entries in this lookup definition.

Table 1-12 Entries in the Lookup.Concur.UM.ReconAttrMap Lookup Definition

Code Key	Decode
Email Address	PrimaryEmail
Employee ID	EmployeeID
First Name	FirstName
IsActive	IsActive=__ENABLE__?'Y':'N'
Id	__UID__
Last Name	LastName
Login ID	__NAME__
Middle Name	MiddleName
Status	__ENABLE__

1.8.2 Reconciliation Rules for Target Resource Reconciliation

Reconciliation rules for target resource reconciliation are used by the reconciliation engine to determine the identity to which Oracle Identity Manager must assign a newly discovered account on the target system.

The following is the process-matching rule for users:

Rule name: Concur User Recon Rule

Rule element: Email Equals Login ID

In this rule element:

Email is the email address attribute of a user.
Login ID is a unique ID attribute of the Concur account.

1.8.3 Viewing Reconciliation Rules for Target Resource Reconciliation

You can view reconciliation rules by using Oracle Identity Manager Design Console.

To view reconciliation rules for target resource reconciliation:

Log in to Oracle Identity Manager Design Console.
Expand Development Tools.
Double-click Reconciliation Rules.
Search for and open the Concur User Recon Rule.

Figure 1-2 Concur User Recon Rule

Description of "Figure 1-2 Concur User Recon Rule"

1.8.4 Reconciliation Action Rules for Target Resource Reconciliation

Reconciliation action rules define that actions the connector must perform based on the reconciliation rules defined for Users.

Table 1-13 lists the rule condition and the corresponding action to be performed during target resource reconciliation.

Table 1-13 Action Rules for Target Resource Reconciliation

Rule Condition	Action
No Matches Found	None
One Entity Match Found	Establish Link
One Process Match Found	Establish Link

1.8.5 Viewing Reconciliation Action Rules for Target Resource Reconciliation

You can view reconciliation action rules on the Object Reconciliation tab of a resource object in Oracle Identity Manager Design Console.

To view reconciliation action rules for target resource reconciliation:

Log in to Oracle Identity Manager Design Console.
Expand Resource Management.
Double-click Resource Objects.
Search for and open the Concur User resource object.
Click the Object Reconciliation tab, and then click the Reconciliation Action Rules tab.
The Reconciliation Action Rules tab displays the action rules defined for this connector.

Figure 1-3 Reconciliation Action Rules for Target Resource Reconciliation

Description of "Figure 1-3 Reconciliation Action Rules for Target Resource Reconciliation"

1.9 Connector Objects Used During Provisioning

Connector objects such as adapters are used for performing provisioning operations on the target system. These adapters perform provisioning functions on the fields defined in the lookup definition for provisioning.

This section contains the following topics:

1.9.1 Provisioning Functions

These are the supported provisioning functions and the adapters that perform these functions for the connector.

The Adapter column in Table 1-14 gives the name of the adapter that is used when the function is performed.

Function	Adapter
Create User	adpCONCURCREATEUSER
Update User	adpCONCURUPDATEUSER
Enable user	adpCONCURENABLETASK
Disable user	adpCONCURDISABLETASK
Change or reset password	adpCONCURPASSWORDUPDATE

1.9.2 User Fields for Provisioning

The Lookup.Concur.UM.ProvAttrMap lookup definition holds the user fields for provisioning. This lookup definition holds mapping between process form fields and target system attributes.

Table 1-15 lists the entries in the lookup definition.

Table 1-15 Entries in the Lookup.Concur.UM.ProvAttrMap Lookup Definitions

Code Key	Decode
Country of Residence	CountryofResidence
Email Address	EmailAddress
Employee Administration Country	EmployeeAdministrationCountry
Employee ID	EmployeeID
First Name	FirstName
Id	__UID__
Last Name	LastName
Ledger	Ledger
Locale	Locale
Login ID	__NAME__
Manager	ExpenseApproverEmployeeID
Middle Name	MiddleName
Password	__PASSWORD__
Reimbursement Currency	ReimbursementCurrency
Status	__ENABLE__

1.10 Roadmap for Deploying and Using the Concur Connector

This is the organization of information available in this guide for deploying and using the connector.

The rest of this guide is divided into the following chapters:

Deploying the Concur Connector describes procedures that you must perform on Oracle Identity Manager and the target system during each stage of connector deployment.
Using the Concur Connector describes guidelines on using the connector, and explains procedures to configure reconciliation runs and perform provisioning operations.
Extending the Functionality of the Concur Connector describes procedures that you can perform if you want to extend the functionality of the connector.
Files and Directories on the Concur Connector Installation Media lists the files and directories that comprise the connector installation media.