SAML 2 Quick Start Guide · products, and services from third parties. Oracle Corporation and its affiliates are not responsible for and expressly disclaim all warranties of any kind

SAML 2 Quick Start Guide

October 12, 2019

Copyright © 2013, 2020, Oracle and/or its affiliates. All rights reserved.

This software and related documentation are provided under a license agreement containing restrictionson use and disclosure and are protected by intellectual property laws. Except as expressly permittedin your license agreement or allowed by law, you may not use, copy, reproduce, translate, broadcast,modify, license, transmit, distribute, exhibit, perform, publish, or display any part, in any form, or by anymeans. Reverse engineering, disassembly, or decompilation of this software, unless required by law forinteroperability, is prohibited.

The information contained herein is subject to change without notice and is not warranted to be error-free. If you find any errors, please report them to us in writing.

If this is software or related documentation that is delivered to the U.S. Government or anyone licensing iton behalf of the U.S. Government, then the following notice is applicable:

U.S. GOVERNMENT END USERS: Oracle programs, including any operating system, integrated software,any programs installed on the hardware, and/or documentation, delivered to U.S. Government endusers are "commercial computer software" pursuant to the applicable Federal Acquisition Regulationand agency-specific supplemental regulations. As such, use, duplication, disclosure, modification, andadaptation of the programs, including any operating system, integrated software, any programs installedon the hardware, and/or documentation, shall be subject to license terms and license restrictionsapplicable to the programs. No other rights are granted to the U.S. Government.

This software or hardware is developed for general use in a variety of information managementapplications. It is not developed or intended for use in any inherently dangerous applications, includingapplications that may create a risk of personal injury. If you use this software or hardware in dangerousapplications, then you shall be responsible to take all appropriate fail-safe, backup, redundancy, and othermeasures to ensure its safe use. Oracle Corporation and its affiliates disclaim any liability for any damagescaused by use of this software or hardware in dangerous applications.

Oracle and Java are registered trademarks of Oracle and/or its affiliates. Other names may be trademarksof their respective owners.

Intel and Intel Xeon are trademarks or registered trademarks of Intel Corporation. All SPARC trademarksare used under license and are trademarks or registered trademarks of SPARC International, Inc.AMD, Opteron, the AMD logo, and the AMD Opteron logo are trademarks or registered trademarks ofAdvanced Micro Devices. UNIX is a registered trademark of The Open Group.

This software or hardware and documentation may provide access to or information about content,products, and services from third parties. Oracle Corporation and its affiliates are not responsible for andexpressly disclaim all warranties of any kind with respect to third-party content, products, and servicesunless otherwise set forth in an applicable agreement between you and Oracle. Oracle Corporation andits affiliates will not be responsible for any loss, costs, or damages incurred due to your access to or useof third-party content, products, or services, except as set forth in an applicable agreement between youand Oracle.

Table of ContentsOpenAir SAML 2 Quick Start Guide . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1

Identity Provider Setup . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1Provider Integration Setup . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1OpenAir Account Configuration . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 10OpenAir Mobile Apps and SAML2 . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 15

OpenAir SAML 2 Quick Start Guide 1

OpenAir SAML 2 Quick Start Guide

Identity Provider SetupThis section details OpenAir Service Provider authentication attribute mapping.

Below are the relevant SAML assertion fields for exchanges. The mapping describes the relationshipbetween SAML attributes to OpenAir login identifiers.

1. SAML NameID: OpenAir User ID which represents the unique user nicknames defined in theOpenAir account.

Note: If this field does not send the user’s nickname as a persistent attribute, then theprovider must follow Step 3 below.

2. SAML assertion string attribute account_nickname: OpenAir Company ID. This is the name ofyour OpenAir account.

3. [Optional] SAML assertion string attribute user_nickname: alternate OpenAir User ID. Ifspecified, the user_nickname takes precedence over NameID for identifying the user. Use ofthis attribute provides the IdP with an option to use a transient NameID for session management,while still providing the user nickname for OpenAir authentication.

Important: These attributes must be included in all SAML assertions, unless otherwisemarked as [Optional]. NameID is still required when using user_nickname for OpenAirauthentication.

Note: OpenAir does not support multiple identity providers. For example, customers cannot useboth Okta and Azure at the same time.

