Genpact Cora Knowledge Center

Support

Configure OpenID Connect authentication

Overview

OpenID Connect is an authentication layer on top of the OAuth 2.0 protocol. With OpenID Connect, clients verify the identity of end-users based on the authentication performed by an authorization server, and obtain basic profile information about the connecting end-user in an interoperable and REST-like manner.

Cora SeQuence supports the authorization code flow as a means of authentication.
For more details on the core OpenID Connect functionality, see this page

Prerequisites

  • Cora SeQuence Administration and Flowtime must be configured to use HTTPS.
    For details on configuring HTTPS for Cora SeQuence sites, see this article.  
  • Obtain your server's fully qualified domain name (FQDN) and Cora SeQuence's base URL.
  • Determine whether users are identified by email or by name.

Supported flows

  • Cora SeQuence only supports the Authorization Code Flow. 
    • For the authentication request, Cora SeQuence supports HTTP-POST (by default) and HTTP-GET.
    • For the Token request, Cora SeQuence supports Basic-Authentication and POST-Authentication. 

How to configure

Cora SeQuence supports automatic discovery of the OpenID provider's configuration, or manual configuration of the OpenID provider. 

Note: If your Cora SeQuence installation does not use discovery, see Appendix A below for additional configuration instructions.

Configuring the OpenID Provider (OP) 

1. Generate the following with your OpenID Provider:  

  • Client ID
  • Client secret

