Esko Logo Back to Esko Support
Choose your language for a machine translation:


SAML is a standard which allows software responsible for authenticating users (called Identity Provider) to be connected to any application that supports SAML. The Identity Provider has complete control over how the user authenticates. WebCenter has no influence whatsoever.

This means that settings in WebCenter related to expiration of passwords have no effect when using SAML. Even more, the Identity Provider does not even need to support passwords. It could also use something different like swiping of a card or some other technologies for two factor authentication. If you do need to expire passwords when using SAML, have a look at the settings in your Identity Provider.

The application that is connected to the Identity Provider, in this case WebCenter is called the “Service Provider”.

SAML can be used to provide a “Single Sign On” experience. Since the Identity Provider has complete control how it authenticates the user it can also decide to remember users which already authenticated that day. The Identity Provider can then decide to skip the authentication for other applications and directly log the user in. This results in the user having to enter his credentials only once and he does not get asked again when he is using different applications. (”Single Sign On”)

You need a license to be able to use SAML in WebCenter.
The latest version of the SAML plugin is installed together with WebCenter. (since WebCenter 18.1)

Next to SAML, WebCenter also supports other ways of authenticating to WebCenter (LDAP, Token, …). More details can be found in the WebCenter documentation.

FAQ: Can I authenticate with <insert application to provide authentication here> to WebCenter?

Check whether the application supports SAML 2.0. If it does, then it should work. Customers have successfully configured SAML in WebCenter to work with with Okta, ADFS (Active Directory Services), Shibolleth, Ping Federate, and others…

FAQ: Does WebCenter support <insert feature here> related to passwords, two factor authentication, single sign on, … when using SAML?

As mentioned above the Identity Provider gets complete control to authenticate the user in any way you can think of. WebCenter does not need to do anything. Check the documentation of the Identity Provider to see what it supports.

Things to know:

CFR 21 part 11 - support for “Password recheck when approving a document or completing a task”

This is a requirement for Life Science customers (CFR 21 part 11). Before WebCenter 20.0 support for password recheck when using SAML was rather limited, especially when using SAAS. Since WebCenter 20.0, password recheck can be turned on in the SAML configuration. Turning it on will show the log in page of the Identity Provider every time the user needs to sign a task or approval. The flag "forceAuthn" will be passed to the Identity Provider to tell it to show the login page and require the user to re-authenticate even if the user is already logged in.

The fallback described below that was available for previous versions of WebCenter is also still available.

When using a version earlier than WebCenter 20 it is possible to comply with the standard by configuring a second type of authentication in WebCenter which will be used for doing the password re-check. This second authentication can be basic password authentication or LDAP (note that LDAP is not supported on SAAS systems). More information about the password re-check fallback option can be found under section “7.12.5 Digitally Signatures for SAML users” in the WebCenter 18.0 release notes which can be found here. When WebCenter basic password authentication is used for the second authentication method (this will be the case on SAAS), each user will need to maintain two sets of passwords: one for SAML and one for approving documents/completing tasks.

SAML and ArtiosCAD Enterprise (or other WebCenter Connectors)

The ArtiosCAD Enterprise WebCenter Connector and other WebCenter Connectors do not support SAML authentication. When SAML is configured for WebCenter it cannot be configured as the primary authentication method when ArtiosCAD also needs to connect. ArtiosCAD users need to use Basic Password Authentication or LDAP. (See also “Finalization – SAML as Default”)

It is possible to still use SAML for users using WebCenter. They however need to click a button on the WebCenter log in page go to the actual login page provided by the Identity Provider.

In the new WebCenter Connector which is under development users will be able to authenticate using SAML.

Typical Flow of a SAML configuration

The goal is to exchange all the information needed to configure both systems and get them to communicate with each other. Typically, the whole integration process is completed first on a test system, after which all the steps are repeated for production.

Preconditions Checklist

Before we can start with configuring SAML we need to be sure that WebCenter will not move to a different URL anymore. (It simplifies things)

☐ WebCenter needs to be running on its final URL. This URL should be using https://.
☐ The information above ("things to know") was provided/discussed.

Initial Meeting

