Using DocDB with single sign-on

Intended for:

This article is intended for DocDB users who want to use single sign-on (including Fermilab Services account) to access a DocDB instance.

Scenario/Use case:

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

Instructions:

DocDB instances can have up to three versions so they may be accessed by the following three access methods: single sign-on (including Fermilab Services account), private (DocDB-specific username/password), or certificate (CILogon, CERN, OSG). Users can pick an authentication method from their DocDB homepage, which will have a URL similar to https://xyz-docdb.fnal.gov/ and look similar to:

1. Instructions for users who cannot use single sign-on

Users who do not have a Fermilab Services account, or who are trying to access a DocDB instance that has federated access enabled (see Accessing DocDB with Federated ID Single Sign-On (SSO)), but do not have an external federated ID from an outside organization approved by Fermilab, may use the certificate version of the site with a CERN, OSG or non-Fermilab CILogon certificate. For instructions on how to access DocDB using a certificate, see these articles:

Some DocDB instances have private access (DocDB username/password) enabled. Users who want to use this method should contact their DocDB instance administrator for the password.

Users with Fermilab CILogon certificates will be automatically redirected to the SSO login page. Once at the SSO login page, they can choose whether to use their Services account username and password or their Fermilab CILogon certificate to gain access.

If your DocDB instance has federated access enabled, users with CERN CILogon certificates may also be automatically redirected to the SSO login page.

Using single sign-on has the advantages that you do not have to remember a DocDB-specific password or get/renew a certificate, and you can be a member of multiple groups.

NOTE: CERN, OSG or non-Fermilab CILogon certificate DocDB users: If your certificates expires, is removed or otherwise becomes invalid, you will automatically be redirected to the SSO version of your DocDB. As soon as you renew and load a valid CERN, OSG or non-Fermilab CILogon certificate in your browser, the redirect will stop, and you can continue to use the certificate version of DocDB as you have in the past.

2. Instructions for users who want to switch to single sign-on

For most DocDB instances, you need to have a Fermilab Services account in order to use single sign-on authentication to access a Fermilab-hosted DocDB. Once you have a Fermilab Services account, you can go directly to the single sign-on (SSO) version of your DocDB (if SSO is enabled for your DocDB) by going to your DocDB's homepage (similar to http://xyz-docb.fnal.gov/) and clicking on the "Single Sign-On" link or by following an email or webpage link to the single sign-on version of your DocDB.

Some DocDB instances have federated access enabled. See Accessing DocDB with Federated ID Single Sign-On (SSO) for information on how to sign in with an external federated ID and which organizations are currently approved.

The SSO version of each DocDB has a URL similar to https://xyz-docdb.fnal.gov/cgi-bin/sso/...

2.1 If you were previously a private DocDB user:

By default, when you first use single sign-on to access DocDB, you are not a member of any DocDB groups and can view only public documents (unless your DocDB administrator has pre-arranged one or more groups for you).

When you log in to a private DocDB, you are actually logging in as a member of a single DocDB group. When you log in using your single sign-on account, you’ll want to be a member of that same DocDB group so you can access the same documents. You need to apply for your DocDB SSO account to be a member of that same DocDB group if you are not already listed as a member of that group. To check which groups you are a member of and to be added to more groups, follow the instructions under “Checking and adding DocDB groups in the single sign-on version of DocDB” near the bottom of this page.

Besides going directly to the SSO version of your DocDB via the "Single Sign-On" link on your DocDB homepage, you can change a private DocDB URL to an SSO DocDB URL by just changing “private” to “sso”. Below is an example of private and SSO DocDB URLs for the same page:

Private DocDB URL: https://xyz-docdb.fnal.gov/cgi-bin/private/ShowDocument?docid=1234
SSO DocDB URL: https://xyz-docdb.fnal.gov/cgi-bin/sso/ShowDocument?docid=1234

