In Part 1, About Desktop SSO using Azure AD, IDCS, and the App Gateway, I covered a high-level explanation on how this solution works including important decisions needed to deploy the App Gateway.  If you have not read Part 1, please do so before continuing with this article.   In Part 2 I provide concise steps on how to implement the solution, so let’s cut out the small talk and jump into it because there is a lot to cover. 

STEP 1 – Oracle App Gateway – Download, Deploy, and Configure

This section contains basic on deploying the App Gateway, and any details not outlined I provide official Oracle documentation references.   The App Gateway can be deployed either in the cloud or on-premises, that is your choice based on the architecture you choose. 

Pre-requisites

Please do not skip this section.  The following is a high-level list of requirements required before moving on to the next section of steps.  

1. IDCS version 19.2.1 or higher; click on the About in your tenant to verify.
2. Oracle Virtualbox – Download and install.
3. A Microsoft Azure account that is a Global Administrator member.
4. An Oracle Identity Cloud Service account that is a member of IDCS_Administrators group.
5. At least one user account in both IDCS and Azure AD that has the same email address.
6. HTTP Application Resource – Ready to protect and require the hostname, port, and uri for later; alternatively, this could also be a load balancer that points to the HTTP resource.

STEP 1.1 – Download the App Gateway (requires IDCS 19.2.1 or higher)

This section provides high-level steps to getting the App Gateway and deploying it, but the details on how to deploy the App Gateway can be found in the provided links.

