Micro Focus Content Manager SDK 10.1
Open ID Connect Authentication

Table of Contents

Authentication overview

OAuth authentication is managed via OpenId Connect authentication. The authentication is configured in yout Identity Provider (e.g. Azure AD) and then the appropriate details are stored in Content Manager in the hptrim.config file, for the Web Client and ServiceAPI or Enterprise Studio for the desktop client.

ADFS for Native client

As of CM 10 the CM web applications (ServiceAPI, WebDrawer and Web Client) have an OpenId Connect authentication provider built in. This document describes creating an AD FS application and configuring the Windows native Content Manager client.

Configure ADFS

Follow the steps below to setup ADFS to support OpenID for Content Manager native.

Log on to your ADFS Server and create an application group.

Name the group

Provide a Name and Description, then select native Application. Click on the next button.

Configure the group

Store the client identifier somewhere for later and enter the value ‘urn:ietf:wg:oauth:2.0:oob’ then click on the add button, then select next.

Review the settings and select Next

Modify application group properties

Once this has been completed right click the application group and select properties.

Add application

Click Add Application

Select Web API

Configure the Web API

Add the Redirect to be the same as the client ID of the Native application that you previously copied again then click next .

Select an appropriate Access control Policy

Set scopes

Select the Native Application and ensure email, openid and profile are checked.

Review the configuration and select next, then close.

Set issuance rules

Right click the app group and select properties, highlight the WEB API application and select edit.

Add rule

Navigate to the issuance Transform Rules Tab and click Add Rule

Map attributes

Give the rule a Name, Select Active Directory as the Attribute Store, and add the following mapping of LDAP attributes:

  • E-Mail-Addresses -> E-mail Address
  • User-Principal-Name -> UPN
  • Then select ‘OK’

Configure Content Manager

Navigate to the content Manager server and run Trim Enterprise Studio as an Administrator Highlight the dataset and select "Authentication"

Configure OpenId settings

Enter the ADFS url for the ADFS server, the client ID which was stored from early on (Native Application) then click test.

Enter the user details for a test user and click Sign in.

The users email in active directory should appear if successful.

ADFS for WebClient and ServiceAPI

As of CM 10 the CM web applications (ServiceAPI, WebDrawer and Web Client) have an OpenId Connect authentication provider built in. This document describes creating an AD FS application and configuring the CM web application.

Create the AD FS Application