Provider Integration SetupThe steps below describe one-time setup requirements necessary before assertions can be exchangedbetween the Identity Provider and OpenAir Service Provider endpoints.

1. The Identity Provider should provide OpenAir with a copy of their service metadata, or a URL atwhich we can access it.

2. You can download or import the OpenAir SAML metadata from the following URLs:

■ Sandbox account — https://auth.sandbox.openair.com/sso/metadata

■ Production — https://auth.openair.com/sso/metadata

The assertion consumer service URLs (or endpoints) are:

■ Sandbox account — https://auth.sandbox.openair.com/sso

■ Production account — https://auth.openair.com/sso


https://auth.sandbox.openair.com/sso/metadata

https://auth.openair.com/sso/metadata

Provider Integration Setup 2

Important: OpenAir’s new identity authentication service is enabled in all OpenAirenvironments. You must update the configuration of your Identity Provider to use theSAML metadata and endpoint for the new identity authentication service prior to themigration to Oracle Cloud Infrastructure (OCI).

■ The legacy SAML metadata and endpoint URLs will continue to be supported inProduction until your account is migrated to OCI:

□ Legacy SAML metadata — https://www.openair.com/saml.pl?o=B

□ Legacy endpoint URL — https://www.openair.com/saml.pl?o=P

■ Until your SAML is updated to use the new endpoint, users accessing OpenAir withSingle Sign-on should navigate to https://www.openair.com/index.pl?_sso=1or click the Legacy SSO users can login here link on the OpenAir login page to accessthe legacy endpoint.

3. Integration testing should be performed in a sandbox server account. You should plan to providean active SAML identity provider instance for our sandbox integration, for future support andtroubleshooting.

4. The Identity Provider must support Redirect/POST SSO assertions as the default exchangemethod. All assertions must be signed. SAML assertion encryption is optional, but recommended.

5. Some custom configuration may be required for specific Identity Provider product. Refer to yourvendor documentation for details.

This guide describes the custom configuration requirements for the following Identity Provider products:

■ Microsoft Active Directory Federation Service 3.0

■ Microsoft Azure AD

Note: Make sure the Identity Provider has created a Service Provider profile using OpenAir SAMLmetadata before following these custom configuration steps.

Note: All configuration steps described below use the SAML metadata and endpoint for thenew OpenAir identity authentication service. Make sure the Identity Provider has created a ServiceProvider profile using OpenAir SAML metadata before following these custom configuration steps.

Important: The configuration steps for specific Identity Provider products are given forillustration purposes only. OpenAir does not support specific Identity Provider products orproduct versions. Refer to the vendor documentation for detailed and updated instructions aboutyour Identity Provider product.

The Identity Provider product must support SAML 2.0 and allow custom assertions in order to beused with the OpenAir SAML integration. The attributes NameID and account_nickname mustbe included in the SAML assertion. See Identity Provider Setup.

Microsoft Active Directory Federation Service 3.0Follow these steps to set up Microsoft Active Directory Federation Service (AD FS) 3.0 SSO to OpenAir:

1. Make sure that you have installed the following patches on your AD FS server:


https://www.openair.com/saml.pl?o=B

https://www.openair.com/index.pl?_sso=1


■ Windows Server 2008 — KB2896713

This patch fixes a problem which appeared in KB2843638, when error message MSIS0038(SAML Message has wrong signature) would appear even for correct signatures.

■ Windows Server 2012 (R2) — KB3003381

This patch fixes the incorrect MSIS0038 error reported in AD FS 2.0 and AD FS 3.0

2. Install AD FS 3.0 on Windows Server.

3. Download the AD FS Metadata XML from the following location:

https://<your_federation_server_name>/federationmetadata/2007–06/federationmetadata.xml

4. In AD FS 3.0, open the Add Relying Party Trust Wizard. Click Start.

5. On the “Select Data Source” step, select “Import data about the relying party published onlineor on a local network,” and enter one of the following in the “Federation metadata address (hostname or URL)” field

https://auth.sandbox.openair.com/sso/metadata (Sandbox metadata for testing)

https://auth.openair.com/sso/metadata (Production metadata)