An initial meeting should be held with the representatives from the customer side responsible for maintaining the Identity Provider and someone from Esko who will do the configuration of the WebCenter plugin. In this meeting the desired authentication flow and various technical aspects are addressed. At the end of this meeting, both parties agree on:

  • Authentication flow
    (i.e. Which SAML Binding will be used?)
    • WebCenter supports both Post and Redirect bindings (and “Unsolicited URL”). Any of these can be selected. What is selected depends on what the Identity Provider supports. The default in WebCenter is POST. In case you don’t know what to choose, it is best to leave it on the default.

FAQ: Does WebCenter support Service Provider-initiated or Identity Provider-initiated sign-on?

Both are supported.

Note though that if you click on a link in an email, you will be redirected to a specific page in WebCenter. WebCenter (Service Provider) will notice that the user is not logged in and initiate the log on. After the user is authenticated, WebCenter will redirect to the correct page. Clicking links in email notifications will, thus, always be “Service Provider” initiated.

Interestingly though, WebCenter can be configured to start “Post”, “Redirect” but also “Unsolicited” authentication. Note that if you choose “unsolicited” in WebCenter, to the Identity Provider it will look like an Identity Provider-initiated sign-on as WebCenter will simply redirect to the page that starts an Identity Provider-initiated sign-on. (even though it was in fact initiated by WebCenter)

FAQ: Do I need to use a specific URL to authenticate with SAML or does any URL work?

Any link to WebCenter will redirect to the login page if the user is not logged in. This can be the SAML login page if the system is configured that way (see also “Finalization”). After authentication, the user will be sent back to the page they wanted to visit. This is especially useful for email notifications which direct users to a specific page. No additional configuration needs to be done for this to work.

  • Security
    (i.e.: What should be signed or encrypted? How will the certificates / keys be exchanged?)
    • Generally, only the Authentication Responses sent by the Identity Provider are signed (one certificate generated by the Identity Provider side).
    • Since both WebCenter and the Identity Provider should have https, additional encryption is not needed (and not supported by WebCenter).
    • WebCenter can also sign Authentication Requests. Unless specifically requested this is not turned on as it generally does not add any additional security and is complicated to configure.

FAQ: To leverage automatic updates, Can the trust be built from a Federation Metadata URL?

Yes, the metadata URL from WebCenter can be used directly from the customer Identity Provider configuration. Also, the other way around, WebCenter can be configured with the metadata URL from the Identity Provider system.

For more details see section "How to handle expiration of certificates?".

  • IdP Server
    (i.e. What brand of IdP server will be used? ADFS, Shibboleth, etc.)

  • User Identification
    (i.e. How will the WebCenter username be specified in the AuthnResponse)
    • Usually WebCenter takes the username from the NameID parameter, but the plugin can be configured to use any specific SAML Attribute/Claim sent in the response.

FAQ: What do we need to include for the NameID (and format)?

Usually just put the WebCenter username in the NameID. The format can be anything. WebCenter supports a lists of  NameID formats, the default is “…nameid-format:unspecified”. In case you don’t know what to choose, it is best to leave it on the default.

  • User Management
    • How will users be created in the system? Should user provisioning be turned on?
      Take into account that some settings cannot be configured when creating a user using User Provisioning so you might not want to turn it on. See FAQ below.
    • Next to User Provisioning (User Creation), users can also be automatically added/removed from a list of groups every time they log in (“Synchronize User Groups on Login”).

FAQ: Do the users need to be created in WebCenter before he can log in? / How will users be provisioned into the platform?

While you can use User Provisioning, we believe it is best to create all users in the system beforehand. (see also: “FAQ: Can I configure the WebCenter menu of a user created by the SAML User Provisioning?” below)

Our suggestion is to turn off “user provisioning” and have a procedure to have the users created before they enter WebCenter for the first time. That way they can be created with the correct menu, … (see also next FAQ about the limitations of User Provisioning)

Creating users can be done manually or by using the WebCenter SDK or by using the integrate with WebCenter node.

FAQ: Can I configure the WebCenter menu of a user created by the SAML User Provisioning?

No, this is currently not possible. There are plans to improve user provisioning in future versions of WebCenter.

User Provisioning is supported in the SAML plugin. The SAML plugin can automatically create users which are not yet in the system when they log in for the first time. You can provide the username, their profile information and the groups they need to be in. However, as you can currently not configure his menu he would end up being logged in with the default WebCenter menu which could confuse the user.

