ServiceNow Service Management

Intended for:

DocDB instance administrators after single sign-on (including Fermilab Services account) access is enabled on their DocDB

Scenario/Use case:

This article provides instructions for administrating DocDB after single sign-on (including Fermilab Services account) access is enabled.

What's staying the same:

Users of the public and private versions of DocDB and CERN, OSG or non-Fermilab CILogon certificate users can continue using those DocDB versions as before. No changes or actions are required, unless they wish to switch to using single sign-on (SSO).

Your DocDB administrator username and password are still needed for administrative actions. Your Services account username and password can be used to sign into your site but will not work for DocDB administrative actions.

We recommend that you keep using links to the certificate version of your DocDB for both certificate and single sign-on users. This allows you to use a single link for both audiences. Fermilab CILogon certificate users (and users with no certificates) will automatically be redirected to use the single sign-on version of your DocDB, but users with other certificates (CERN, OSG, other organizations using CILogon) will continue using the certificate version via the same link. A separate link will be needed to access your private (DocDB password) DocDB; you should use the same link format as you have always used for your private DocDB.

You can change a link to the SSO version of your DocDB to a link to your certificate DocDB by:

Changing /sso/ to /cert/
Changing https://xyz-docdb.fnal.gov/ to https://xyz-docdbcert.fnal.gov/
i.e. Appending "cert" to the host name (xyz-docdbcert instead of xyz-docdb)

For example, here are SSO and CERT links to the same document:

SSO: https://xyz-docdb.fnal.gov/cgi-bin/sso/ShowDocument?docid=1234
CERT: https://xyz-docdbcert.fnal.gov/cgi-bin/cert/ShowDocument?docid=1234

(where you put in your DocDB hostname instead of "xyz-docdb.fnal.gov", such as cd-docdb.fnal.gov or docs.dunescience.org)

Adding access for users who want to switch to using single sign-on:

Fermilab CILogon certificate users will automatically be redirected from the certificate version to the single sign-on (SSO) version. Their certificate DocDB account settings, permissions and signatures will automatically be transferred to their single sign-on DocDB account. These users do not have to take any steps to apply for access and you don't have to take any steps to grant them access.

You will need to add single sign-on access for OSG, CERN or non-Fermilab CILogon certificate users who have Services accounts and want to switch to using single sign-on. This can be done by transferring their DocDB certificate account (starts with "/DC=") settings to their DocDB SSO account (starts with "SSO:"). Instructions on how to do this can be found in this article: How to handle DocDB 'account transfer' requests.

After their DocDB certificate account settings are transferred to their DocDB SSO account, users should switch to solely using the SSO version of their DocDB. If they remove their certificate from their browser, they will automatically be redirected from the certificate version of DocDB to the SSO version they should be using after the transfer.

For private (shared DocDB group name and password) users who have Services accounts and would like to use them, direct them to use the 'Single Sign-On' link on the homepage of your DocDB. From there they should click the link 'Apply to Groups', where they can request access to additional groups. You will receive a request by email like the one below.

The process is similar to the process for certificate users applying for access, except you must select the appropriate requested groups in the group list. The requested groups are not selected (pre-loaded) for you. As with certificate access requests, also select the action of "Modify", select the username (should look like "SSO:username"), check the "Verify" checkbox, enter your DocDB administrator username and password (not your Services username and password), and then click on the "Modify Personal Account" button to finish.

Then the user will receive an email like the one below, confirming that their request has been granted.

Make switching to single sign-on easier by mapping DocDB groups to Services groups:

If your private or certificate DocDB users wish to switch to using single sign-on to access DocDB, we recommend that you submit a Service Desk ticket to docdb-support@fnal.gov to add a mapping to a Services group for the username (group) most used to access your private DocDB. This is typically your main collaboration group such as "nova" for nova-docdb. This will allow those Services account users to access your DocDB as members of that group automatically. This means those users won't need to apply for access and you won't need to grant it. In the ticket, please include:

URL for your DocDB
Name of the DocDB group (DocDB username used for login)
List of Service account usernames to be members of the new Services group (one username per line)

When the ticket is processed, the new Services group will be created and associated with the same group in your DocDB. Your users' groups will then include the groups they have specifically been assigned to in DocDB (i.e. those listed on your DocDB's "Personal Accounts" page) plus the DocDB groups they are associated with from being members of the new Services group you requested.

This also means some users will have access to your DocDB via Services group associations to your DocDB groups, even if "None" is listed in the "Groups" column on your DocDB's "Personal Accounts" page. There are instructions for users to get a list of groups they are in (by either method) on "Using DocDB after single sign-on access is enabled".

You can see the list of associations from Services groups to your DocDB's groups at:
https://xyz-docdb.fnal.gov/cgi-bin/sso/DocDBInstructions?set=general#authentication
(where you put in your DocDB hostname instead of "xyz-docdb.fnal.gov", such as cd-docdb.fnal.gov or docs.dunescience.org).

Handling expired certificates and removing certificates to switch to single sign-on:

If users have an expired certificate, they will be redirected to the single sign-on version of DocDB. This means:

Fermilab CILogon certificate users will automatically be redirected to the single sign-on version of your DocDB when their certificate expires. This is the desired behavior to allow them to let their certificate expire, and is also the same behavior they see when they have a valid Fermilab CILogon certificate. This allows them to continue using the single sign-on version of DocDB when their certificate expires, with no noticeable change to them.
CERN, OSG and non-Fermilab CILogon certificate users who wish to continue using the certificate version of DocDB will be redirected to use single sign-on when their certificate expires. To use the certificate version of their DocDB again, they just need to remove the expired certificate from their browser and load their renewed certificate into their browser.
CERN, OSG and non-Fermilab CILogon certificate users who have a Services account and wish to switch to using single sign-on can do so by removing their certificate from their browser. Then they will be redirected to use single sign-on, as Fermilab CILogon certificate users are. In addition, they should send a request to their DocDB administrators to transfer their certificate DocDB account settings to their SSO DocDB account.

Viewing "managed" documents (documents with or needing signoffs):

You can view the list of "managed" documents in the SSO version of your DocDB at:
https://xyz-docdb.fnal.gov/cgi-bin/sso/ListManagedDocuments
(where you put in your DocDB hostname instead of "xyz-docdb.fnal.gov", such as cd-docdb.fnal.gov or docs.dunescience.org).

Administrating DocDB after single sign-on access is enabled