Note: This procedure uses the Sandbox metadata in its examples. To set up AD FS inProduction, replace the references to the Sandbox URLs with the Production URLs.

Click Next.

6. Click OK when the following warning appears:

“AD FS Management: Some of the content in the federation metadata was skipped because it isnot supported by AD FS. Review the properties of the trust carefully before you save the trust tothe AD FS configuration database.”

7. On the “Specify Display Name” step, enter a name for the Relying Party Trust in the “Display name”field. Click Next.

8. On the “Configure Multi-factor Authentication Now?” step, select “I do not want to configure multi-factor authentication settings for this relying party trust at this time.” Click Next.



9. On the “Choose Issuance Authorization Rules” step, select the option permitted by your company’spolicies or preferences. Click Next.

10. Click Next on the “Ready to Add Trust” step.

11. On the “Finish” step, clear the “Open the Edit Claim Rules dialog...” option and click Close on the“Finish” step.

12. Go to the “Relying Party Trusts” menu in AD FS, right-click the Relying Party Trust name youentered in step 7, and click “Properties”.

13. Click the “Monitoring” tab and clear the “Monitor relying party” option. Click Apply.

14. In the “Encryption” tab, click Remove and click Yes in the confirmation message.

15. In the “Signature” tab, confirm that a certificate still appears in the list.

16. In the “Identifiers” tab, confirm that the https://auth.sandbox.openair.com/sso/metadata link appears, enter the following into the “Relying party identifier” field, and click Add:

https://auth.sandbox.openair.com/sso

17. Click OK to close the Properties.

You will now need to create claim rules for your account’s Company ID and NameID or User Name. Thefollowing steps set up examples of these Claim Rules. Please note that your company’s specific claim rulesmay appear differently depending on what you use for Name ID or Company ID. See Identity ProviderSetup for more details.

Set Up a Claim Rule Using E-mail Address as NameID

1. Go to the “Relying Party Trusts” menu in AD FS and right click the OpenAir Relying Party Trust. ClickEdit Claim Rules....



2. Click Add rule...

3. In the “Choose Rule Type” step, select “Send LDAP Attributes as Claims” for the “Claim ruletemplate”. Click Next.

4. In the “Configure Claim Rule” step:

■ Enter a name for the rule in the “Claim rule name” field.

■ Select “Active Directory” from the “Attribute store” dropdown list.

■ Select “E-Mail-Addresses” in the “LDAP Attribute” list.

■ Select “E-Mail Address” in the Outgoing Claim Type” list.

Click Finish.

Set Up a Claim Rule to Transform an Incoming Claim



3. In the “Choose Rule Type” step, select “Transform an Incoming Claim” for the “Claim rule template”.Click Next.





■ Select “E-Mail Address” in the “Incoming claim type” dropdown list.

■ Select “Name ID” in the “Outgoing claim type” dropdown list.

■ Select “Unspecified” in the “Outgoing name ID format” dropdown list.

■ Select the “Pass through all claim values” radio button.

Click Finish.



Set up a Claim Rule for a Company ID



3. In the “Choose Rule Type” step, select “Send Claims Using a Custom Rule”. Click Next.



■ Enter => issue(Type = “account_nickname”, Value = “testaccount”); in the “Custom rule”field.

Note: You should replace “testaccount” in this example with your company’s accountnickname.

Click Finish.

18. Open a web browser and test your connection at the following address:

https://<your_federation_server_name>/adfs/ls/IdpInitiatedSignOn.aspx



Microsoft Azure AD

Important: SAML SSO can be configured on Microsoft Azure AD Premium only.

The Free and Basic versions of Microsoft Azure AD only support pre-configured attributes in theSAML assertion. It is not possible to rename or add the custom attributes user_nickname andaccount_nickname required by OpenAir Service Provider when using MS Azure AD Free or MSAzure AD Basic.

1. Sign in to the Azure Portal using your Azure Active Directory administrator account.

2. Browse to Azure Active Directory > Enterprise Applications > New application > Non-galleryapplication. The Add your own application pane displays.

3. Enter a Name for the application (e.g. “OpenAir Sandbox” or “OpenAir Production”) and click Add.The Application Overview screen displays.

