Configure Active Directory Federation Services for Windows 2016 as OpenId Provider

Disclaimer: Microsoft Active Directory Federation Services (ADFS) is a product offered by Microsoft Corporation. This document shows how to configure applications in ADFS for Windows 2016 using the tools provided by the vendor. What is shown here is valid at the time of writing and can be referred to as a guideline to understand how applications should be setup in ADFS. This can change over time. Please refer to the latest ADFS documentation for more up to date information.

Adding IFS Applications to ADFS for Windows 2016
- Configuration with one single application group (needed for CRM panel)
IFS Admin Console configurations
Mapping the AD user to Foundation1 user

Adding IFS Applications to ADFS for Windows Server 2016

The applications that need to be authenticated using Active Directory Federation Services have to be registered and configured in ADFS for Windows 2016. This is performed using the tools provided by ADFS.

NOTE: How to configure the Active Directory user registry and how to enable and configure Active Directory Federation Services for the AD is outside the scope of this documentation.

NOTE: Once you have installed ADFS service you can test it using ADFS test application. First the test application has to be enabled using the ADFS property EnableIdpInitiatedSignonPage. Open a Power Shell in Administrator mode and issue the command Set-AdfsProperties –EnableIdpInitiatedSignonPage $True. Then from Internet Explorer open the web page https://>adfs_service_url</adfs/ls/idpinitiatedsignon.aspx. This page will give you several options to test signing in to ADFS. If these sign in tests are successful that means your ADFS service is properly installed.

Aurena Default Application

Login to the Windows 2016 server where the ADFS is installed using the Domain Administrator Credentials. Launch AD FS Management tool. Click on "Application Groups". Click "Add Application Group...".

adfs1

Give a name to your application group and select "Server application". Click "Next".

adfs2

Note down the value given in the field "Client Identifier". This is required later when authentication configuration is completed using IFS Admin Console. Add the following Redirect URIs for Aurena Application.

https://<fully_qualified_domain_name_of_the_app_server:port>main/ifsapplications/projection/oauth2/callback/
https://<fully_qualified_domain_name_of_the_app_server:port>/main/ifsapplications/web/oauth2/callback/

E:g:

https://lkppdeTest888.corpnet.ifsworld.com:58080/main/ifsapplications/projection/oauth2/callback/
https://lkppdeTest888.corpnet.ifsworld.com:58080/main/ifsapplications/web/oauth2/callback/

Note the trailing slashes at the end. This is important.

adfs3

Click "Next". Select check box "Generate a shared secret". Copy the value given in the field "Secret". This is required when authentication configuration is completed using the IFS Admin Console.

adfs4

Click "Next" and finish the configuration.
From the application groups select the application group just created. click "Add application..".

adfs5

Select "Web API"

adfs6

Give an Identifier. For documentation purposes giving the application server URL as the identifier is a good idea.
Press next and leave "Permit everyone" as the selection.
Press next and make sure the selection is "openid".

adfs7

Press next and finish the configuration.

Aurena B2B Application

To authenticate user login for B2B client follow the above procedure and create a separate application group. Add the following Redirect URIs. If a separate application group is not required the same application group as Aurena can be used with the following set of Redirect URIs added.

https//:<fully_qualified_domain_name_of_the_app_server:port>/b2b/ifsapplications/projection/oauth2/callback/
https://<fully_qualified_domain_name_of_the_app_server:port>/b2b/ifsapplications/web/oauth2/callback/

E.g.:

https://example.com:58080/b2b/ifsapplications/projection/oauth2/callback/

Note the trailing slashes at the end. This is important.

If a separate application group is created take a note of the Application ID and the Secret key of the B2B application as this is required later to finish configuring authentication for IFS Applications using the IFS Admin Console.

IFS Enterprise Explorer and Touch Apps

IFS Enterprise Explorer

To authenticate user logins for IFS Enterprise Explorer add the following application group in ADFS.
Go to "Add Application Group.." give a name and select "Native application"

adfs8

Note down the Client Identifier as this is required later when authentication configuration is completed using the IFS Admin Console. Enter the following redirect URIs.

