SAML 2.0 Federated Authentication: Difference between revisions

From QPR ProcessAnalyzer Wiki
Jump to navigation Jump to search
No edit summary
 
(54 intermediate revisions by 2 users not shown)
Line 1: Line 1:
QPR ProcessAnalyzer can use federated authentication with the SAML 2.0 protocol. When using the federated authentication, QPR ProcessAnalyzer works as a '''service provider (SP)''', and uses compatible external '''identity providers (IdP)''' to provide user identity (i.e. authenticating users), such as Microsoft Active Directory Federation Services (ADFS) or Shibboleth.
QPR ProcessAnalyzer supports authenticating users with federated authentication using the SAML 2.0 protocol. QPR ProcessAnalyzer works as a '''service provider (SP)''' and uses an external '''identity providers (IdP)''' to provide user identity (i.e. authenticating users). Commonly used identity providers are Azure AD and Microsoft Active Directory Federation Services (ADFS).


==QPR ProcessAnalyzer as SAML 2.0 Service Provider==
== Introduction ==
When QPR ProcessAnalyzer is configured as a SAML 2.0 service provider ('''SP'''), users can authenticate to QPR ProcessAnalyzer via the configured SAML 2.0 identity provider ('''IdP''') by clicking '''Log in Using SSO''' button in the login screen. This redirects users to the identity provider for authentication. When the authentication is done, users are redirected back to QPR ProcessAnalyzer where user is then logged in.
When QPR ProcessAnalyzer is configured as a SAML 2.0 service provider (SP), users can authenticate to QPR ProcessAnalyzer via the configured SAML 2.0 identity provider (IdP). When accessing QPR ProcessAnalyzer, users are automatically redirected to the identity provider for authentication. When the authentication is done, users are redirected back to QPR ProcessAnalyzer where user is then automatically logged in. When using federated authentication, users don't normally see the QPR ProcessAnalyzer login page. The login page can be accessed (e.g. when login using QPR ProcessAnalyzer user management credentials) by adding '''forceLogin=1''' parameter to the url, e.g. <nowiki>https://customer.onqpr.com/QPRPA/ui/#/login?forceLogin=1</nowiki>.  


Alternatively, QPR ProcessAnalyzer can automatically redirect users to the identity provider, so that users won't see the QPR ProcessAnalyzer's login screen. This automatic redirection occurs, when accessing url '''/<root>/api/saml''', e.g. https://customer.onqpr.com/qprpa/api/saml. For example a redirection to this url can be configured to IIS.
QPR ProcessAnalyzer can also automatically redirect users to the identity provider from the url '''/qprpa/saml2''', e.g. <nowiki>https://customer.onqpr.com/qprpa/saml2</nowiki>. Redirection to this url can be configured to IIS, when users access QPR ProcessAnalyzer with the server name only, e.g. <nowiki>https://customer.onqpr.com</nowiki>. The advantage of using this url is that the QPR ProcessAnalyzer web application is not loaded before the authentication, making the authentication flow faster. When going to the identity provider using a url starting with <nowiki>https://customer.onqpr.com/QPRPA/ui/</nowiki>, the QPR ProcessAnalyzer web application is loaded before going to the identity provider.


When a user logs in to QPR ProcessAnalyzer for the first time, user account is created to QPR ProcessAnalyzer user management. This account can only log in using the federated authentication, because the user account doesn't have a password in QPR ProcessAnalyzer. User accounts are matched between the systems using usernames.
When a user logs in to QPR ProcessAnalyzer for the first time, user account is created to QPR ProcessAnalyzer user management. This account can only log in using the federated authentication, because the user account doesn't have a password in QPR ProcessAnalyzer. User accounts are matched between QPR ProcessAnalyzer and the identity provider using usernames.


Further notes regarding the federated authentication:
Additional notes for the SAML authentication:
* QPR ProcessAnalyzer only support SAML POST binding (e.g. SAML redirect binding is not supported).
* QPR ProcessAnalyzer needs to use https when SAML 2.0 authentication is used.
* When QPR ProcessAnalyzer has been configured to use an identity provider, QPR ProcessAnalyzer will fully trust information coming from the identity provider.
* The identity provider needs to publish the identity provider metadata, because QPR ProcessAnalyzer reads the identity provider settings from there.
* Currently the logout request to IdP is not supported by QPR ProcessAnalyzer.
* QPR ProcessAnalyzer only supports SAML POST binding (e.g., SAML redirect binding is not supported).
* SAML AuthnRequests are not signed (by QPR ProcessAnalyzer), and SAML Assertions must be signed (by the IdP) to be accepted by QPR ProcessAnalyzer
*''SAML AuthnRequests'' are self-signed using a certificate that is embedded to QPR ProcessAnalyzer. The certificate public key is available in the service provider metadata published by the [[Web API: saml2|QPR ProcessAnalyzer Web API]]. The embedded certificate has a maximum validity of one year, so if using the embedded certificate, make sure to update QPR ProcessAnalyzer to the latest releases, to maintain having a valid certificate.
*''SAML Assertions'' must be signed (by the identity provider) to be accepted by QPR ProcessAnalyzer.
*SAML Assertions can optionally be encrypted by the identity provider. This requires the SAMLEncryptionCertificate setting to be defined in the [[PA_Configuration_database_table#SAML_2.0_Federated_Authentication_Settings|QPR ProcessAnalyzer configuration table]].
* Logout request to identity provider is not supported by QPR ProcessAnalyzer.
* If user clicks the logout button, user is redirected to the QPR ProcessAnalyzer login page. There user can click the '''Log in using SSO''' button to relogin.
* If the QPR ProcessAnalyzer session expires, user is redirected back to the identity provider for relogin.


==Configuring QPR ProcessAnalyzer as SAML 2.0 Service Provider==
==Configuring SAML to QPR ProcessAnalyzer==


The configuration entries listed in the tables below, can be defined either
To configure the SAML 2.0 authentication, follow these steps:
* using the QPR ProcessAnalyzer installer during the QPR ProcessAnalyzer installation (only part of the settings)
# Define settings '''SAMLMetadataUrl''', '''ServiceProviderLocation,''' '''SAMLUserIdAttribute''', '''SAMLEncryptionCertificate''' (optional), and '''SAMLSigningCertificate''' (optional) in the [[PA_Configuration_database_table#SAML_2.0_Federated_Authentication_Settings|QPR ProcessAnalyzer configuration table]]. QPR ProcessAnalyzer needs to be restarted for the settings to take effect.
* after the QPR ProcessAnalyzer installation by adding to the '''CONFIGURATIONENTITY''' table in the QPR ProcessAnalyzer database.
# Configure a redirection from the root path of the QPR ProcessAnalyzer server to '''/qprpa/saml2''', so that users are automatically redirected to the identity provider for authentication.
# The identity provider configuration depends on which identity provide is used. See below for help how to configure [[#Using Azure AD as Identity Provider|Azure AD]] and [[#Using ADFS as Identity Provider|ADFS]] as the identity provider.


=== Setup When Using Metadata ===
If there are any issues with the authentication, please check the [[QPR_ProcessAnalyzer_Logs|QPR ProcessAnalyzer logs]].
Federated authentication can be configured to use SAML2 metadata if it's available as an XML document through HTTP.


{| class="wikitable"
==Using Azure AD as Identity Provider==
! Database&nbsp;field&nbsp;name
Azure Active Directory (AAD) can be used as an identity provider to login to QPR ProcessAnalyzer. Following configurations are needed:
! Installer&nbsp;field&nbsp;name
# Login to https://portal.azure.com as a cloud application admin or an application admin for your Azure AD tenant.
! Description
# Click '''Azure Active Directory''' > '''Enterprise Applications''' > '''New application'''. Select '''Non-gallery application'''.
|-
# Define '''Name''' for the application, e.g., "QPR ProcessAnalyzer".
|SAML_METADATA_URL
# Go to '''Manage''' > '''Single sign-on''' > '''SAML'''.
|Federation metadata URL
# Click '''Edit''' pencil on the '''Basic SAML Authentication''' and define following settings (where <hostname> is the name of the QPR ProcessAnalyzer server):
|The metadata URL of the identity provider. Check that the metadata can be opened using the configured link. The metadata is an XML document, so it should start '''<?xml version="1.0" encoding="UTF-8"?>''' followed by an '''EntityDescriptor''' tag. The metadata URL might look something like '''<nowiki>https://your.federated.identity.provider.com/saml/metadata</nowiki>'''.
##'''Identifier (Entity ID):''' https://<hostname>/qprpa/saml2
|-
## '''Reply URL (Assertion Consumer Service URL):''' https://<hostname>/qprpa/saml2/acs
|SAML_SERVER_ENTITY_IDENTIFIER
## '''Sign on URL:''' It's recommended to leave this setting empty.
|Server entity identifier
# Copy the '''App Federation Metadata Url''' to the clipboard to store it to  to the ''SAMLMetadataUrl'' setting in the QPR ProcessAnalyzer configuration table.
|Use this field to define the identity provider entity ID, if the federation metadata contains multiple identity providers. This field is not mandatory, if the metadata contains only one identity provider. In the federation metadata, a single '''EntityDescriptor''' tag represents one identity provider, so you can check the number of available identity providers by checking the federation metadata contents ('''entityID''' attribute).
# If you want QPR Application to synchronize group membership between Azure AD and QPR ProcessAnalyzer, please add also the '''Group Claim''' from User '''Attributes & Claims'''.
|}
 