1. Sign in to IDCS console (https://idcs-<guid>.identity.oraclecloud.com/ui/v1/adminconsole) as an administrator.
2. Select the Menu (top left hamburger button) > Settings > Downloads > and download the App Gateway for Identity Cloud Service.
3. Deploy the App Gateway to your choice of virtual server whether that be in the cloud or on-premises; follow the steps in the documentation to host the virtual appliance.

STEP 1.3 – Register the App Gateway in IDCS

This section steps through the process of registering the App Gateway. Be to read Part 1 About Desktop SSO using Azure AD, IDCS, and the App Gateway and the App Gateway to be clear what hostnames and ports are required for the front ends of the App Gateway and the web server resource that will be protected.

1. Sign in to IDCS console (https://idcs-<guid>.identity.oraclecloud.com/ui/v1/adminconsole) as an administrator.
2. Select the Menu (top left hamburger button) > Security > App Gateways > click the Add button –– continued in next step.
3. Details – Enter a name in the Name field > click the Next icon  –– continued in next step.
4. Hosts – Click the Add button > enter the following variables and click the Save button –– continued in next step.
   • Host Identifier: <an arbitrary descriptive name>
   • Host: <App Gateway or Load Balancer hostname>
   • Port: <App Gateway or Load Balancer port>
   • SSL Enabled:  <check if adding SSL>
5. Click Finish > copy the Client ID and Client Secret to complete the App Gateway configuration.  An application in the Apps tab will be added later.
6. Activate the new App Gateway by clicking on the Menu (top left hamburger button) > Security > App Gateways > select the hamburger button next to the new App Gateway and select Activate > click OK to confirm.

STEP 1.4 – Create an IDCS Enterprise Application

1. Sign in to IDCS console (https://idcs-<guid>.identity.oraclecloud.com/ui/v1/adminconsole) as an administrator.
2. Select the Menu (top left hamburger button) > Applications > click Add button –– continued in next step.
3. Select Enterprise Application > in Details provide the following required values:
   • Name: <Enter a descriptive name in the Name field>
   • Application URL:  <Enter the fully qualified domain name of App Gateway or load balancer hostname and port; e.g. https://myappgateway.com/>
4. Click the Next icon > complete the Resources and Authentication Policy tabs for the SSO Configuration as follows.
   NOTE: The following configuration is only a minimal example, but your configuration can be different.
   • Add the following in the Resources tab:
     • Resource 1:
       • Resource Name: Root
       • Resource URL: /.*
       • Regex: checked
     • Resource 2:
       • Resource Name: Favicon
       • Resource URL: /favicon.ico
       • Regex: unchecked
   • Add the following in the Authentication Policy tab:
     • Require Secure Cookies:  uncheck if not using HTTPS
     • Managed Resources:
       • Click Add > finish by clicking the Add button
         • Resource: Root
         • Authentication Method: Form or Access Token
         • Headers:  temporarily add a Name and Value
       • Click Add > finish by clicking the Add button
         • Resource:  Favicon
         • Authentication Method:  Public
5. Click the Finish button –– continued in next step.
6. Select the Groups tab > click the Assign button > select the group created earlier > click OK to confirm –– continued in next step.
7. Click on the Activate button to activate the application.

STEP 1.5 – Optional

Users & Groups

1. Sign in to IDCS console (https://idcs -<guid>.identity.oraclecloud.com/ui/v1/adminconsole) as an administrator.
2. Select the Menu (top left hamburger button)
3. Find and select your Enterprise Application
4. Select the Users or Groups tab
5. Click on the Assign button to add user or group to which would grant authorization to your application or protected HTTP resource.

HTTP Headers

1. Sign in to IDCS console (https://idcs-<guid>.identity.oraclecloud.com/ui/v1/adminconsole) as an administrator.
2. Select the Menu (top left hamburger button)
3. Find and select your Enterprise Application
4. Select the SSO Configuration tab
5. Select the Authentication Policy tab

Under the Managed Resources section, you can modify or add a resource and in the Headers section you can add dynamic or hard coded headers.  For example, see the following screenshot as an example.  

STEP 2 – Prepping Microsoft Azure and Oracle Identity Cloud Service

This section provides preparation items for Microsoft Azure AD and Oracle Identity Cloud Service in regard to federation integration.

STEP 2.1 – Create a user account in Azure

1. Sign in to Azure (https://portal.azure.com/) as an administrator
2. Go to or select Azure Active Directory > Users > click on New user and create a user.
   • NOTE: Remember the email address because this will be used in IDCS when the same matching account using that email address is created. The email address is used to map between IDCS and Azure during Federation.

STEP 2.2 – Create a user account in Oracle Identity Cloud Service 

1. Sign in to IDCS (https://idcs-<guid>.identity.oraclecloud.com/ui/v1/adminconsole)  as an administrator.
2. Select the Menu (top left hamburger button) > Users > press Add follow the wizard and use the same email address used in Azure when the user was created in the previous step.

STEP 2.3 – Create a group in Oracle Identity Cloud Service to authorize a protected resource

1. Sign in to IDCS (https://idcs-<guid>.identity.oraclecloud.com/ui/v1/adminconsole) as an administrator.
2. Select the Menu (top left hamburger button) > Groups > press Add > give a name and click Finish.
3. Select the Users tab > press Assign Users > assign the user created in the previous step > press OK.

STEP 3 – Creating the Federation Agreement 

This section steps through creating the federation agreement between Azure AD (IdP) and IDCS (SP).  

STEP 3.1 – Get the IDCS SAML metadata

1. Using a web browser request the SAML metadata from https://idcs-<guid>.identity.oraclecloud.com/fed/v1/.
2. When prompted Sign in to IDCS as an administrator.
3. Download and save the Federated metadata to a file named idcs_sp_metadata.xml.

STEP 3.2 – Setup Federation in Azure

1. Sign in to Azure (https://portal.azure.com/) as an administrator.
2. Create an application by selecting Menu (top left hamburger button) > Azure Active Directory > Enterprise applications > click New application > select Non-gallery application –– continued in next step.
3. In the Add your own application enter a name in the Name field; e.g. Desktop SSO > click the Add button –– continued in next step.
4. Select option 2. Set up single sign on > select SAML > select the tab button on the top called Upload metadata file > select the file/folder icon > choose the idcs_sp_metadata.xml file > click the Open button > click the Add button –– continued in next step.
5. A page ont the right will be presented titled Basic SAML Configuration, enter the following details below > then click the Save button (You should see a confirmation).
   • Sign on URL: https://idcs-<guid>.oraclecloud.com/ui/v1/myconsole
   • Relay State: <leave blank>
   • Logout Url: <leave blank>
6. You can verify the previous SAML setup by clicking on the blue Test button at the bottom of the SAML-based Sign-on page.  Choose either Sign in as current user or Sign in as someone else to test.  Be sure the account in Azure also has an account in IDCS with the same matching email address used in Azure.
7. On the page in Azure titled SAML-based Sign-on click the download link next to Federation Metadata XML and either note the name or rename it azure_idp_metadata.xml.  Use this metadata in the next federation setup in IDCS.

STEP 3.3 – Assign Access to the Azure Enterprise Application

Before we finish with Azure AD we have to assign a test user that exists in both Azure AD and IDCS to have access to the enterprise application that was created earlier. 

1. Sign in to Azure (https://portal.azure.com/) as an administrator.
2. Select Menu (top left hamburger button) > Azure Active Directory > Enterprise applications > now select the application we created earlier; e.g. Desktop SSO.
3. Select 1. Assign users and groups > click the Add user button > select the Users and groups link > select the test user that exists in both Azure and IDCS > click the Select button > finish by clicking the Assign button.

STEP 3.4 – Setup IDCS Federation and add an IDP

1. Sign in to IDCS (https://idcs-<guid>.identity.oraclecloud.com/ui/v1/adminconsole) as an administrator.
2. Select the Menu (top left hamburger button) > Security > click Identity Providers > click Add SAML IDP > start the wizard –– continued in next step.
3. In the Details tab enter an Identity Provider name in the Name field and optionally a description; e.g. Azure > click Next –– continued in next step.
4. In the Configure tab click the upload button > select the file azure_idp_metadata.xml from earlier > click the Open button> leave the default Signature Hashing Algorithm to SHA-256, and leave Include Signing Certificate unchecked  > click the Next button –– continued in next step.
5. In the Map tab leave the default value for Identity Provider User Attribute as Name ID > change the option for Oracle Identity Cloud Service User Attribute to Primary Email Address > leave the default value for Requested NameID Format to <None Requested> > click the Next button –– continued in next step.
6. In the Export tab click the Next button to continue.
7. In the Test tab click the Test Login button to verify Federation works –– continued in next step.
8. Finish by clicking the Activate button.

Testing

Validating the SSO is not too exciting because if everything is configured properly simply requesting the HTTP resource using the Edge browser should get you to the resource without being prompted for a login.  The following are a couple of pretty simple steps to validate this implementation.  

1. Using Microsoft Edge browser request the HTTP resource protected by the App Gateway.
2. Your request should go directly to the HTTP resource without being prompted.

Troubleshooting 

If you are prompted for a username and password then obviously something is not correct.  I highly recommend turning on development tools in say Chrome, then preserving logs and using the Network tab to capture a HTTP trace.  There are a couple key authentication protocols responsible for authentication that IDCS and App Gateway use, SAML2 and OAuth2, which each should be investigated.  Refer to my Part 1 About Desktop SSO using Azure AD, IDCS, and the App Gateway article to help analyze the flow in comparison to the HTTP trace.  You can even save the HTTP trace as a HTTP Archive (HAR) and use a HAR Viewer to try and identify issues.  Another tool to troubleshoot SAML2 issues is the SAML-Tracer browser extension or add-in for Google Chrome or Firefox that can help determine any problems with federation. 

Summary

If everything was implemented correctly you should now have a way to desktop SSO to a HTTP resource without being prompted to login.  In addition, HTTP headers can be sent down stream to the target web application for various reasons including trusted header SSO authentication if supported.  If you are on IDCS release 19.3.3.x or higher, another feature was added to Enterprise Applications in the SSO Configuration tab called Authorization Policy in which you can also add more rules that can contain conditions and actions such as HTTP methods, allow group members, accept only certain IP address ranges, date and time ranges, and allowed headers.  The only thing this article left out which is important is a way to provision users and groups into IDCS, and there are more than one way to do this.  One would be to use the IDCS AD Bridge, and the details for that are in this section 16 Manage Microsoft Active Directory (AD) Bridges for Oracle Identity Cloud Service of the official Oracle documentation. There are others, but this should be a start.  Hopefully this solution provides a foundation to desktop SSO use cases that can be used as is or expanded for your specific needs. Enjoy!