authentication.oit.duke.edu Open in urlscan Pro
152.3.72.142 Public Scan

Back to summary

Submitted URL:
http://shib.oit.duke.edu/
Effective URL:
https://authentication.oit.duke.edu/manager
Submission: On April 15 via api (April 15th 2024, 2:44:21 pm UTC) from US — Scanned from DE

Form analysis
0 forms found in the DOM

Text Content

AUTHENTICATION

* Home
* Documentation
* Tools
* My Sites
* Register Site
* OAuth
* Help

AUTHENTICATING YOUR DUKE SITE

RESOURCES FOR GETTING YOUR SITE OR SERVICE PROTECTED BY SHIBBOLETH

In accordance with Duke security offices service authentication statement , OIT
supports electronic authorization to resources via Shibboleth, an open-source
authorization provider created by Internet2, a community of academic, research,
industrial, and governmental institutions.

LOCALLY-DEVELOPED SITES/SERVICES

Guidelines for protecting sites or services developed at or specifically for
Duke.

Before you start

Before you get started with installing/configuring Shibboleth, you need to able
to modify files on your server. If this is not the case, consult with an
administrator so that you can make changes.

Familiarize yourself with the vocabulary

The steps below outline the process of getting your site protected with
shibboleth.

1. Install the Shibboleth Service Provider (SP) software
2. Configuration to protect your site
3. Register your site with the Duke Identity Provider (IdP)
4. Test authentication and authorization

Install Shibboleth Service Provider (SP)
Download

SHIBBOLETH SERVICE PROVIDER (SP) INSTALLATION V3

The following instructions will help you install the Shibboleth Service Provider
(SP) on your application server.

Note: Before you install anything, make sure that you have administrative
permissions on your application server.

You will also need to download a text editor when you start the configuration
phase. Atom or Sublime are good choices.

LINUX INSTALLATIONS (RHEL, CENTOS, & SUSE LINUX ENTERPRISE SERVER)

To install Shibboleth on a Linux machine, use the official RPM from the
Shibboleth team here: https://shibboleth.net/downloads/service-provider/RPMS/

if you are using EL7, an example of the generated config from the link above can
look like this:

[shibboleth]
name=Shibboleth (CentOS_7)
# Please report any problems to https://shibboleth.atlassian.net/jiratype=rpm-md
mirrorlist=https://shibboleth.net/cgi-bin/mirrorlist.cgi/CentOS_7
gpgcheck=1
gpgkey=https://shibboleth.net/downloads/service-provider/RPMS/repomd.xml.key
https://shibboleth.net/downloads/service-provider/RPMS/cantor.repomd.xml.key
enabled=1

1. Once you have downloaded/added the shibboleth repo. Install the Shibboleth
Service Provider (SP) with yum install shibboleth This will install the
latest version of the Shibboleth Service Provider (SP) software. You will
receive confirmation prompts when software is installing. Type y to allow
the installation of the Shibboleth Service Provider software.

2. You can confirm the installation by typing shibd -v in the terminal. You
should see the version number printed out, for example shibboleth 3.0.2

3. If you see the above version or greater, you are ready to move to the
configuration step.

OTHER LINUX DISTRIBUTIONS

The only supported Linux distributions are Red Hat Enterprise, CentOS 6, 7 and
SUSE Linux Enterprise Server 11-SP3, 11SP4, 12SP3, 12SP4

If you are using Ubuntu you can install the Debian package by using the
following command sudo apt-get install libapache2-mod-shib2. NOTE This will
install an outdated version of the Shibboleth Service Provider (SP) with version
2.6.1.

You can reference the Shibboleth Official Wiki page here
https://wiki.shibboleth.net/confluence/display/SP3/LinuxInstall

WINDOWS/IIS INSTALLATIONS

1. Download and install the latest version of Shibboleth from
http://shibboleth.net/downloads/service-provider/latest/. During the
installation, you can choose the installation directory.
2. Depending on your system choose either the win32 or win64 folder.
3. Depending on what you chose above, click the first file ending in .msi to
download.
4. Once the installer has downloaded, run the installer.
5. The installer will walk you through various prompts.
6. One of those prompts will ask you to select the desired location to install
the Shibboleth software. The default location is C:\opt\shibboleth-sp\
7. Select Configure IIS7 module when prompted for directory installation. The
installer will add an ISAPI filter and an SSO extension.
8. Restart IIS iisreset. You can now move to configuring your Service Provider
(SP).
9. For more information:
https://wiki.shibboleth.net/confluence/display/SP3/Install+on+Windows

MAC OS INSTALLATIONS.

Please visit the Shibboleth Website for information on Installing Shibboleth for
Mac OS. https://wiki.shibboleth.net/confluence/display/SP3/MacPortInstall

