SAML 2.0 Federated Authentication: Difference between revisions

From QPR ProcessAnalyzer Wiki
Jump to navigation Jump to search
No edit summary
Line 35: Line 35:
# Click '''Edit''' pencil on the '''Basic SAML Authentication''' box and add following information (where <hostname> is the name of the QPR ProcessAnalyzer server):
# Click '''Edit''' pencil on the '''Basic SAML Authentication''' box and add following information (where <hostname> is the name of the QPR ProcessAnalyzer server):
##'''Identifier (Entity ID):''' https://<hostname>/qprpa/api/saml
##'''Identifier (Entity ID):''' https://<hostname>/qprpa/api/saml
## '''Reply URL (Assertion Consumer Service URL):''' https://<hostname>/qprpa/api/samlsignin
## '''Reply URL (Assertion Consumer Service URL):''' https://<hostname>/qprpa/Saml2/Acs
## '''Sign on URL:''' https://<hostname>/qprpa/api/samlsignin
## '''Sign on URL:''' https://<hostname>/qprpa/Saml2/Acs
# Copy the '''App Federation Metadata Url''' (this is set to QPR ProcessAnalyzer to the ''SAMLMetadataUrl'' setting).
# Copy the '''App Federation Metadata Url''' (this is set to QPR ProcessAnalyzer to the ''SAMLMetadataUrl'' setting).
# 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'''.
# 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'''.
Line 46: Line 46:
* 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/api/samlsignin</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://SERVERNAME/Saml2/Acs</nowiki>''' where SERVERNAME is the QPR ProcessAnalyzer server hostname.
* Step 8: Define url '''https://<hostname>/api/samlsignin''' where <hostname> is the QPR ProcessAnalyzer server hostname.
* Step 8: Define url '''https://<hostname>/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 57: Line 57:


== SAML 2.0 Authentication API ==
== SAML 2.0 Authentication API ==
QPR ProcessAnalyzer has [[Web_API:_Samlsignin|/api/samlsignin]] 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).
QPR ProcessAnalyzer has [[Web_API:_Samlsignin|/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).


==References==
==References==

Revision as of 16:29, 15 February 2022

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/api/saml, e.g. https://customer.onqpr.com/qprpa/api/saml. 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 federated authentication:

  • QPR ProcessAnalyzer needs to use https when SAML 2.0 authentication is used.
  • QPR ProcessAnalyzer only supports setup using SAML metadata (e.g. setup using a identity provide public key is not supported).
  • QPR ProcessAnalyzer only supports SAML POST binding (e.g. SAML redirect binding is not supported).
  • Logout request to identity provider is not supported by QPR ProcessAnalyzer.
  • SAML AuthnRequests are self-signed using a certificate that is embedded to QPR ProcessAnalyzer. The certificate metadata and public key are available from QPR CustomerCare (customercare@qpr.com).
  • SAML Assertions must be signed (by the identity provider) to be accepted 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 and SAMLUserIdAttribute 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/api/saml, 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 box and add following information (where <hostname> is the name of the QPR ProcessAnalyzer server):
    1. Identifier (Entity ID): https://<hostname>/qprpa/api/saml
    2. Reply URL (Assertion Consumer Service URL): https://<hostname>/qprpa/Saml2/Acs
    3. Sign on URL: https://<hostname>/qprpa/Saml2/Acs
  6. Copy the App Federation Metadata Url (this is set to QPR ProcessAnalyzer to the SAMLMetadataUrl setting).
  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/

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://SERVERNAME/Saml2/Acs where SERVERNAME is the QPR ProcessAnalyzer server hostname.
  • Step 8: Define url https://<hostname>/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).

References