4. Click Single sign-on on the left hand side pane, and select SAML. The SAML-based sign-onconfiguration screen displays.

5. Enter Basic SAML Configuration settings:

■ Identifier (Entity ID) — Enter one of the following:

□ https://auth.sandbox.openair.com/sso/metadata (Sandbox metadata for testing)

□ https://auth.openair.com/sso/metadata (Production metadata)

■ Reply URL (Assertion Consumer Service URL) — Enter one of the following:

□ https://auth.sandbox.openair.com/sso (Sandbox)

□ https://auth.openair.com/sso (Production)

■ Leave the optional fields Sign on URL and Relay State blank.



6. Add the User Attributes & Claims user_nickname and account_nickname:

a. Click Add new claim.

b. Enter the Name user_nickname.

c. From the Source attribute dropdown, select the source attribute containing the OpenAirUser ID.

d. Click Save. The attribute user_nickname is now listed in the table.

e. Repeat steps a-d for the account_nickname attribute. You may select the source attributecontaining the OpenAir Company ID from the dropdown or type the OpenAir Company IDas a constant.

f. Delete all other attributes & claims that can be deleted.



7. Review the SAML Signing Certificate and download the Metadata XML file. OpenAir CustomerService or Professional Services will need the Metadata XML file to enable the SAML feature orchange the SAML settings on your account.

8. Click Users and groups on the left hand side pane and assign users and group to this SAMLapplication. Azure AD will not issue a token allowing a user to sign into the application unlessAzure AD has granted access to the user. Users may be granted access directly, or through agroup membership. To assign a user or group to your application, click the Assign Users button.Select the user or group you wish to assign, and click the Assign button.

OpenAir Account ConfigurationOpenAir Customer Service or Professional Services can enable the SAML feature on request in yourOpenAir account.

Important: The SAML integration should be tested on a sandbox account first. It will beimplemented on your Production account after it is confirmed to be working as expected on aSandbox account.

After the feature is enabled, the following steps are required:

1. You will need to configure the SAML integration in OpenAir — See SAML integration settingsSAML Integration Settings.

2. You will need to provide the following information:

■ Identity Provider metadata.

■ SAML Identity Provider Entity ID metadata URL (if different from the IdP Entity ID).

In some cases, you may also need to provide:

■ SAML Identity Provider heartbeat URL

3. OpenAir will add your Entity Provider Entity ID to the Circle of Trust. After this is completed, youshould be able to test the SAML integration. See Testing the SAML Integration.


OpenAir Account Configuration 11

4. You will need to create a custom field and enable your employees to login using SAML Single Sign-On. See Enabling Employees to Login Using SAML Single Sign-On.

SAML Integration SettingsThe SAML integration settings form becomes available when the feature is enabled. To view or changethe SAML integration settings for your OpenAir account, go to Administration > Global settings >Integration: SAML Single Sign-On.

The following settings are available on the form:

■ Account Overview:



□ IdP Entity ID — This is set by OpenAir Customer Service or Professional Services when enablingthe SAML feature. The Entity ID is part of the SAML service metadata Identity Provider shouldprovide in order to enable the SAML feature.

□ SP Entity ID — This is OpenAir Service Provider Entity ID. Click the link to fetch the SAML metadatafor OpenAir Service Provider.

■ Active Settings — This section l lets you compare the Active settings for the identity authenticationservice with the SAML configuration for your account. If these settings do not match, an errormessage appears when you go to Administration > Global settings > Integration: SAML Single Sign-On, and setting mismatches are highlighted on the form. To synchronize the settings and update theidentity authentication service data, click Save on the SAML integration form.

Note: The Active settings section is only available if the new identity authentication service isenabled.

■ Security Settings:□ Affiliate ID — If a SAML Affiliation is assigned at the Identity Provider, enter the affiliation ID

included in the Identity Provider assertions. This is not required if the Affiliation ID is the same asthe IdP Entity ID.

■ Protocol Settings□ Enable SP SSO — To use Service Provider initiated Single Sign-On (SP-initiated SSO), check the

Enable SP SSO box.

Note: IdP-initiated SSO is always supported once the SAML is enabled and configured. Ifyou check the Enable SP SSO box, both IdP-initiated and SP-initiated SSO will be supportedfor the OpenAir web application. However, mobile users must use SP-initiated SSO, to loginto OpenAir Mobile apps, if SP SSO is enabled on your OpenAir account.