Configure your Service Provider (SP)
Download

SHIBBOLETH SERVICE PROVIDER (SP) CONFIGURATION V3

QUESTIONS?

Please be sure to look through the documents page for common problems.

If you are still having trouble, please visit
https://authentication.oit.duke.edu/manager/register to request help with a
Shibboleth integration.

THINGS TO THINK ABOUT WHEN SETTING UP SHIBBOLETH

Use SSL for your web server (Apache or IIS) - You’re using authentication to
protect your site. If you do not use SSL, you are risking the security of your
website by making it possible for somebody to steal assertions that are created
by the Identity Provider (IdP) for the Service Provider (SP) to consume. Our
generated shibboleth2.xml files assume that you will be using SSL by setting
handlerSSL=true in the configuration.

Anytime you make changes to the shibboleth2.xml or attribute-map.xml files, be
sure to restart the shibboleth service. For Linux, use systemctl restart shibd.
If you are using Windows/IIS, use sc stop shibd_default && sc start
shibd_default.

It is also useful to look at the log files the Shibboleth software creates. For
Linux, the directory is /var/log/shibboleth/. For Windows, look at
C:\opt\shibboleth-sp\var\log\shibboleth.

Specifically, you want to pay attention to the shibd.log file.

VERIFY INSTALLATION

To make sure that you have installed the Shibboleth Service Provider (SP)
correctly, follow the next steps based on your application server operating
system.

This assumes that you used the default directory during installation. If you
chose a different directory, make sure that you can see the Shibboleth files
inside the directory you chose.

1. Make sure the Shibboleth directory exists.

Linux: /etc/shibboleth

Windows/IIS: c:\opt\shibboleth-sp\etc\shibboleth

2. Make sure that the shibd process starts & that the status is active
(running). In your Terminal/PowerShell run the following command:

Linux: systemctl start shibd | systemctl status shibd

Windows/IIS: sc start shibd_default

If you receive an error stating that the shibd service is not found, it means
that the installation did not happen successfully. Otherwise, you are ready to
move to the configuration step.

CONFIGURATION

Inside the Shibboleth directory, you will see a couple of files to which you
will need to make changes.

Files to change:

* shibboleth2.xml
* attribute-filter.xml

On your terminal or command prompt, use the following commands to grab the Duke
Metadata and the Metadata Signing certificate:

LINUX

1. Move into the Shibboleth directory cd /etc/shibboleth

2. Download Duke Metadata:

wget -O duke-metadata-3-signed.xml
https://shib.oit.duke.edu/duke-metadata-3-signed.xml

3. Download Metadata signing certificate: wget -O idp_signing.crt
https://shib.oit.duke.edu/idp_signing.crt

4. Verify that both files were downloaded correctly: ls.

* ls will give you a list of files in that directory. If you see the
duke-metadata-3-signed.xml and idp_signing.crt files, you are ready to make
changes to the shibboleth2.xml file. Otherwise, try the command again or open
the files in your browser and save the files with the appropriate name and
extension, duke-metadata-3-signed.xml and idp_signing.crt inside the
shibboleth directory.

WINDOWS

Using the Command Prompt or PowerShell.

1. Move into the Shibboleth directory cd c:\opt\shibboleth-sp\etc\shibboleth

2. Download Duke Metadata: curl -o duke-metadata-3-signed.xml -k
https://shib.oit.duke.edu/duke-metadata-3-signed.xml

3. Download Metadata signing certificate:

curl -o idp_signing.crt -k https://shib.oit.duke.edu/idp_signing.crt

4. Verify that both files were downloaded correctly: dir.

* dir will give you a list of files in that directory. If you see the
duke-metadata-3-signed.xml and idp_signing.crt files, you are ready to make
changes to the shibboleth2.xml file. Otherwise, try the command again or open
the files in your browser and save the files with the appropriate name and
extension, duke-metadata-3-signed.xml and idp_signing.crt inside the
shibboleth directory

SHIBBOLETH CONFIGURATION

The following steps apply both to Linux and Windows installs.

Time to update the shibboleth2.xml and the attribute-map.xml configuration
files. You’ll find them in /etc/shibboleth if you’re using the Shibboleth Linux
distribution from Duke.

The attribute-map.xml should be ready to use if you’re using the standard
attributes, eduPersonPrinciplaName and eduPersonAffiliation.

SHIBBOLETH2.XML

DEFINE THE ENTITYID FOR YOUR SERVICE PROVIDER

Find the entityID inside <applicationDefaults /> element.

* Replace the entityID value with a unique name that identifies your site.
Remember this entityID as you will use it when you register your site. Leave
the cipherSuites value and add encryption=true similar to the below XML.