FAQ: Are there any other SAML attributes/claims/transformation requirements/group claim… that we need to send over?

(other than NameID, see above)


Unless User Provisioning is enabled on the WebCenter side (see also FAQ above), in that case you need to send:

and optionally:
WCR_USER_GROUPS – the user will be added to these WebCenter groups when he is created

Or if Synchronize User Groups on Login is enabled you need to send:
WCR_USER_GROUPS – the user will be added to these WebCenter and removed from ALL groups which were not passed - whenever he logs in

Exchanging Information

After the initial meeting both parties exchange a template exchange a template that requests all the needed technical details in order to configure the SAML SSO integration from their side.

The following documents can be used for this:

Information needed to configure WebCenter = provided by Identity Provider side:

Information needed to configure Identity Provider = provided by WebCenter:

To fill in the WebCenter document, have a look at section "Collecting information to send to the Customer" below.

Testing Meeting

After exchanging the information and configuring both sides, a meeting should be set up between both parties to test the configuration and check whether it works as expected.

FAQ: How can I check that the SAML configuration I entered is correct?

WebCenter cannot check whether the configuration is correct. The only way to know is to try it out and see whether it works.

If it does not work, see Troubleshooting below.

FAQ: How to remove the WebCenter log in page and go directly the SAML one?

After it is validated that a user can sign in using SAML, the WebCenter log in page can be removed. To do this, see the “Finalization” section below.

If the configuration works for test, the steps can be repeated for the production environment.

SAML Plugin Configuration

After creating the SAML plugin instance in WebCenter you can go to the configuration page of the SAML plugin:

Collecting information to send to the Customer

The information needed to configure the Identity Provider can be found at the bottom under "WebCenter Service Provider Details".

The Entity Id and Assertion Consumer URL are automatically generated based once the configuration is saved.

  • Entity Id is just a name to identify this WebCenter and can be anything as long as it is communicated correctly to the customer (even though by default it looks like a url). Since it is a "name", backslashes do matter!
  • The Assertion Consumer URL is the url of WebCenter to which the customers authentication service (Identity Provider) needs to send it's AuthnResponses. This is automatically generated based on the url you use to access WebCenter. Hint: make sure this is https!

Both are also in the metadata xml generated by WebCenter (see below).

Watch Out! Configure the WebCenter SAML plugin over https!

Make sure to access the configuration of the SAML plugin in WebCenter over its final URL. If you do so the plugin will automatically configure information related to the URL (Assertion Consumer URL) correctly.

Below that are some settings which can be turned on/off.

  • Use URL Parameters – can just be left on.
  • User provisioning has been discussed above (see FAQ under “Initial Meeting”).
  • Same for the “Synchronize User Groups on Login” (see “Initial Meeting”).
  • “Sign Authentication Requests”, (see “Security” under “Initial Meeting” above).

After this, the WebCenter metadata xml can be generated by clicking the button WebCenter Service Provider Metadata. The metadata can be sent to the customer either by URL or by file.

Login page is shown when clicking the "metadata" link?

If you get logged out when clicking the “metadata” link in the SAML configuration, the SAML configuration is probably not “enabled”.

Go to the SSO instances page and enable the SAML instance, then try again.

Configuring the SAML plugin

After receiving the other side of the information (from the Identity Provider side), the top part of the SAML plugin “Identity Provider Details” can be configured.

The SAML Profile should have been discussed during the “Initial Meeting” above. Same for the “Links WebCenter Username to:”.

 The rest of the configuration involves uploading the metadata by URL or, by file - together with the correct “Identity Provider Entity Id” that was received from the Identity Provider side.

FAQ: What to do with the certificate from the Identity Provider side?

Nothing. It is also part of the Metadata XML. Uploading the Metadata XML will in WebCenter will also correctly configure the certificate.

FAQ: What to do if WebCenter cannot access the metadata by URL?

Short answer: Configuring metadata by URL is the preferred approach, but if it does not work we advise to simply upload the metadata by file.

If WebCenter has trouble reading the metadata when you provide it by URL, but can access the URL just fine from the browser on the application server, then, there is a missing certificate. It is possible to add the missing certificate to the Java keystore used by the WebCenter Application server.