To create the AD FS application:

  1. create a new Application Group
  2. select 'server application accessing a web application'
  3. Enter a name.
  4. press Next
  5. take note of the client identifier
  6. add a Redirect URI. The redirect URI must be all in lowercase and be the URL of the Content Manager web site with the suffix '/serviceapi/auth/openid. For example: https://myserver/contentmanager/serviceapi/auth/openid.
  7. press Next
  8. Generate a shared secret and take note of this secret
  9. press next
  10. add an identifier, for example: https://MyServer/contentmanager/
  11. press next
  12. choose an access control policy (for example: 'Give access to everyone
  13. In 'Configure Application permissions select email, openid, and profile
  14. Complete the Application Group

Examples

New AD FS application

Add Redirect URI

Generate Secret

Specify Web API identifier

Add the settings to the Web Client

To configure the Web Client edit the hprmServiceApi.config file and add (or edit) the authentication element to look similar to the example below.

  • Client Id and secret come from the previous section
  • issuerUri is found in the AD FS console - Endpoints, in the OpenID Connect section
  • name must be 'openid'

Example

<authentication allowAnonymous="false" slidingSessionMinutes="30">
<openIdConnect>
<add
name="openid"
clientID="CLIENT_ID"
clientSecret="SECRET"
issuerURI="https://MyServer/adfs/.well-known/openid-configuration"/>
</openIdConnect>
</authentication>

Configure AD FS for Office Integration access

The office integration requires an access token to allow it ro authenticate with the Web Client, this can be configured in AD FS:

  1. go the Application group configured above
  2. use 'Add Application' to add a native application
  3. preserve Client Id for later use
  4. complete the native application
  5. edit the Web API application and in Client Permissions add the new client application selecting the scopes email, openid and profile
  6. in Issuance Transform Rules add a new Rule
  7. select 'Send LDAP Attributes'
  8. select Next
  9. choose Active Directory as the attribute store
  10. map these two claims,
    • Display Name - Name
    • User-Principal-Name - UPN
  11. Finish

Examples

Add native application

Add permissions for native application

Specifiy claims to be included in token

Add office integration the settings to the Web Client

The office integration authentication settings are stored in the file ADFS\config.xml in the web client install directory:

  • clientAuthority - the URL to your AD FS server
  • clientResourceUri - the relying party identifier from the AD Fs Web API
  • clientID - the Client Id from the AD FS native application
  • The Redirect URI from the AD FS native application
<adfsClient>
<clientAuthority>https://acme.com/adfs</clientAuthority>
<clientResourceUri>https://acme.com/contentmanager/</clientResourceUri>
<clientID>ab762716-544d-4aeb-a526-687b73838a34</clientID>
<clientReturnUri>https://acme.com/contentmanager/</clientReturnUri>
</adfsClient>

AzureAD for WebClient/Mobile App and ServiceAPI

As of CM 10 the CM web applications (ServiceAPI, WebDrawer and Web Client) have an OpenId Connect authentication provider built in. This document describes creating an Azure Ad application and configuring the CM web application. This document also details the steps required to allow the Content Manager mobile app to authenticate.

Create the Azure AD Application

To create the Azure AD application:

  1. From with portal.azure.com go to Azure AD.
  2. Go to App Registrations and select New Registration.
  3. Enter a name.
  4. Under Redirect URI leave Web selected.
  5. The value in the Redirect URI is important, it must be lowercase and it must be the URL to your application (e.g. https://mydomain.com/cmwebdrawer) followed by the path to the authentication provider (for example /auth/openid). The /auth/ component is fixed but the 'openid' is the name you will supply in hptrim.config later and so can be any string, as long as it matches the value in hptrim.config. For the web client the path must include the path to the ServiceAPI, for example: https://mydomain.com/contentManager/serviceapi/auth/openid.

Example

Add a secret

From Certificates and Secrets add a secret and copy it some where you can find it later.

Example

Configure Tokens

From the Authentication section go to 'Select the tokens you would like to be issued' and check the option ID Tokens.

Configure permissions

From API Permissions add the following delegated Microsoft Graph permissions:

  • email
  • offline_access
  • openid
  • profile
  • User.Read
  • Files.Read
  • Files.Read.All
  • Files.ReadWrite
  • Sites.Read.All
  • Sites.ReadWrite.All
  • User.Read

Select 'Grant Admin Access' to grant access to all permissions.

Example

Configure for mobile

Add the mobile redirect URI

If this Azure app is to be used to connect the Content Manager mobile app then:

  1. go to the Authentication section,
  2. select 'Add a platform',
  3. choose 'Mobile and desktop applications, and
  4. put trimapp://mobile in the 'Custom Redirect URIs' field.

Add the mobile redirect URI to the ServiceAPI

The redirect URI set above must be included in the ServiceAPI hptrim.config. To do this add a section similar to the one below inside the element authentication/opnIdConnect:

<add name="mobile"
clientID="[CLIENT ID from Azure App]"
clientSecret="[SECRET from Azure APP]"
issuerURI="[OpenID Connect metadata document from endpoints in Azure App]"
redirectUri="trimapp://mobile" />

Configure authentication in hptrim.config

To use the Azure AD app created above edit hptrim.config (hprmServiceAPI.config in the Web Client) so that it has am authentication similar to the one below.

  1. The name must match the last segment of the Redirect URI path.
  2. Client ID is the application ID from the Azure Ad Overview.
  3. The secret is the one saved when creating the App. If it was not saved created a new one in Certificates and Secrets.
  4. Get the issuerUri from Overview > Endpoints > OpenID Connect metadata document

Example config

<authentication allowAnonymous="false" slidingSessionMinutes="60">
<openIdConnect>
<add
name="openid"
clientID="ae39011d-52e7-4ecc-b9eb-87d6d876dd"
clientSecret="_MqXXXXXXXXXXXXXXXG[sp3GrMfD:"
issuerURI="https://login.microsoftonline.com/08363ee4-6592-4325-9d5a-123456789/v2.0/.well-known/openid-configuration"
/>
</openIdConnect>
</authentication>

Enable redirect

The web client will not re-direct the authentication endpoint unless the Html feature is enabled in hprmServiceAPI.config. To do this:

  1. edit hprmServiceAPI.config
  2. find the property named 'serviceFeatures'
  3. Add the feature Html

Allow users (Web Client only)

For the Web Client find the web.config file and wuthin it find the Location element with the path "serviceapi", it should contain the element <allow users="*" /> within its authorization element.

Example

<location path="serviceapi">
<system.web>
<httpHandlers>
<add path="*" type="ServiceStack.WebHost.Endpoints.ServiceStackHttpHandlerFactory, ServiceStack" verb="*" />
</httpHandlers>
<authorization>
<allow users="*" />
</authorization>
</system.web>
...
</location>

Logout

For WebDrawer the logout link is configured in the uiSettings. It should contain '~/auth/logout'. In the Web Client a logout link will be displayed automatically when OpenId Connect authentication is enabled.

Example

<uiSettings
logoutLink="~/auth/logout"
...
/>

Allow anonymous access in IIS

IIS will not be handling authentication so we use IIS Manager to allow anonymous access only.

Google authentication for WebClient and ServiceAPI

As of CM 10 the CM web applications (ServiceAPI, WebDrawer and Web Client) have an OpenId Connect authentication provider built in. This document describes creating Google credentials and configuring the CM web application.

Create the Google Credentials

To create the Google credentials:

  1. Go to https://console.developers.google.com/,
  2. Select Credentials > OAuth Client ID,
  3. Set Application type to 'Web Application'.
  4. Add your domain in the Authorized JavaScript origins
  5. The value in Authorized redirect URIs is important, it must be lowercase and it must be the URL to your application (e.g. https://mydomain.com/cmwebdrawer) followed by the path to the authentication provider (for example /auth/openid). The /auth/ component is fixed but the 'openid' is the name you will supply in hptrim.config later and so can be any string, as long as it matches the value in hptrim.config. For the web client the path must include the path to the ServiceAPI, for example: https://mydomain.com/contentManager/serviceapi/auth/openid.
  6. On saving the Client ID and Client Secret will be displayed, preserve them for later use.

Example

Configure authentication in hptrim.config

To use the Google credentials created above edit hptrim.config (hprmServiceAPI.config in the Web Client) so that it has am authentication similar to the one below.

  1. The name must match the last segment of the Redirect URI path.
  2. Client ID is the one preserved earlier.
  3. The secret is the one preserved earlier.
  4. The issuerURI is: https://accounts.google.com

Example config

<authentication allowAnonymous="false" slidingSessionMinutes="2">
<openIdConnect>
<add
name="openid"
clientID="741419278958-abcdefghijklmemopqrs.apps.googleusercontent.com"
clientSecret="jl-BiX7685hjgf76857y"
issuerURI="https://accounts.google.com"
/>
</openIdConnect>
</authentication>

Enable redirect

The web client will not re-direct the authentication endpoint unless the Html feature is enabled in hprmServiceAPI.config. To do this:

  1. edit hprmServiceAPI.config
  2. find the property named 'serviceFeatures'
  3. Add the feature Html

Logout

For WebDrawer the logout link is configured in the uiSettings. It should contain '~/auth/logout'. In the Web Client a logout link will be displayed automatically when OpenId Connect authentication is enabled.

Example

<uiSettings
logoutLink="~/auth/logout"
...
/>

Allow anonymous access in the IIS

IIS will not be handling authentication so we use IIS Manager to allow anonymous access only.

AzureAD for Content Manager Desktop

OpenID Connect may be used to authenticate with the Content Manager desktop client, this document details how to configure this.

Create the Azure AD Application

To create the Azure AD application:

  1. From with portal.azure.com go to Azure AD.
  2. Go to App Registrations and select New Registration.
  3. Enter a name.
  4. Select 'Public native client' in the Redirect URI
  5. Enter this redirect Uri 'urn:ietf:wg:oauth:2.0:oob'

Example

Configure permissions

From API Permissions add the following delegated Microsoft Graph permissions:

  • email
  • offline_access
  • openid
  • profile
  • User.Read
  • Files.Read
  • Files.Read.All
  • Files.ReadWrite
  • Sites.Read.All
  • Sites.ReadWrite.All
  • User.Read

Select 'Grant Admin Access' to grant access to all permissions.

Example

Configure authentication in Content Manager Enterprise Studio

To use the Azure AD app created above open Content Manager Enterprise Studio and:

  1. from the database choose Authentication > OpenID
  2. The OpenID Issuer URL is taken from the Azure App - Overview > Endpoints > OpenID Connect metadata document
  3. The Client Id is taken from the Azure App - Overview > Application ID
  4. Client secret should be empty
  5. Client app scope should contain 'openid email offline_access'

Example

Configure Azure AD for Office Integration access

The office integration requires an access token to allow it to authenticate with the Web Client, this can be configured in Azure AD:

  1. create an Azure App for Web Authentication, you may use the one you created to authenticate with the CM Web Client,
  2. create (or edit) the file ADFS\config.xml in your CM Web Client installation folder and set it as follows:
  3. from the Azure App for Web Authentication:
    1. go to 'Expose an API',
    2. select 'Add a Scope',
    3. enter the following values:
      • Scope name: access_as_user,
      • Who can consent: Admins and Users,
      • Admin consent display name: Office can act as the user
      • Admin consent description: Enable Office to call the add-in's web APIs with the same rights as the current user
      • User consent display name: Office can act as you
      • User consent description: Enable Office to call the add-in's web APIs with the same rights that you have
    4. Click the 'Add scope' button
  4. from the CM Desktop Azure App go to API Permissions and:
    1. select 'Add a Permission'
    2. choose 'My APIs'
    3. select the Web Client Application
    4. select the access_as_user permissions
    5. select 'Add permission'.
  5. The web client authentication information needs to updated to be made aware of the new client, to do this:
    1. from the CM Desktop Azure App copy the 'Application ID URI' (will probably look similar to this: api://cf2501bd-10f0-4ad6-96dc-f5cf7b2b3bf5)
    2. edit the Web Client hprmServiceAPI.config file
    3. in the 'add' element of the openIDConnect element add a new attribute called 'appIdURI' (this is a case senstitive name),
    4. the value of appIdURI should be the 'Application ID URI' from the CM Desktop Azure App

Example Config.xml

<adfsClient>
<clientAuthority>https://login.windows.net/cmofficedev.onmicrosoft.com</clientAuthority>
<clientResourceUri>api://auchurchla02:3000/09f0ec5c-87e9-4568-8b60-4eb3e20de75e</clientResourceUri>
<clientID>cf2501bd-10f0-4ad6-96dc-f5cf7b2b3bf5</clientID>
<clientReturnUri>http://MyWebClient</clientReturnUri>
</adfsClient>

Troubleshooting Azure AD for Office Integration access

Error AADSTS500011: The resource principal named https://MYSERVER/contentmanager/ was not found in the tenant named XXXX-XXXX-XXXXX-XXXXXX.

If you get this error try using the Client ID in clientResourceUri, rather than Application ID URI.