The eppn (eduPersonPrincipalName) is the scoped NetID attribute, e.g.
netid@duke.edu. Although eppn may look and sometimes function as an email
address, it is not intended as one. EPPN is a federation identifier that
signifies that a user is coming from Duke and not another institution.

If you are sure you will never need to use non-Duke identities in your
application and want to use the uid attribute or unscoped NetID, make sure you
have requested uid and set REMOTE_USER="uid"

SET THE METADATA SOURCE AND METADATA SIGNING CERTIFICATE.

The shibd service will check for new metadata files periodically and make
updates. The Shibboleth daemon will also reload the metadata file.

* Find the commented out <MetadataProvider /> element and uncomment it by
removing the  comment tags.
* Replace the url value with:
https://shib.oit.duke.edu/duke-metadata-3-signed.xml
* Set the backingFilePath value to duke-metadata-3-signed.xml , replace
maxRefreshDelay with reloadInterval
* Remove the <MetadataFilter type="RequireValidUntil"
maxValidityInterval="2419200"/> element
* Remove the DiscoveryFilter element along with the three children attribute
elements.
* Last, set the certificate value to idp_signing.crt
* Your MetadataProvider element should look like this

SET ENCRYPTION AND SIGNING KEYS

Find the <CredentialResolver type="file" use="encryption"/> element and replace
the values for key and certificate to sp-encrypt-key.pem and sp-encrypt-cert.pem
respectively. By default, these values are already filled out. However, if you
have renamed or want to rename these files, make sure that the names match. The
sp-encrypt-cert.pem is the certificate that you will use during registration.
NOTE: This is not your website SSL certificate.

Optional: As of Shibboleth Service Provider V3, the SP software suggests using
two different keys for the signing and encryption. If you do set the signing
key, make sure to ask the Identity Management team to make the change to sign
assertions for this SP.

SESSION INITIATOR

* Update the Sessions information by setting the handlerSSL="true". This forces
the handler to use SSL and makes stealing session and cookie information more
difficult.
* find the <Sessions /> element, replace it with the following:

* If you are testing on a local environment, then leave handlerSSL="false".
Otherwise leave as handlerSSL="true" for a production environment.

DEFINE THE DUKE SHIBBOLETH IDP

The last section tells your Service Provider (SP) what Identity Provider (IdP)
users will authenticate against.

* find the <SSO /> element and replace the entityID value to:
https://shib.oit.duke.edu/shibboleth-idp

RESTART SHIBBOLETH DAEMON

Anytime that you make changes to the Shibboleth2.xml or any file inside the
shibboleth directory, make sure to restart the shibboleth service.

Linux: systemctl restart shibd

Windows: sc stop shibd_default and sc start shibd_default.

Alternatively, you can restart the shibboleth daemon through the services app by
finding the Shibboleth Daemon (Default).

ATTRIBUTE-MAP.XML

The attribute-map.xml

The standard attributes, eduPersonPrincipalName and eduPersonScopedAffiliation
should have entries in your attribute-map.xml file resembling the below XML.

When you request an attribute to be released, make sure to uncomment that
attribute here.

VERIFY CONFIGURATION

You are now ready to test configuration changes.

1. Restart the shibd service:

Linux: systemctl restart shibd

Windows: sc stop shibd_default && sc start shibd_default. Also, make sure to
restart IIS. iisreset

2. Open a web browser and access your site appending /Shibboleth.sso/Status to
your sites URL. for example, http://localhost/Shibboleth.sso/Status

You should see XML text printed out to the screen. Scroll down to the bottom
and look for the element <Status><OK/></Status>.

You can also see a copy of your metadata at
http://localhost/Shibboleth.sso/Metadata. This will prompt you to save or
open the file. Open the file and you will see your EntityID configured in
the shibboleth2.xml file along with the Assertion Consumer Service(ACS)
value and the sp-encrypt-cert.pem certificate text. You will use these
values when you register your Service Provider (SP) with the Duke Identity
Provider (IdP).

3. Next, access your site using: http://localhost/Shibboleth.sso/Login

If you see a page that says, "The application you have accessed is not
registered with our Identity Provider (IdP).", this means that the
configuration happened successfully and you are now ready to register your
site.

4. If you see any other message besides the above, check the console for
possible problems.

Check problems with shibd -t

If you need help, submit an authentication help request at
https://authentication.oit.duke.edu/manager/register/. An IdM analyst will
look at your request and contact you regarding more details or provide you
with reasonable steps to take to fix your problem.

Collect Service Provider (SP) Information

It is now time to collect information from the Service Provider (SP) you just
configured.

The below items are to be found under the Shibboleth directory on your
application server

Windows default directory is: c:\opt\shibboleth-sp\etc\shibboleth

