Configuring a SAML (Single Sign-On) authenticator can sometimes be a bit challenging due to the vast array of SSO IDP (Identity Provider) configurations out there. Once you've received the metadata file from your IDP you can begin configuring a SAML authenticator in TechDoc.
Log into your Document Manager and navigate to Admin->Create Authenticator. Give the authenticator a name and then select SAML from the drop down. Now you'll need to enter the service data to complete the configuration. This is done by using flags to specify the various options. As with all authenticators, you may leave the service data field blank and click OK to display it's full usage. The only configuration flag that is mandatory here is -m. This flag is used to specify the metadata file you received from your IDP and placed into your TechDoc etc folder. To specify the metadata file, you should enter -mFILE_NAME.xml where FILE_NAME is replaced with the name of your metadata file. After you've done this, you may click OK and test the authenticator to see if it works. If the authenticator fails with any error, enable logging by specifying the service data flag -l (lowercase l). This will add additional logging to the TechDoc logs and can be very helpful when trying to resolve an issue. Remember once the issue has been resolved, remove the -l flag as your TechDoc logs can grow very quickly. Here are a few of the issues you may run into if the authenticator fails:
Log in failed because there was a problem with this SAML authenticator's service data. An unexpected error occurred while parsing the SAML metadata file.
This typically is caused by a malformed/corrupt metadata file. Replace your metadata file with a fresh copy from your SSO IDP.
An error occurred while parsing the SAML response. The SAML response contains an unencrypted assertion but this authenticator requires it to be encrypted.
You may receive this error if the IDP is not configured to encrypt it's assertions (responses back to TechDoc). We highly recommend that the IDP change it's configuration to encrypt it's responses because it adds a second layer of security. However, we realize that it may not be an option for all environment so if you need to accept unencrypted responses, just add the service data flag -e. We never recommend using this setting unless you have to.
An error occurred while parsing the SAML response. The SAML response contains an unsigned assertion but this authenticator requires it to be encrypted.
You may receive this error if the IDP is not configured to sign it's assertions (responses back to TechDoc). We highly recommend that the IDP change it's configuration to sign it's responses because this is the first layer of protection for SAML-based SSO. However, if you are just testing and would like to temporarily accept unsigned responses, you may specify the service data flag -s. We never recommend using this setting unless you have to.
I'm receiving errors about the digest method used for signing. What should I do here?
The TechDoc SAML Authenticator defaults to using SHA-1 for it's signing digest method, but it does support higher levels. If you encounter a situation that requires a higher digest level, you may specify the flag -D followed by one of the following:
- SHA256
- SHA384
- SHA512
I'm receiving an error saying the SAML response is no longer valid.
This is typically caused by the system clock's time being incorrect on either the TechDoc server or SSO IDP. We highly recommend that the culprit server correct it's time. However, if you are unable to correct it for some reason, you may adjust the time tolerance allowed by the TechDoc SAML authenticator. By default it allows a 5 minute window meaning the SSO IDP can be up to 5 minutes faster than your TechDoc server or 5 minutes slower. If you need a greater tolerance, you may specify the -t flag followed by the number of minutes. For example -t30 would allow a 30 minute window.
I see the error "Failed because the SAML authenticator did not return any user attributes". What does this mean?
You'll want to view the TechDoc logs and look at the SAML response to make sure you see user attributes listed. At a bare minimum, we require that the unique ID of the user be returned from the SSO IDP. If you do not see any attributes listed, you'll need to contact your SSO IDP and get them to make configuration changes to return user attributes. If you do however see user attributes listed, make sure the unique ID is listed as "uid". If the unique ID is listed with anything else, you'll need to let TechDoc know what it is by using the -n flag followed by the unique ID name. For example -nauid would say the unique ID is specified using auid.
It appears to work but I get a message saying an account cannot be used because these is no TechDoc account that authenticates using...
This message simply states that your SSO account needs to be tied to your TechDoc user account before you can use SSO to log in. Log in to the TechDoc DM and modify the user account you wish to connect to an SSO account. On the modify user screen, select your SAML SSO authenticator from the drop down and then enter your unique ID as returned by the SSO IDP. If you are not sure what your unique ID is, refer to the TechDoc logs and see whats being returned or contact your SSO IDP help desk.
It looks like we're up but when users click "Log In", they still have to hit the button to use SAML SSO. I want everyone to automatically authenticate against SAML SSO when they click "Log In"...
Once you have all your users set up for using SAML SSO, you will probably want to enable full single sign-on. You do this by logging in as a TechDoc Admin and modifying System Properties. You can change DefaultAuthenticator to the SAML authenticator you created. Then when people attempt to log in, it will automatically go to the SSO IDP without making them click the extra button. If you decide you want to disable this feature, simply change DefaultAuthenticator back to Local and then user’s will have to click the extra button again to use single sign-on.
But...
If you run into any other issues, feel free to post them here and we'll be happy to help you out. Please remember this is all about security. If you need to ask us something that contains sensitive information about your security, please do NOT post it here. Instead, email or phone us to discuss security-sensitive details.