It is advises to upload by URL whenever possible because it makes handle expiration of certificates easier. Instead of having to re-upload the metadata, it only takes a re-save of the configuration page and WebCenter will re-download the metadata at the given URL (one click). See also “How to handle expiration of certificates?” below.

The WebCenter SAML plugin used to have a feature which would make the SAML plugin re-download the metadata on a regular basis if the metadata was provided by a URL. This means you did not even need to update the metadata in WebCenter when the certificate expired. WebCenter would update the metadata on its own. This feature however has been removed because it was unreliable and introduced a memory leak.

If you do want to configure by URL and install a custom certificate to download the metadata by URL, details can be found here (the page is currently accessible by Esko associates only) under “How to install a custom certificate to download the metadata of the IdP by URL? / WebCenter does not use custom root certificate installed in Windows.”

Finalization – SAML as Default

On the SSO configuration page you can make SAML the default by changing the priority to 1. This has advantages and disadvantages. The right choice depends on the customer.

When configuring SAML as priority 1, a user which is not yet logged in and goes to any page in WebCenter will never see the WebCenter login page anymore.


  • When the user follows a link to WebCenter he will immediately see the authentication page of the Identity Provider.
  • If the user already entered his password on the Identity Provider for some other service they will never see any login page and immediately go to their landing page in WebCenter (“Single Sign On”, see also “Introduction”)

FAQ: I have configured SAML with priority 1. How do I access the WebCenter login page?

To authenticate without SAML when SAML is configured with priority 1, users must explicitly go to https://<url-to-webcenter-of-customer>/<instance>/login.jsp to see the WebCenter login page. After that they specifically need to click the button of the type of log in they want to use. Clicking the Login button will redirect to the SAML login page again (since it has priority 1).

Make sure you make the correct button visible in the “SSO Instances” page in WebCenter by checking the correct Listed checkbox.

This brings us to the disadvantages:

  • If there are users that need to use the system that cannot login using SAML (e.g. external individuals using the same system), they have no way of authenticating anymore. They could still go to the login page (see FAQ above), but this is not practical for email notifications which would always redirect to the SAML login page. You could however link to the WebCenter login page from the SAML login page (adding a button for external people).
  • When using ArtiosCAD Enterprise or any other connector, SAML cannot be configured with priority 1. (see also section “Things to know”)
  • If there is additional information (like how to get started) configured on the WebCenter log in page, this will no longer be seen by users as they directly go to the SAML login portal.

It is also a valid choice to not put SAML as priority 1. In that case the user will always land on the WebCenter login page. If he wants to authenticate using SAML he has to click a button first.

SAML as default and logout URL

When SAML is configured as priority 1, the logout URL should also be configured in the SAML plugin. Otherwise users will not see the WebCenter login page anymore unless they log out. Seeing the WebCenter login page (not the page they are used to) only after log out may be confusing. Additionally, clicking the login button on that page might log them in again without providing any credentials (because of “Single Sign On”).


Following the instructions in this article should prevent you from getting into trouble, but of course, it can always happen.

I see an error on the login portal (Identity Provider Side). What now?

Usual causes:

The information was not correctly exchanged. The Identity Provider has different information than the Service Provider.


  • Check the settings in WebCenter. Make sure the "NameID" format is set to its default value "urn:oasis:names:tc:SAML:1.1:nameid-format:unspecified" (unless discussed otherwise).
  • Check the settings on the Identity Provider side, check that the Entity ID matches with the value from WebCenter.

If you don’t immediately find the cause, you could investigate the log files of the Identity Provider for more information or use a SAML Tracer to see what information is sent between WebCenter and the Identity Provider.

I see an error on the WebCenter login page (Service Provider Side). What now?

This is a good sign, usually this means the configuration is almost working!

Solution: Investigate the WebCenter server.log file for an exception. There will be one.

Cause: Potential causes:

The user does not exist in WebCenter.

If you don’t immediately find the cause, you could also use a SAML Tracer to see what information is sent between the Identity Provider and WebCenter.

After authenticating I end up on a different WebCenter server:

Cause: The configuration in the WebCenter SAML plugin is probably from a different server. This can happen when cloning a database from another server and overwriting everything. The previous configuration of the SAML plugin is lost.

Solution: Reconfigure the WebCenter SAML Plugin.