Linux default directory: /etc/shibboleth

* EntityID: The EntityID in the shibboleth2.xml file.
* Certificate: Find the sp-cert.pem file inside the shibboleth directory. When
registering your Service Provider (SP), make sure you paste the text inside
BEGIN CERTIFICATE - END CERTIFICATE into the certificate field.
* Assertion Consumer Service URL (ACS): The assertion consumer url is usually
the fully qualified domain name plus Shibboleth.sso/SAML2/POST for example:
https://mysite.duke.edu/Shibboleth.sso/SAML2/POST
Download the SAML tracer plugin if you are unsure what the Assertion Consumer
Service URL is.

Register Service Provider (SP)
* Register your Service Provider (SP) with Duke's Identity Provider (IdP)
* We recommend for EntityIDs to follow the naming convention of a URL. For
example, https://mysite.duke.edu

Note:
The EntityID is a unique name that identifies your Service Provider (SP) with
the Duke Identity Provider(IdP). In no way does the EntityID indicate that
your site is using SSL. The EntityID is a unique name specific to your
Service Provider (SP). Take a look at the
Shibboleth Documentation for EntityID naming conventions
.
* If you have more than one environment (test, production), it is possible to
have multiple EntityIDs.

Test authentication and authorization
* The default directory protected by Shibboleth is the /secure path on your
server.
* Using a web browser that is not already logged into Shibboleth, attempt to
navigate to a part of your site that should be protected by Shibboleth. If
everything was configured correctly, you should see a redirect to a login
page that begins with https://shib.oit.duke.edu
* You can now make configuration changes to protect a certain path within your
server. Take a look at our attributes and authorization document to make such
changes.
* If you encountered an error, take a look at our common errors page.
* Take a look at the Shibboleth Documentation for further reference.

VENDOR SITES/SERVICES

Guidelines for protecting sites or services offered by vendors.

Before you start
* Make sure the vendor completes the Vendor risk assessment. This is important
since this will inform us what the vendor supports and if it meets the
requirements for integrating with Duke.
* Visit the Duke Security website if you have questions with regard to choosing
a vendor.
* It is advisable that you familiarize yourself with the vocabulary. This will
help connect the dots if problems arise at any time during the integration.

Is your vendor part of InCommon?
* Check the following list to see if your vendor is part of InCommon: InCommon
participants
* If your vendor is an InCommon participant, please submit a Shibboleth
integration support request with the vendor's EntityID and any attributes the
vendor needs to be provided about users upon login.
* If the above does not apply to your vendor, move on to the Getting Started
section.

Getting Started

Provide your vendor contact with the following:

* The Duke metadata is important since it contains information that identify
the Identity Provider (Duke). Your Service Provider (vendor) will use this
information to redirect users to the Duke Shibboleth NetID login page.
The certificate in the Duke metadata is used to sign the responses and
assertions produced by the Identity Provider (IdP).
* Give your vendor the Metadata Signing Certificate. This certificate is used
to sign the Identity Provider's (IdP) Metadata.
* Occasionally, vendors require a SHA256 signing certificate.This can be
obtained with a ServiceNow ticket to Identity Management-OIT

Gather information from vendor

It is time to collect information that will be used in the Register Service
Provider (SP) section below.

For reference, take a look at our vocabulary document.

Request a copy of the vendors metadata. This can be uploaded as a file in the
registration interface.

If the vendor cannot provide this file, you will need them to provide the
following elements so you can register the Service Provider (SP) manually:

1. EntityID
2. Certificate used for encryption
3. Assertion Consumer Service URL (ACS)
4. Attributes the Service Provider (SP) will need

Register Service Provider (SP)
* Duke sponsor - create a guest account for the vendor. The guest account can
also serve as an account for testing authentication. Note: You will need to
request NetID credentials.
* Register your Service Provider (SP)
* If you have more than one environment (test, production), you can have
multiple registrations.

Test authentication and authorization
* Using a web browser (private/incognito window) that is not already logged
into Shibboleth, attempt to navigate to a part of your site that should be
protected by Shibboleth.
* You should be prompted with the Duke Shibboleth NetID login page. If you see
an error stating that the Identity Provider (IdP) does not recognize your
Service Provider (SP), make sure you registered the correct EntityID during
registration.
* If you authenticated successfully with your NetID and password but received
an error afterwards, contact your vendor for help with the issue. You can
submit a help request if the vendor requires custom changes for their Service
Provider (SP).

authentication.oit.duke.edu Open in urlscan Pro 152.3.72.142 Public Scan

Form analysis 0 forms found in the DOM

Text Content

authentication.oit.duke.edu Open in urlscan Pro
152.3.72.142 Public Scan

Form analysis
0 forms found in the DOM