<https://fully_qualified_domain_name_of_the_app_server:port>/int/default/plsqlgateway/oauth2/callback
<https://fully_qualified_domain_name_of_the_app_server:port>/int/default/clientgateway/oauth2/callback
<https://fully_qualified_domain_name_of_the_app_server:port>/main/default/plsqlgateway/oauth2/callback
<https://fully_qualified_domain_name_of_the_app_server:port>/main/default/clientgateway/oauth2/callback

E:g:
https://example.com:58080/int/default/plsqlgateway/oauth2/callback
https://example.com:58080/int/default/clientgateway/oauth2/callback
https://example.com:58080/main/default/plsqlgateway/oauth2/callback
https://example.com:58080/main/default/clientgateway/oauth2/callback

Note the lack of trailing slashes at the end. This is important.

adfs9

Press next and finish application configuration.
Select the newly created application group and click on "Add application". Select the "Web API".

adfs10

Press next. In the Identifier field enter the following: api://<INSTANCE_NAME>. Make sure to follow this exact format as this is the accepted format of the resource id that is required. The INSTANCE_NAME here is the instance name given for the IFS Application instance.

E.g.: api://PROD_INSTANCE

adfs18

Press next and select "Permit everyone".
Press next and select both "openid" and "user_impersonation" scopes.

adfs12

Press next and finish application configuration.
Select the newly created web application from the application group and press "Edit".

adfs13

Select the tab "Issuance Transform Rules". Select "Add Rule". From the drop down select "Send claims Using a Custom Rule" and press next.

adfs14

Add the following claims:

Claim rule name	Custom rule
Issue open id scope	=> issue(Type = "http://schemas.microsoft.com/identity/claims/scope", Value = "openid");
Issue user_impersonation scope	=> issue(Type = "http://schemas.microsoft.com/identity/claims/scope", Value = "user_impersonation");

Add another rule. Pick "Send LDAP Attributes as Claims".

Selecting LDAP attributes as claims

Pick sending "User-Principal-Name" as "UPN" as shown below.

Setup of UPN claim rule

NOTE: Re-authentication behavior: When the user logs in and work in IFS Enterprise Explorer client the client session is refreshed based on the session timeout (Default 10 minutes). When the current session times out the Access Token given by the ADFS server is used to refresh the client session. The Access Token is has a lifetime of about 1 hour by default. Once the Access Token is expired the Refresh token given by the ADFS server is used to obtain a new Access Token. This Refresh token has a lifetime of about 7 days according to ADFS documentation. Once the Refresh token is expired it will not be possible to get any new Access Tokens. So re-authentication will fail and the user will be prompted for credentials.

Touch Apps Server and Touch Apps

The Touch Apps Server and the Touch Apps are also accessed through the Native application that was created for IFS Enterprise Explorer above. Redirect URIs must be added for the Touch Apps Server and for each individual Touch App to this same native application.

Please refer Touch Apps Server Configuration for Redirect URIs for more information

Configuration with one single application group (needed for CRM panel)

If some addons are used with IFS, the below instructions need to be done slightly differently. It is possible to configure this using a single application group if you need the Web Client to be able to access the resource defined for the native client. The way this is done is very similar to how it is done with two application groups. A known use-case where this alternate setup is needed is if the CRM Panel is to be used with ADFS.

The difference is that in this case the Web API and the Native Client Application would be created in the same application group as the Server Application that was created for Aurena is in. Aside from that, the setup is the same. For applications that do not need such a setup, it has no consequence whether or not it is set up this way or with two application groups.

IFS Middleware Server Admin Console configurations

After the applications are added to ADFS as explained in the above section some configurations are needed in IFS Middleware Server Admin Console to finish setting up the IFS Application to use ADFS as the Open Identity Provider.
Login to IFS Admin Console. Go to "Common > Security".
The DEFAULT tab holds the Open ID provider configuration details for Aurena client. Select "ADFS (Windows Server 2016)" as the Identity Provider. Fill in the details as show below.

Parameter Value

Identity Provider ADFS (Windows Server 2016)

Identity Provider URL ADFS Service URL.
Note: In order to find the URL to use here open a power shell in the server where ADFS is installed and type Get-ADFSProperties. HostName and HttpsPort properties are the values that should be used to construct this URL.