More Q&A

How to handle expiration of certificates?

WebCenter does not automatically poll the URL for updates. To update the metadata the save button needs to be clicked in the configuration.

Certificates expire and need to be replaced before that happens.

Usually, when configuring SAML in WebCenter there is only one type of certificate, the Identity Provider signing certificate. This certificate is provided by the Identity Provider (customer) inside the metadata xml. Sometimes the customer also sends the certificates separately in a zip, but these can be ignored. We only need the one in the metadata xml. (the ones in the zip and the metadata xml are identical anyway)

The customer generates the new certificate some time before the old one expires and sends a mail to all involved parties about the certificate that will expire. At that time there are two (Identity Provider signing) certificates: the old one which is still in use, and the new one which should be used as soon as the old one expires.

Note: WebCenter will always require you to do something to apply the new certificates. The customer might indicate in the email that he thinks no update is required and the customer might think that WebCenter will update automatically, but that is not the case. WebCenter at least requires you to click Save. WebCenter doesn't have functionality to automatically re-download updated metadata information at regular intervals, you need to manually Save.

Ok, so how do we do the update? Usually, the update is really simple:

  1. You got the mail from the customer which tells you that there is a new certificate that needs to be deployed.
    Check if the email somehow indicates that the new certificate was created. Look for any of the following:
    • the customer might have zipped the certificates and added them in the attachment,
    • or he added the new metadata xml in the attachment
    • or he provided a link to download the metadata xml.
    If you find any such indication, continue.
  2. Note: it is always possible to do the update at the time indicated by the customer by skipping to the step [Weekend Update] below. However, usually it is not necessary to wait till the last moment and you can just do the update whenever it fits for you. WebCenter can automatically switch to the new certificate when the old one expires if it knows about both. The following steps will tell WebCenter about both certificates so that it will do the switch automatically when the time comes. Continue with the next step.
  3. Log into WebCenter as an admin.
  4. Check if the SAML plugin is configured by URL. You can see this in the configuration page, just check whether the "Identity Provider Metadata" URL field is filled in.

    1. If that is the case, just click "Save" and if no error occurs skip to the "[Multi-certificate Check]" step below.
      If an error occurred, check "What to do if WebCenter cannot access the metadata by URL?" elsewhere in this KB article and as mentioned in that section, download the metadata from the url and try uploading that file.
    2. If the URL field is not filled in, then the identity Provider Metadata was uploaded by file. This could be for a couple of reasons (see also "What to do if WebCenter cannot access the metadata by URL?" elsewhere in this KB article). It makes the update more risky as there are a more possibilities for making mistakes. (and making any kind of mistake would bring down authentication on production)
      1. If (and only if) the mail of the customer contains a url (1) to the metadata xml:
        • Download the metadata from that url. Make sure that when downloading any strange browser extensions are turned off in your current browser (I have seen browser extensions change the xml in the past which will break everything). Upload the downloaded metadata xml under the "Identity Provider Metadata" field in WebCenter and Save. Continue to the "[Multi-certificate Check]" step below.

          (1) FYI: Why does it make a difference whether the metadata is available by URL?
          Some SAML systems provide a system where they automatically re-download the metadata xml at regular intervals. WebCenter does not implement that functionality, but it still means that any metadata provided by URL should always be up to date. WebCenter doesn't download it automatically, but other systems might still download it at random intervals. This means we can re-upload it at any time without worrying about breaking anything. The metadata from the url should always be valid at any time.

      2. IF the mail of the customer does NOT contain a url to the metadata xml but instead provides the metadata xml only as an attachment, skip to the "[Weekend Update]" step below.

  5. [Multi-certificate Check] Ok, if you got to this step by following the instructions above, what we did now was check that the metadata was provided by url and then re-upload the metadata xml (by url of by file). Note that only the "old" certificate is still used at this moment (it didn't expire yet) so the customer is not required to already have both certificates in the metadata xml (only the "old" one should be there for sure). However, usually both certificates are already in the xml which makes our life easier.
    We can now easily check whether both certificates were already in the metadata and if so, we are done:
    1. Look on the page. Check if there are two certificates available. Check the expired date of both certificates. One should expire in a couple of days/weeks. The other one should only expire in a couple of years.
    2. If that is the case, you are done! Certificate update successful! WebCenter will use the old one till it expires and then, automatically start using the new certificate.
    3. If you only see the old certificate, you are out of luck, continue with the next step...

  6. [Weekend Update] If you got to this step, wait till the time indicated by the customer (e.g. in the weekend, when the certificate expires) to do the update.
  7. Log back in into WebCenter as an admin at that time.
  8. Check if the SAML plugin is configured by URL. (see step 3 above for details how to see this)
  9. If the SAML plugin is configured by URL, click "Save". If no errors occurred, the new certificate should be available in WebCenter now. If an error occurred, check "What to do if WebCenter cannot access the metadata by URL?" elsewhere in this KB article (and as mentioned in that section, try uploading by file).
  10. If the SAML plugin is NOT configured by URL, upload the new metadata xml under the "Identity Provider Metadata" field in WebCenter and Save. The certificate should now be updated.

Other Certificates (Usually not the case):

In the rare case that a signing certificate was configured on the WebCenter side (option “Sign Authentication Requests”) a new certificate needs to be generated and configured in the SAML plugin. See “How to configure “Request Signing”?” below.

A third certificate which can be configured is the certificate used to download the metadata by URL. For details see “What do do if WebCenter cannot access the metadata by URL?” elsewhere in this article.

Can I authenticate an SDK call using SAML.


SAML requires the user to authenticate itself in a browser. It does not support a way for a machine to authenticate. If you want to authenticate as a user, you could have a look at token authentication. More details can be found in the WebCenter SDK Documentation and here (page is accessible by Esko associates only).

Does WebCenter support “Single Sign Out” / “SAML Logout”?

No. If you logout in WebCenter it will just log the user out of WebCenter. WebCenter does not support “Single Sign Out” / “SAML Logout”.

This means that if you would visit another page in WebCenter, the Identity Provider would still remember you and you would be logged in into WebCenter immediately.

The SAML plugin in WebCenter does allow configuring the page that the user will end up on after logging out.

Can the "Load-balancer"/"reverse proxy"/"SSL Web Gateway" authenticate the user in WebCenter?

Firstly, WebCenter is not designed to run behind a "Load-balancer"/"reverse proxy"/"SSL Web Gateway". There are many things to keep in mind. Getting WebCenter running behind a reverse proxy, however, is a challenge on its own. More details can be found in the following KB: 

If you want the load balancer to authenticate the user (instead of the user itself), this is currently only supported if the load balancer supports SAML. If it does you can connect it to WebCenter like any Identity Provider.

How to configure “SAML Request Signing”?

WebCenter can sign Authentication Requests. Unless specifically requested this is not turned on as it generally does not add any additional security and is complicated to configure.

Generating a new certificate (and Java keystore) can be done by following the steps described in our internal “SAML User Manual”. After request signing is turned on, the metadata from WebCenter contains the public certificate and needs to be reconfigured on the Identity Provider side.

Appendix: Configuring ADFS

Once the necessary information has been exchanged, (see section “Exchanging Information”) both the WebCenter side and the Identity Provider side can start setting up the configuration.

For details about configuring the WebCenter side, see section “SAML Plugin Configuration”.

The following steps can be used to configure ADFS:

Step 1: On your ADFS Server, Open up AD FS Management.

Step 2: Right click on Relying Party Trusts and select Add Relying Party Trust.

Step 3: In the Select Data Source step in the wizard, choose one of the two “Import data” options. Since Esko will provide the metadata URL, usually you take “by URL”. (but “from a file” works too)

(See section “Collecting information to send to the Customer” above)

Step 4: Enter a Display name and click Next

Step 5: Go through the other options of the wizard.

Step 6: After the wizard is finished, open the Claim Rules dialog. This can be done by right-clicking on the created Relying Party Trust.

Step 7: WebCenter needs at least the username to be passed. Usually in the Subject Name ID field. (see also “Initial Meeting”)

Click Add Rule… in the tab Issuance Transform Rules.

In the wizard that follows, map the LDAP AttributeSAM Account Name” on the Claim “Name ID”. (both should be available in the respective dropdown)

Step 8: In case User Provisioning is turned on in WebCenter, more claims need to be added. For more details, see section “Initial Meeting” above.

Article information
Applies to

WebCenter 14 and later



Last revised