2. Configure the Reply URLs by appending the following to the base part of the application:
oidcServices/signinresponse(i.e. https://sequenceadmin.mycompany.com/oidcServices/signinresponse )

3. Do one of the following:

  • If your OP works with discovery, obtain the discovery URI.
    It will be used when configuring the web.config. 
  • If your OP does not work with discovery, but has the token signing keys available from an end point, then obtain a copy of that end point.  

Configuring ADSS

  • If you use Windows Active Directory or Azure Active Directory, configure Cora SeQuence's Active Directory Synchronization Service to retrieve users.
  • Validate that users are synchronized and that at least one of the authentication fields contains the unique user identifier.
    For more details on configuring active directory synchronization, see this article.

 Configuring IIS 

  • Enable only anonymous authentication for the Administration site and Flowtime site.
  • Make sure that the only default document is default.aspx.

Configuring the web.config file

1. Add the following section under the <configuration> <configSections> nodes:

a. Directly under <configSections> , add the following nodes:

<section name="system.identityModel" type="System.IdentityModel.Configuration.SystemIdentityModelSection, System.IdentityModel, Version=4.0.0.0, Culture=neutral, PublicKeyToken=B77A5C561934E089" />
   <section name="system.identityModel.services" type="System.IdentityModel.Services.Configuration.SystemIdentityModelServicesSection, System.IdentityModel.Services, Version=4.0.0.0, Culture=neutral, PublicKeyToken=B77A5C561934E089" />

b. Under the <sequence.engine> <sectionGroup>, add the following nested<sectionGroup>:

<sectionGroup name="identity" type="PNMsoft.Sequence.Configuration.IdentityConfiguration,PNMsoft.Sequence.IdentityModel.v8, Version=8.0.0.0, Culture=neutral, PublicKeyToken=0a1a1b90c1c5dca1">
       <section name="openIdConnect" type="PNMsoft.Sequence.IdentityModel.OpenIdConnect.Configuration.OpenIdConnectConfigurationSection, PNMsoft.Sequence.IdentityModel.OpenIdConnect, Version=8.0.0.0, Culture=neutral, PublicKeyToken=0a1a1b90c1c5dca1" />
     </sectionGroup>

2. Register the following modules:

<system.webServer>
... 
  <modules>
    <!-- Other modules already configured in web.config should be here -->
<add name="SessionAuthenticationModule" type="System.IdentityModel.Services.SessionAuthenticationModule, System.IdentityModel.Services, Version=4.0.0.0, Culture=neutral, PublicKeyToken=b77a5c561934e089" preCondition="managedHandler" />
<add name="OpenIdConnectAuthenticationModule" type="PNMsoft.Sequence.IdentityModel.Services.OpenIdConnectAuthenticationHttpModule, PNMsoft.Sequence.IdentityModel.OpenIdConnect, Version=8.0.0.0, Culture=neutral, PublicKeyToken=0a1a1b90c1c5dca1"/>
 </modules>
...
</system.webServer>

3. Add the OpenID Connect configuration.

Template of the <OpenIdConnect>node

<sequence.engine>
...
<identity>    
<openIdConnect 
discoveryKind="OpenIdDiscoveryDocument"
                    discoveryUri="<your openID sever discovery Uri>"
           
clientId="your clientID"
clientSecret="Your ClientSecret"
           
cookieEncryptionKey="a random choice of 30 alpha-numeric chars"
cookieEncryptionInitializationVector="another random choice of 30 alpha-numeric chars"/>
</identity>
...
</sequence.engine>

Attributes 

NameDescriptionRequiredValue
discoveryKindHow the application gets the additional OpenID Connect configuration from the OP.YesOpenIdDiscoveryDocument (when using discovery)
discoveryUriThe URL of the OP's discovery document.Yes (if using discovery)To be obtained from the OP
clientIDThe ID of the application in the OP.Yes To be obtained from the OP

clientSecretThe symmetric key of the application and the OP.Yes To be obtained from the OP

cookieEncryptionKeyThe key Cora SeQuence uses to encrypt its cookie.YesA randomly chosen string of alpha-numeric characters (30 characters)
cookieEncryptionInitializationVectorThe initialization vector Cora SeQuence uses to encrypt its cookie.
NOTE: If your system uses load balancing,cookieEncryptionKeyand
cookieEncryptionInitializationVector must be identical.
YesA randomly chosen string of alpha-numeric characters (30 characters)
authorizationRequestHttpMethod
Determines whether the authorization request is sent to the OP as an HTTP-GET or HTTP-POST.
NOTE: From our tests, Azure AD works with POST, whereas Okta works with GET.
NoPOST or GET

4. Configure the SessionAuthenticationModule.

a. Anywhere under the root configuration node, add the following nodes, making sure that you replace https://sequenceadmin.mycompany.com with your application base URL.

<configuration>
...
<system.identityModel>
   <identityConfiguration>
     <audienceUris>
       <add value="https://sequenceadmin.mycompany.com"/>
     </audienceUris>
   </identityConfiguration>
 </system.identityModel>
 <system.identityModel.services>
   <federationConfiguration>
     <cookieHandler requireSsl="true" />
   </federationConfiguration>
 </system.identityModel.services>
...
</configuration>

5. Configure Cora SeQuence Services. 

Note: Windows authentication must be removed from Sequence Web Services.

a. Locate the <system.serviceModel> node in the web.config file. 

b. In the child node <binding>, change the clientCredentialType value from "Windows" to "None":

<bindings>
     <webHttpBinding>
       <binding name="webHttpsBinding">
         <security mode="Transport">
           <transport clientCredentialType="None" />
         </security>
       </binding>
       <binding name="webHttpBinding">
         <security mode="TransportCredentialOnly">
           <transport clientCredentialType="None" />
         </security>
       </binding>
     </webHttpBinding>
   </bindings>

6. Configure the Cora SeQuence authentication provider.

a. Add claims authentication under the <configuration> <sequence.engine> <authentication> section:

<providers>
         <add type="PNMsoft.Sequence.Security.ClaimsIdentityAuthenticationProvider, PNMsoft.Sequence.IdentityModel.v8, Version=8.0.0.0, Culture=neutral, PublicKeyToken=0a1a1b90c1c5dca1" />
      </providers>
      <forms enabled="false" />
      <claims enabled="true" signoutFromSts="false" ssoEnabled="true" loginUrl="~/oidcServices/Signininitiation" logoutUrl="~/oidcServices/SignOutInitiation" accessDeniedUrl="~/AccessDenied.aspx">
        >IdentityClaims>
          >add claimType=">claim type>" originalIssuer=">token issuer>" authenticationType=">sequence authentication type>"/>
        >/IdentityClaims>
      >/claims>

b. Replace the attribute values in this line:
claimType="<claim type>" originalIssuer="<token issuer>" authenticationType="<sequence authentication type" with the appropriate values.
For additional information on claims-based authentication configuration, see  this article.

Appendix A:  Configure OpenID Connect without discovery

Perform the configuration procedures described above, and when configuring the <openIdConnect> node, add attributes according to the discovery kind used by your installation. 

Example of the <openIdConnect>node with discoveryKind="JsonWebKeySet":

<openIdConnect discoveryKind="JsonWebKeySet"
              discoveryUri="https://urlToTokenSigningKeys"
              validIssuer="uriOfIssuer"
              clientId="yourClientId" clientSecret="yourClientSecret"
              cookieEncryptionKey="yourChoiceOf30AlphanumericCharactersForKey" cookieEncryptionInitializationVector="yourChoiceOf30AlphanumericCharactersForInitVector"
              authorizationRequestHttpMethod="Get"
              authority="https://authorizationEndpoint"
             tokenEndpoint="https://tokenEndpoint"
             logoutEndpoint="https://logoutEndpoint"
             tokenRequestAuthorizationMethod="client_secret_basic"
             idTokenSigningAlgValues="RS256"/>

Example of the <openIdConnect>node with discoveryKind="Store":

<openIdConnect discoveryKind="Store"
              validIssuer="uriOfIssuer"
              clientId="yourClientId" clientSecret="yourClientSecret"
              cookieEncryptionKey="yourChoiceOf30AlphanumericCharactersForKey" cookieEncryptionInitializationVector="yourChoiceOf30AlphanumericCharactersForInitVector"
              authorizationRequestHttpMethod="Get"
              authority="https://authorizationEndpoint"
             tokenEndpoint="https://tokenEndpoint"
             logoutEndpoint="https://logoutEndpoint"
             tokenRequestAuthorizationMethod="client_secret_basic"
             idTokenSigningAlgValues="RS256">
 <identityProviderCertificates>
 <add name="firstCertificate" certificateFindType="FindByThumbprint" certificateFindValue="0aaf6ec6b0a8550a6e6e4c85eb4123888cbec941" certificateLocation="LocalMachine" valid="false" />
 <add name="secondCertificate" certificateFindType="FindByThumbprint" certificateFindValue="d92e120951acf1283d2d2e80a8b22ae83a56fa0f" certificateLocation="LocalMachine" valid="false" />
 <add name="thirdCertificate" certificateFindType="FindByThumbprint" certificateFindValue="cf8e3031d1eef302acba6adb7da2bdf2ac6ce582" certificateLocation="LocalMachine" valid="false"/>
 <add name="fourthCertificate" certificateFindType="FindByThumbprint" certificateFindValue="c78efcc723a996c3351fb35793b4b1d7bc75ba97" certificateLocation="LocalMachine" valid="false"/>
 </identityProviderCertificates>
</openIdConnect>

Configuration settings

ItemDescriptionValueRequired
validIssuerThe name of the token issuer. The name will be validated against the token and signing certificate.N/AYes
authorityThe OpenID authorization endpoint.
Depends on discoveryKind
discoveryKindDetermines how the OpenID module discovers the identity provider’s signing tokens.See the discoveryKind table belowYes
discoveryUri
  • When the discoveryKind is set to OpenIdDiscoveryDocument:
    this is the URL of the OP's discovery document.
  • When the discoveryKind is set to JsonWebKeySet or Federation:
    this setting is used to locate the document containing the required information to retrieve the identity of the provider’s signing keys.
  • When the discoveryKind is set to Store:
    this value is not required.
The default is an empty string.Depends on discoveryKind
identityProviderCertificatesA collection of configuration elements that determine how to locate a certificate in the machine Certificate Store. This element is required only when the discoveryKind is set to ‘Store’.
NOTE:  identityProviderCertificates is a node, not an attribute. 
Null (default) -- see identityProviderCertificate options table below.No
clientIdThe ID of the application in the OP.To be obtained from the OP.Yes
clientSecretThe symmetric key of the application and the OP.To be obtained from the OP.
Yes

cookieEncryptionKeyThe key Cora SeQuence uses to encrypt its cookie.A randomly chosen string of alpha-numeric characters (30 characters).
Yes
cookieEncryptionInitializationVectorThe initialization vector Cora SeQuence uses to encrypt its cookie.A randomly chosen string of alpha-numeric characters (30 characters).
Yes
tokenEndpointThe OpenID token endpoint.
Yes
logoutEndpointThe OpenID logout endpoint.
Yes
tokenRequestAuthorizationMethodThe means by which the token request is authenticated by the OP."client_secret_basic"  or "client_secret_post"Yes
idTokenSigningAlgValuesIdentifies the signing algorithm of the ID token.Use one of the values in the left most column in the table in section A.1
Yes
authorizationRequestHttpMethodDetermines whether the authorization request is sent to the OP as an HTTP-GET or HTTP-POST.
NOTE: From our tests, Azure AD works with POST, whereas Okta works with GET.
POSTNo

discoveryKind options

A token is usually signed by the OpenID Provider using a public certificate. Cora SeQuence should be able to obtain the public certificate to validate the OpenID Provider’s signature in the token.
There are four ways that  Cora SeQuence can discover the public certificate:

discoveryKind attribute valueDescription
OpenIdDiscoveryDocumentIndicates that the discovery is done using an OpenIdDiscoveryDocument . When this option is used, the discoveryUri attribute must be set to a Uri that contains this type of document.
JsonWebKeySetRequires a Uri that returns a JsonWebKeySet result. This setting is a subsetting of the OpenIdDiscoveryDocument.
FederationRequires a Uri that returns a WS-Federation metadata document. When this option is used, the discoveryUri attribute must be set to a Uri that contains this type of document.
StoreUse this option when the certificates are stored in the computer's local certificate store. When this option is used, the IdentityProviderCertificates element is required.

identityProviderCertificate options

Under identityProviderCertificate, you configure where and how to retrieve certificates from the local certificate store. This is relevant only when setting Store under the discoveryKind attribte.

AttributeDescription
nameA unique name for each certificate.
certificateFindType
Value based on the System.Security.Cryptography.X509Certificates.X509FindType enum.
certificateFindValueThe value to search for based on the certificateFindType attribute.
certificateLocationValue based on the System.Security.Cryptography.X509Certificates.StoreLocation  enum.
validIndicates that the certificate can be retrieved even if it is not valid (entire chain can not be validated).