More information about Azure Active Directory: https://docs.microsoft.com/en-us/azure/active-directory/


{| class="wikitable"
Instructions for setting up the optional SAML assertions encryption: https://docs.microsoft.com/en-us/azure/active-directory/manage-apps/howto-saml-token-encryption?WT.mc_id=migration_service_aad_-inproduct-azureportal.
! Database&nbsp;field&nbsp;name
! Installer&nbsp;field&nbsp;name
! Description
|-
|SAML_CONSUMER_URL
|SAML consumer URL
|Url that the identity provider uses when redirecting back to QPR ProcessAnalyzer. Use url with following form: '''<Location of your QPR ProcessAnalyzer installation>/EnticeServices/rest/authenticate/saml''', e.g. '''<nowiki>http://SERVERNAME/EnticeServices/rest/authenticate/saml</nowiki>'''. This setting is mandatory for the federated authentication to work.
|-
|SAML_USER_ID_ATTRIBUTE
|User id attribute
|The name of the SAML attribute in the assertion that will be used as the user's login name. If this field is not given or is empty, the '''saml:Assertion''' > ''' saml:Subject''' > '''saml:NameID''' attribute is used in the assertion. If this field is given, one of the '''saml:Assertion''' > '''saml:AttributeStatement''' > '''saml:Attribute''' elements in the assertion is used (the '''Name''' attribute in the '''saml:Attribute''' element is used for matching). Please note that the first mentioned saml:NameID element is different than the usual SAML attributes that are defined using saml:Attribute elements.
|}


==Using ADFS as Identity Provider==
==Using ADFS as Identity Provider==
Line 55: Line 49:
* Step 4: Select option '''Enter data about the relying party manually''' as metadata is not available.
* Step 4: Select option '''Enter data about the relying party manually''' as metadata is not available.
* Step 5: Name can be chosen freely.
* Step 5: Name can be chosen freely.
* Step 7: Disable option '''Enable support for the WS-Federation Passive protocol'''. Select option '''Enable support for the SAML 2.0 WebSSO protocol''' and define url '''<nowiki>https://SERVERNAME/EnticeServices/rest/authenticate/saml</nowiki>''' where SERVERNAME is the QPR ProcessAnalyzer server hostname.
* Step 7: Disable option '''Enable support for the WS-Federation Passive protocol'''. Select option '''Enable support for the SAML 2.0 WebSSO protocol''' and define url '''<nowiki>https://<hostname>/qprpa/saml2/Acs</nowiki>''' where SERVERNAME is the QPR ProcessAnalyzer server hostname.
* Step 8: Define url '''<nowiki>https://SERVERNAME/EnticeServices/rest/authenticate/saml</nowiki>''' where SERVERNAME is the QPR ProcessAnalyzer server hostname.
* Step 8: Define url '''https://<hostname>/qprpa/saml2/Acs''' where <hostname> is the QPR ProcessAnalyzer server hostname.
* Step 11: Select option '''Configure claims issuance policy for this application'''.
* Step 11: Select option '''Configure claims issuance policy for this application'''.


Line 65: Line 59:
</pre>
</pre>


==Using Azure AD as Identity Provider==
== SAML 2.0 Authentication API ==
Azure Active Directory (AD) can be used as an identity provider to login to QPR ProcessAnalyzer. Configuration scenario (discussed above) for Azure AD is to use metadata. Following configurations are needed:
QPR ProcessAnalyzer has [[Web_API:_saml2/acs|/saml2/acs]] endpoint which accepts a SAML assertion from the IdP and returns a HTTP redirection to QPR ProcessAnalyzer Web UI. The url contains a ''sys:samlHash'' parameter which is used by the Web UI to login the user using the [[Web_API:_Token|/token]] endpoint (to get a session token to use in the interactions with the Web API).
# Login to https://portal.azure.com, click '''Azure Active Directory''', click '''App registrations''' and click '''New application registration'''.
 
# Define '''Name''' for the application, such as "QPR ProcessAnalyzer". Select '''Application type''' to be '''Web app / API'''. Define '''Sign-on URL''' to be '''<nowiki>http://SERVERNAME/EnticeServices/rest/authenticate/saml</nowiki>''' (where SERVERNAME is the name of your QPR ProcessAnalyzer server, http/https protocol matches and the port is the right one).
== Troubleshooting ==
# When the Azure application has been created, from the applications settings click '''Properties'''.
'''Problem''': When trying to authenticate with SAML, QPR ProcessAnalyzer responds: ''Bad Request - Request too long''.
# Click '''Azure Active Directory''', click '''App registrations''' and click '''Endpoints'''. Copy the contents of the '''Federation Metadata Document''' field, and configure it to the QPR ProcessAnalyzer SAML_METADATA_URL setting (discussed above).


More information about Azure Active Directory: https://docs.microsoft.com/en-us/azure/active-directory/
'''Solution''': This error comes when the SAML assertion (message from IdP to QPR ProcessAnalyzer) contains too long data. The SAML assertion is encoded to an http header (as part of a cookie), which has a certain allowed maximum length. One option is to increase the limits in the Windows http.sys web server (https://learn.microsoft.com/en-us/troubleshoot/developer/webapps/iis/iisadmin-service-inetinfo/httpsys-registry-windows). Alternatively, it may be possible reduce the amount of data included by the IdP to the SAML assertion.


==References==
==References==
* General information about federated authentication: https://en.wikipedia.org/wiki/Federated_identity
* General information about federated authentication: https://en.wikipedia.org/wiki/Federated_identity
* General information about SAML 2.0: https://en.wikipedia.org/wiki/SAML_2.0
* General information about SAML 2.0: https://en.wikipedia.org/wiki/SAML_2.0
* General information about Shibboleth: https://en.wikipedia.org/wiki/Shibboleth_(Internet2)
* SAML 2.0 in Azure AD: https://docs.microsoft.com/en-us/azure/active-directory/develop/single-sign-on-saml-protocol
* Shibboleth documentation: https://wiki.shibboleth.net/confluence/display/SHIB2/Home
* General information about ADFS: https://en.wikipedia.org/wiki/Active_Directory_Federation_Services
* General information about ADFS: https://msdn.microsoft.com/en-us/library/bb897402.aspx
* ADFS documentation: https://msdn.microsoft.com/en-us/library/bb897402.aspx
* ADFS documentation: https://en.wikipedia.org/wiki/Active_Directory_Federation_Services


[[Category: QPR ProcessAnalyzer]]
[[Category: QPR ProcessAnalyzer]]

Latest revision as of 22:28, 26 May 2024

QPR ProcessAnalyzer supports authenticating users with federated authentication using the SAML 2.0 protocol. QPR ProcessAnalyzer works as a service provider (SP) and uses an external identity providers (IdP) to provide user identity (i.e. authenticating users). Commonly used identity providers are Azure AD and Microsoft Active Directory Federation Services (ADFS).

Introduction

When QPR ProcessAnalyzer is configured as a SAML 2.0 service provider (SP), users can authenticate to QPR ProcessAnalyzer via the configured SAML 2.0 identity provider (IdP). When accessing QPR ProcessAnalyzer, users are automatically redirected to the identity provider for authentication. When the authentication is done, users are redirected back to QPR ProcessAnalyzer where user is then automatically logged in. When using federated authentication, users don't normally see the QPR ProcessAnalyzer login page. The login page can be accessed (e.g. when login using QPR ProcessAnalyzer user management credentials) by adding forceLogin=1 parameter to the url, e.g. https://customer.onqpr.com/QPRPA/ui/#/login?forceLogin=1.

QPR ProcessAnalyzer can also automatically redirect users to the identity provider from the url /qprpa/saml2, e.g. https://customer.onqpr.com/qprpa/saml2. Redirection to this url can be configured to IIS, when users access QPR ProcessAnalyzer with the server name only, e.g. https://customer.onqpr.com. The advantage of using this url is that the QPR ProcessAnalyzer web application is not loaded before the authentication, making the authentication flow faster. When going to the identity provider using a url starting with https://customer.onqpr.com/QPRPA/ui/, the QPR ProcessAnalyzer web application is loaded before going to the identity provider.

When a user logs in to QPR ProcessAnalyzer for the first time, user account is created to QPR ProcessAnalyzer user management. This account can only log in using the federated authentication, because the user account doesn't have a password in QPR ProcessAnalyzer. User accounts are matched between QPR ProcessAnalyzer and the identity provider using usernames.

Additional notes for the SAML authentication:

  • QPR ProcessAnalyzer needs to use https when SAML 2.0 authentication is used.
  • The identity provider needs to publish the identity provider metadata, because QPR ProcessAnalyzer reads the identity provider settings from there.
  • QPR ProcessAnalyzer only supports SAML POST binding (e.g., SAML redirect binding is not supported).
  • SAML AuthnRequests are self-signed using a certificate that is embedded to QPR ProcessAnalyzer. The certificate public key is available in the service provider metadata published by the QPR ProcessAnalyzer Web API. The embedded certificate has a maximum validity of one year, so if using the embedded certificate, make sure to update QPR ProcessAnalyzer to the latest releases, to maintain having a valid certificate.
  • SAML Assertions must be signed (by the identity provider) to be accepted by QPR ProcessAnalyzer.
  • SAML Assertions can optionally be encrypted by the identity provider. This requires the SAMLEncryptionCertificate setting to be defined in the QPR ProcessAnalyzer configuration table.
  • Logout request to identity provider is not supported by QPR ProcessAnalyzer.
  • If user clicks the logout button, user is redirected to the QPR ProcessAnalyzer login page. There user can click the Log in using SSO button to relogin.
  • If the QPR ProcessAnalyzer session expires, user is redirected back to the identity provider for relogin.

Configuring SAML to QPR ProcessAnalyzer

To configure the SAML 2.0 authentication, follow these steps:

  1. Define settings SAMLMetadataUrl, ServiceProviderLocation, SAMLUserIdAttribute, SAMLEncryptionCertificate (optional), and SAMLSigningCertificate (optional) in the QPR ProcessAnalyzer configuration table. QPR ProcessAnalyzer needs to be restarted for the settings to take effect.
  2. Configure a redirection from the root path of the QPR ProcessAnalyzer server to /qprpa/saml2, so that users are automatically redirected to the identity provider for authentication.
  3. The identity provider configuration depends on which identity provide is used. See below for help how to configure Azure AD and ADFS as the identity provider.

If there are any issues with the authentication, please check the QPR ProcessAnalyzer logs.

Using Azure AD as Identity Provider

Azure Active Directory (AAD) can be used as an identity provider to login to QPR ProcessAnalyzer. Following configurations are needed:

  1. Login to https://portal.azure.com as a cloud application admin or an application admin for your Azure AD tenant.
  2. Click Azure Active Directory > Enterprise Applications > New application. Select Non-gallery application.
  3. Define Name for the application, e.g., "QPR ProcessAnalyzer".
  4. Go to Manage > Single sign-on > SAML.
  5. Click Edit pencil on the Basic SAML Authentication and define following settings (where <hostname> is the name of the QPR ProcessAnalyzer server):
    1. Identifier (Entity ID): https://<hostname>/qprpa/saml2
    2. Reply URL (Assertion Consumer Service URL): https://<hostname>/qprpa/saml2/acs
    3. Sign on URL: It's recommended to leave this setting empty.
  6. Copy the App Federation Metadata Url to the clipboard to store it to to the SAMLMetadataUrl setting in the QPR ProcessAnalyzer configuration table.
  7. If you want QPR Application to synchronize group membership between Azure AD and QPR ProcessAnalyzer, please add also the Group Claim from User Attributes & Claims.

More information about Azure Active Directory: https://docs.microsoft.com/en-us/azure/active-directory/

Instructions for setting up the optional SAML assertions encryption: https://docs.microsoft.com/en-us/azure/active-directory/manage-apps/howto-saml-token-encryption?WT.mc_id=migration_service_aad_-inproduct-azureportal.

Using ADFS as Identity Provider

ADFS (Active Directory Federation Services) can be used as an identity provider to login to QPR ProcessAnalyzer. For ADFS setup, follow the ADFS configuration guide in https://docs.microsoft.com/en-us/windows-server/identity/ad-fs/operations/create-a-relying-party-trust with the following notes:

  • Step 4: Select option Enter data about the relying party manually as metadata is not available.
  • Step 5: Name can be chosen freely.
  • Step 7: Disable option Enable support for the WS-Federation Passive protocol. Select option Enable support for the SAML 2.0 WebSSO protocol and define url https://<hostname>/qprpa/saml2/Acs where SERVERNAME is the QPR ProcessAnalyzer server hostname.
  • Step 8: Define url https://<hostname>/qprpa/saml2/Acs where <hostname> is the QPR ProcessAnalyzer server hostname.
  • Step 11: Select option Configure claims issuance policy for this application.

Example: 

c:[Type == "http://schemas.microsoft.com/ws/2008/06/identity/claims/windowsaccountname", Issuer == "AD AUTHORITY"]
=> issue(store = "Active Directory", types = ("http://schemas.xmlsoap.org/ws/2005/05/identity/claims/upn", "http://schemas.xmlsoap.org/claims/CommonName", "http://schemas.xmlsoap.org/ws/2005/05/identity/claims/emailaddress", "http://schemas.xmlsoap.org/claims/Group"), query = ";userPrincipalName,displayName,mail,tokenGroups;{0}", param = c.Value);

SAML 2.0 Authentication API

QPR ProcessAnalyzer has /saml2/acs endpoint which accepts a SAML assertion from the IdP and returns a HTTP redirection to QPR ProcessAnalyzer Web UI. The url contains a sys:samlHash parameter which is used by the Web UI to login the user using the /token endpoint (to get a session token to use in the interactions with the Web API).

Troubleshooting

Problem: When trying to authenticate with SAML, QPR ProcessAnalyzer responds: Bad Request - Request too long.

Solution: This error comes when the SAML assertion (message from IdP to QPR ProcessAnalyzer) contains too long data. The SAML assertion is encoded to an http header (as part of a cookie), which has a certain allowed maximum length. One option is to increase the limits in the Windows http.sys web server (https://learn.microsoft.com/en-us/troubleshoot/developer/webapps/iis/iisadmin-service-inetinfo/httpsys-registry-windows). Alternatively, it may be possible reduce the amount of data included by the IdP to the SAML assertion.

References

Retrieved from "https://wiki.onqpr.com/pa/index.php?title=SAML_2.0_Federated_Authentication&oldid=24696"