2.2 If you have a Fermilab CILogon certificate DocDB account:

You will automatically be redirected from the certificate version to the SSO version of your DocDB. The certificate version of each DocDB has a URL similar to https://xyz-docdbcert.fnal.gov/cgi-bin/cert/...

Your certificate account permissions and settings will automatically be transferred to your SSO DocDB account so you can continue to use the SSO version in the same way as you used the certificate version (including signing documents) without having to apply for access or take any other steps.

2.3 If you have a CERN, OSG or non-Fermilab CILogon certificate DocDB account

Follow these instructions for each DocDB you use: Request a transfer from a certificate account to a Single Sign-On (Fermilab Services) account. If your DocDB has federated access enabled and you have a CERN CILogon, you may also automatically be redirected to the SSO version of your DocDB. You can follow the same instructions to request a transfer from your certificate account to your preferred Single Sign-On account.

This will transfer all your certificate DocDB permissions and settings to your SSO DocDB account. After the transfer, you should use the SSO version of your DocDB going forward. If you used your certificate DocDB to sign documents before, you will need to use your SSO DocDB to sign documents after the transfer.

If you want the certificate version of your DocDB to automatically redirect to the SSO version, you can make this happen by removing the certificate from your browser. When the certificate version of DocDB does not receive a certificate or receives an invalid or expired certificate, it automatically redirects to the SSO version.

2.4 Checking and adding DocDB groups in the single sign-on version of DocDB:

Besides having permissions transferred from a certificate, SSO DocDB users will automatically receive permissions for any Services groups they are members of that their DocDB administrators have associated with groups within their DocDB. For example, for the Computing DocDB, users who are in the Services group "CS Employees" will automatically have permissions from the "cdweb" group in CS DocDB.

To check which DocDB groups you are a member of:

Go to the SSO landing page for your DocDB; (URL similar to https://xyz-docdb.fnal.gov/cgi-bin/sso/DocumentDatabase).
Click on the "Your Account" button in the navigation box on the left.
On the "Your Account" page, the DocDB groups you are a member of are listed under the heading "Member of Groups". This includes groups from any DocDB account transfer, groups associated with your Services account and groups assigned specifically within DocDB.

To apply to be added to more DocDB groups than you have been automatically granted:

Go to the SSO DocDB landing page for your DocDB; (URL similar to https://xyz-docdb.fnal.gov/cgi-bin/sso/DocumentDatabase). Examples:
- https://esh-docdb.fnal.gov/cgi-bin/sso/DocumentDatabase
- https://microboone-docdb.fnal.gov/cgi-bin/sso/DocumentDatabase
- https://docs.dunescience.org/cgi-bin/sso/DocumentDatabase
- https://beamdocs.fnal.gov/cgi-bin/sso/DocumentDatabase
Click Apply to Groups in the navigation box on the left.
On the groups application page, select the groups to be added.
In the "Notes" field, type a note identifying yourself and/or explaining why you need to be added to the selected group(s).
Click Apply for access.
Your request will be emailed to your DocDB's administrators. You will receive an email after they've approved your request, or they will contact you if they have questions or your request cannot be granted.

3. Users who have multiple single sign-on accounts.

If you have multiple single sign-on accounts (such as a Fermilab Services and a CERN Computing account) and your DocDB instance has federated access enabled, you should pick one account to use for access. Your accounts in DocDB are not connected, so permissions are not automatically shared between accounts. This means that if you sign in with Fermilab SSO and request access to the "xyz" group, and then later sign in with CERN SSO and try to view documents in the "xyz" group, you will be denied access.

You can follow these instructions for each DocDB you use to consolidate your SSO accounts (if you have signed in with multiple accounts in the past): Request a transfer from a certificate account to a Single Sign-On (Fermilab Services) account. In the notes field, simply indicate which account should be transferred to your preferred account, e.g. "Please transfer permissions from my Fermilab SSO to my CERN SSO".