Acceptable Clock Skew (seconds) This will be the tolerated amount of clock skew when the validity of the token is calculated. E.g.: 60s

Client ID (web) Client Identifier taken from ADFS application registration when Aurena Web application was registered.

Client Secret (web): Security Key generated when Aurena Web application was registered in ADFS

Client ID (native): Client Identifier taken from ADFS application registration when IFS Enterprise Explorer and Touch apps were registered as a Native application.

Parameter	Value
Identity Provider	ADFS (Windows Server 2016)
Identity Provider URL	ADFS Service URL. Note: In order to find the URL to use here open a power shell in the server where ADFS is installed and type Get-ADFSProperties. HostName and HttpsPort properties are the values that should be used to construct this URL.
Acceptable Clock Skew (seconds)	This will be the tolerated amount of clock skew when the validity of the token is calculated. E.g.: 60s
Client ID (web)	Client Identifier taken from ADFS application registration when Aurena Web application was registered.
Client Secret (web):	Security Key generated when Aurena Web application was registered in ADFS
Client ID (native):	Client Identifier taken from ADFS application registration when IFS Enterprise Explorer and Touch apps were registered as a Native application.

adfs16

The B2B tab holds the Open ID provider configuration details for B2B client. Select "ADFS (Windows Server 2016)" as the Identity Provider. Fill in the details as shown below.

Parameter Value

Identity Provider ADFS (Windows Server 2016)"

Identity Provider URL ADFS Service URL.
Note: In order to find the URL to use here open a power shell in the server where ADFS is installed and type Get-ADFSProperties. HostName and HttpsPort properties are the values that should be used to construct this URL.

Acceptable Clock Skew (seconds) This will be the tolerated amount of clock skew when the validity of the token is calculated. E.g.: 60s

Client ID (web) Client Identifier taken from ADFS application registration when B2B Web application was registered. If a separate application was registered for B2B use that Client Identifier. Otherwise same client ID as the Aurena application must be entered.

Client Secret (web): Security Key generated when B2B Web application was registered in ADFS. Use the same Client secret as Aurena if the same web application registration is used.

Client ID (native): Leave this blank as there is no native application for B2B.

Parameter	Value
Identity Provider	ADFS (Windows Server 2016)"
Identity Provider URL	ADFS Service URL. Note: In order to find the URL to use here open a power shell in the server where ADFS is installed and type Get-ADFSProperties. HostName and HttpsPort properties are the values that should be used to construct this URL.
Acceptable Clock Skew (seconds)	This will be the tolerated amount of clock skew when the validity of the token is calculated. E.g.: 60s
Client ID (web)	Client Identifier taken from ADFS application registration when B2B Web application was registered. If a separate application was registered for B2B use that Client Identifier. Otherwise same client ID as the Aurena application must be entered.
Client Secret (web):	Security Key generated when B2B Web application was registered in ADFS. Use the same Client secret as Aurena if the same web application registration is used.
Client ID (native):	Leave this blank as there is no native application for B2B.

adfs17

Mapping the ADFS user to Foundation1 user

IFS Applications have a user registry of its own in the Oracle Database. These users are know as Foundation1 Users. A user authenticated from an External Identity Provider such as ADFS needs to be mapped to a Foundation1 user for him to get access (authorization) to the application. This can be done through Solution Manager by changing the DIRECTORY_ID (also known as WEB_USER) value of your Foundation1 users.

The DIRECTORY_ID is used for the mapping between the external user identity in the Identity Provider and the Foundation1 user identity.

When ADFS is used as the user repository the UserPrincipleName of the Active Directory user must be the value that should be entered as the value for DIRECTORY_ID(WEB_USER) field. This should be entered in upper case.

NOTE: Solution Manager can be launched through the IFS Applications Admin Landing Page -> IFS Enterprise Explorer Admin. IFS Enterprise Explorer Admin uses DB Authentication always even when some other identity provider is configured for end user Authentication. Please refer Admin landing page for more information

It is possible to use Active Directory Synchronization to map the AD users to Foundation1 users.