□ The following options are available only if SP-initiated SSO is enabled:



▬ SP SSO method — Select the default bindings or method to use for Service Provider initiatedSSO requests. The two methods supported are HTTP POST Binding and HTTP Artifact Binding.

▬ SP SSO ForceAuthn— Check this box to include the ForceAuthn flag in Service Providerinitiated requests. ForceAuthn is an optional SAML feature that acts as a signal to the IdentityProvider to require some form of user interaction during the course of handling the request,overriding the usual implicit assumption that it is acceptable to reuse authentication state froman earlier request. The effect depends on the Identity Provider service and configuration.

■ Miscellaneous Settings — Different miscellaneous settings are available depending on whether SP-initiated SSO is enabled:

□ If SP-Initiated SSO is enabled:

▬ Empty login user initiates SP SSO — Check this box to use Service Provider initiated SSO if theUser ID field is empty on the OpenAir login form.

▬ Hide User ID field on OpenAir SSO Login form — Check this box to hide the User ID field onthe OpenAir SSO login form if the valid Company ID is provided.

□ If SP-Initiated SSO is not enabled:

▬ SP-initiated SSO alternate login URL — Enter the URL for the Single Sign-On page users needto be redirected to when attempting to login on the OpenAir default login page. This is also thepage users will be redirected to, if there is no user interaction within a set period.

▬ SP-initiated SSO alternate login text — Enter any message to be displayed on the OpenAirdefault login page.

■ Settings for logout after redirect: By default, the screen Single Sign-on users see after they log outincludes a link to the OpenAir login page. You can change this link using the following settings.

□ Redirect Page — Enter the alternative link URL. The default link URL points to the OpenAir SSOusers login page.

□ Use link from alternate login URL or IdP’s metadata — Check this box to use either the SP-initiated SSO alternate login URL, if specified, or the URL specified in the Identity Providermetadata as the alternative link URL.

□ Redirect Text — Enter an alternative link text. The default link text is “login page”.

Testing the SAML Integration

To test the SAML integration:

1. Go to Administration > Global settings > Integration: SAML Single Sign-On.

2. Click the Tips menu. The Tips menu should include the following test links:

■ Test SP-initiated SSO



■ Test IdP-initiated SSO

3. Click the test links to test your SAML account configuration.

Enabling Employees to Login Using SAML Single Sign-On

To enable employees to login using SAML Single Sign-On:

1. In OpenAir, go to Administration > Global settings > Custom fields.

2. Click the Create button and select New Custom field. The New Custom field form appears.

3. Select ‘Employee’ from the Add a custom field to dropdown list and ‘Checkbox’ from the Type offield to add dropdown list. Click Continue.

4. Enter the Field name saml_auth, check the Active box, enter the Display name SAMLAuthentication. Enter a Description and Hint if required. Click Save.

Important: The Field name must be set to saml_auth.

5. Go to Administration > Global settings > Employees > [Select an Employee]. The EmployeeDemographic form should now include the SAML Authentication Checkbox.

6. To enable SAML Authentication for an employee, check the SAML Authentication box on theemployee demographic form.



Important: After you have enabled SAML Authentication for an employee, thisemployee will no longer be able to use the standard password authentication method toaccess OpenAir. Make sure you keep the SAML Authentication disabled for at least oneadministrator account for troubleshooting purposes.

Tip: You can use the bulk employee change wizard to copy the value of the saml_authfield to other user records on your OpenAir Account.

See OpenAir Admin Guide under Home > Home > Wizards.

OpenAir Mobile Apps and SAML2OpenAir Mobile Apps, including OpenAir Mobile for iPhone and OpenAir Mobile for Android, supportSAML Single Sign-On. Both Service Provider initiated Single Sign-On (SP-initiated SSO) and IdentityProvider initiated Single Sign-On (IdP-initiated SSO) are supported.


https://www.openair.com/download/OpenAirAdminGuide.pdf

Documents

SAML 2 Quick Start Guide · products, and services from third parties. Oracle Corporation and its affiliates are not responsible for and expressly disclaim all warranties of any kind