Documentation
Additional information to assist with implementing Shibboleth or OAuth
Shibboleth
Helpful information for implementing Shibboleth.
Available Attributes
Public Attributes that can be released by Shibboleth
| Attribute name (friendlyName) | Description | Name |
|---|---|---|
| cn | Typically the person's full name | urn:oid:2.5.4.3 |
| displayName | Preferred name; primary name used when displaying entries. Name person would put on their name tag. Uses givenName or eduPersonNickName, Last Name and generationQualifier. | urn:oid:2.16.840.1.113730.3.1.241 |
| duDukeID | Duke Unique ID; identifier with leading padded zeroes to seven digits | urn:mace:duke.edu:idms:unique-id |
| duMiddleName1 | middle name | urn:mace:duke.edu:idms:middle-name1 |
| eduPersonPrincipalName | Unique identifier for a user. format of the attribute value is netid@duke.edu. Recommended to use as primary identifier. | urn:oid:1.3.6.1.4.1.5923.1.1.1.6 |
| eduPersonAffiliation | Multi-valued attribute that specifies the person's relationship(s) to the institution in broad categories such as student, staff, faculty, emeritus, affiliate, alumni | urn:oid:1.3.6.1.4.1.5923.1.1.1.1 |
| eduPersonNickname | Preferred/Chosen/Lived name. | urn:oid:1.3.6.1.4.1.5923.1.1.1.2 |
| isMemberOf | Grouper or Group manager group membership is released through this attribute | urn:oid:1.3.6.1.4.1.5923.1.5.1.1 |
| eduPersonPrimaryAffiliation | A single-valued attribute that specifies the person's PRIMARY relationship to the institution in broad categories such as student, staff, faculty, emeritus, affiliate, alumni | urn:oid:1.3.6.1.4.1.5923.1.1.1.5 |
| givenName | First name | urn:oid:2.5.4.42 |
| Preferred Duke e-mail address. preferred email is set in the self-service application portal. | urn:oid:0.9.2342.19200300.100.1.3 | |
| ou | Organizational unit; when used as a component of a directory name it identifies an organizational unit with which the named object is affiliated | urn:oid:2.5.4.11 |
| sn | Surname or Family name | urn:oid:2.5.4.4 |
| telephoneNumber | office/campus phone number | urn:oid:2.5.4.20 |
| title | The title of a person in their organizational context; each title is one value of this multi-valued attribute. | urn:oid:2.5.4.12 |
| uid | Duke NetID | urn:oid:0.9.2342.19200300.100.1.1 |
| dkuID | DKU primary identifier | urn:mace:duke.edu:idms:dku-id |
| duDADDEntityId | Duke Alumni primary identifier | urn:mace:duke.edu:idms:dadd:entityid |
Error
Unknown or Unusable Identity Provider
The identity provider supplying your login credentials is not authorized for use with this service or does not support the necessary capabilities.
To report this problem, please contact the site administrator at userNetID@duke.edu.
Please include the following error message in any email:
Identity provider lookup failed at (http://localhost/secure)
EntityID: https://shib.oit.duke.edu/shibboleth-idp
opensaml::saml2md::MetadataException: Unable to locate metadata for identity provider (https://shib.oit.duke.edu/shibboleth-idp)
Solution
Check the console for errors. If you are on windows, check the shibd log file located here: C:\opt\shibboleth-sp\sbin and run shibd.exe - check.
This will result in a message like the following: overall configuration is loadable, check console for non-fatal problems if everything is okay, otherwise a very descriptive error message will be displayed.
If you are on Linux, run the following command:
sudo shibd -t
Error
The login service was unable to identify a compatible way to respond to the requested application. This is generally due to either a misconfiguration on the part of the application or a failure for the application owners to properly register all appropriate assertion consumer service URLs with our Identity Provider (IdP).
If you are the application owner, please check your registration using our self-service interface: https://authentication.oit.duke.edu/manager.
Otherwise, this issue should be reported to the application's support team or owner.
Solution
Download a SAML tracer add on for your browser. Firefox: https://addons.mozilla.org/en-US/firefox/addon/saml-tracer/?src=search
Once downloaded, follow these steps:
Click on the SAML tracer icon to the right of the search bar.
You should see a new window pop up. Try to access your site.
You should see many URLs being displayed in the pop up window. Look for the URL that has the SAML icon. Click on this url.
Click on the SAML tab. It should look something like this:
<samlp:AuthnRequest xmlns:samlp="urn:oasis:names:tc:SAML:2.0:protocol" AssertionConsumerServiceURL="https://inventory.oit.duke.edu/Shibboleth.sso/SAML2/POST" Destination="https://shib.oit.duke.edu/idp/profile/SAML2/Redirect/SSO" ID="_ca6ef0f8b7cae81541ed3fd499b98188" IssueInstant="2018-05-01T14:47:45Z" ProtocolBinding="urn:oasis:names:tc:SAML:2.0:bindings:HTTP-POST" Version="2.0" > <saml:Issuer xmlns:saml="urn:oasis:names:tc:SAML:2.0:assertion">https://inventory.oit.duke.edu</saml:Issuer> <samlp:NameIDPolicy AllowCreate="1" /></samlp:AuthnRequest>
- Make sure that the ACS you registered matches the value you see under AssertionConsumerServiceURL.
Download this Chrome SAML tracer Chrome SAML tracer.
Once downloaded, follow these steps:
Open the developer console. click on the SAML tab:
Access your application. click on the green highlighted row with the GET method on the first column.
Once you have clicked on the above, move to the SAML tab on the right.
Make sure that the ACS you registered matches the value you see under AssertionConsumerServiceURL.
Error
404 File not found.
Solution
Check that port and scheme are specified under the ISAPI element. Usually will result in the 404 file not found if https is enabled.
Custom Attributes
What are custom attributes?
Custom attributes allow SP's to customize the way an attribute is released to service providers. for example, we currently release a users preferred email as the friendlyName value of "mail", and through the Name value as "urn:oid:0.9.2342.19200300.100.1.3" in the SAML response.
How to add a custom attribute?
in your my sites page, click on the SP registration that you want to add custom attributes to.
once you have selected the SP registration, scroll down to the attributes section.
select the attribute that you want to be mapped and click the "+" icon next to the attribute name.
once the attribute is added to the list, check the checkbox next to "use custom name" and in the textfield that appears, type in what you want the Name and FriendlyName of the attribute to be released as. in the screenshot you can see that we are using the displayName attribute but we are choosing that this attribute be released as display_name. optionally, if you still want displayName to be released select the checkbox next to "include original attribute".
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.
Make sure the Shibboleth directory exists.
Linux:
/etc/shibbolethWindows/IIS:
c:\opt\shibboleth-sp\etc\shibbolethMake sure that the
shibdprocess starts & that the status is active (running). In your Terminal/PowerShell run the following command:Linux:
systemctl start shibd|systemctl status shibdWindows/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
Move into the Shibboleth directory
cd /etc/shibbolethDownload Duke Metadata:
wget -O duke-metadata-3-signed.xml https://shib.oit.duke.edu/duke-metadata-3-signed.xmlDownload Metadata signing certificate:
wget -O idp_signing.crt https://shib.oit.duke.edu/idp_signing.crtVerify that both files were downloaded correctly:
ls.
lswill 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.xmlandidp_signing.crtinside the shibboleth directory.
Windows
Using the Command Prompt or PowerShell.
Move into the Shibboleth directory
cd c:\opt\shibboleth-sp\etc\shibbolethDownload Duke Metadata:
curl -o duke-metadata-3-signed.xml -k https://shib.oit.duke.edu/duke-metadata-3-signed.xmlDownload Metadata signing certificate:
curl -o idp_signing.crt -k https://shib.oit.duke.edu/idp_signing.crtVerify that both files were downloaded correctly:
dir.
dirwill 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.xmlandidp_signing.crtinside 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, eduPersonPrincipalName 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
cipherSuitesvalue and addencryption=truesimilar to the below XML.
<applicationDefaults id="default" policyId="default"
entityID="https://your.sp.duke.edu/shibboleth"
REMOTE_USER="eppn"
encryption="true">
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<!--and-->comment tags. - Replace the
urlvalue with:https://shib.oit.duke.edu/duke-metadata-3-signed.xml - Set the backingFilePath value to
duke-metadata-3-signed.xml, replacemaxRefreshDelaywithreloadInterval - 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
<MetadataProvider type="XML" validate="true"
url="https://shib.oit.duke.edu/duke-metadata-3-signed.xml"
backingFilePath="duke-metadata-3-signed.xml" reloadInterval="7200">
<MetadataFilter type="Signature" certificate="idp_signing.crt"/>
</MetadataProvider>
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.
<CredentialResolver type="File" use="signing" key="sp-signing-key.pem" certificate="sp-signing-cert.pem"/>
<CredentialResolver type="File" use="encryption" key="sp-encrypt-key.pem" certificate="sp-encrypt-cert.pem"/>
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:
<Sessions lifetime="28800" timeout="3600" checkAddress="false"
handlerURL="/Shibboleth.sso" handlerSSL="false"
redirectLimit="host+whitelist" redirectWhitelist="https://shib.oit.duke.edu/"
exportLocation="http://localhost/Shibboleth.sso/GetAssertion" exportACL="127.0.0.1"
idpHistory="false" idpHistoryDays="7" cookieProps="https">
- 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
<SSO entityID="https://shib.oit.duke.edu/shibboleth-idp">
SAML2
</SSO>
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.
<Attribute name="urn:mace:dir:attribute-def:eduPersonPrincipalName" id="eppn">
<AttributeDecoder xsi:type="ScopedAttributeDecoder"/>
</Attribute>
<Attribute name="urn:oid:1.3.6.1.4.1.5923.1.1.1.6" id="eppn">
<AttributeDecoder xsi:type="ScopedAttributeDecoder"/>
</Attribute>
<Attribute name="urn:mace:dir:attribute-def:eduPersonScopedAffiliation" id="affiliation">
<AttributeDecoder xsi:type="ScopedAttributeDecoder" caseSensitive="false"/>
</Attribute>
<Attribute name="urn:oid:1.3.6.1.4.1.5923.1.1.1.9" id="affiliation">
<AttributeDecoder xsi:type="ScopedAttributeDecoder" caseSensitive="false"/>
</Attribute>
Verify configuration
You are now ready to test configuration changes.
Restart the shibd service:
Linux:
systemctl restart shibdWindows:
sc stop shibd_default&&sc start shibd_default. Also, make sure to restart IIS.iisresetOpen a web browser and access your site appending
/Shibboleth.sso/Statusto your sites URL. for example,http://localhost/Shibboleth.sso/StatusYou 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).Next, access your site using:
http://localhost/Shibboleth.sso/LoginIf 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.
If you see any other message besides the above, check the console for possible problems.
Check problems with
shibd -tIf 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.
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
Once you have downloaded/added the shibboleth repo. Install the Shibboleth Service Provider (SP) with
yum install shibbolethThis will install the latest version of the Shibboleth Service Provider (SP) software. You will receive confirmation prompts when software is installing. Typeyto allow the installation of the Shibboleth Service Provider software.You can confirm the installation by typing
shibd -vin the terminal. You should see the version number printed out, for exampleshibboleth 3.0.2If 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
- 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.
- Depending on your system choose either the win32 or win64 folder.
- Depending on what you chose above, click the first file ending in
.msito download. - Once the installer has downloaded, run the installer.
- The installer will walk you through various prompts.
- 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\ - Select Configure IIS7 module when prompted for directory installation. The installer will add an ISAPI filter and an SSO extension.
- Restart IIS
iisreset. You can now move to configuring your Service Provider (SP). - 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
Setting Up Logout
Set your LogoutInitiator element in your shibboleth2.xml file to look like the following:
<LogoutInitiator type="Chaining" Location="/Logout" relayState="cookie">
<LogoutInitiator type="Local"/>
</LogoutInitiator>
Initiate logout by redirecting users with the following URL for the logout script.
/Shibboleth.sso/Logout?return=https://shib.oit.duke.edu/cgi-bin/logout.pl
This will destroy the user's session on your SP, the user's SSO session, but it will not destroy the user's session on other SPs.
The logout.pl script can accept two optional arguments:
logoutWithoutPrompt
If the value is "1", then the user is not prompted to logout. The IdP cookies are destroyed.
returnto
After logout, the user can be redirected to the URL you provide as a value here. The redirect location has to be a Duke address. You would use this parameter if you want to take the user back to your application (an unauthenticated page) or display a custom logout/timeout message.
Example: https://shib.oit.duke.edu/cgi-bin/logout.pl?logoutWithoutPrompt=1&returnto=http://www.oit.duke.edu
Vocabulary
Knowledge of these terms will be helpful during the Shibboleth integration process.
ACS
Assertion Consumer Service URL. This is the location that is listening for the SAML Response. From the user's perspective, this is where it goes after the credentials have been collected.
entityID
The identifier for the Service Provider(SP).
endpoint
An endpoint is one end of a communication channel. Roughly speaking, in this case, it's the HTTP call that will be made to the Identity Provider (IdP).
eppn (eduPersonPrincipalName)
This attribute is the "scoped NetID", i.e. netid@duke.edu. It looks like an email address, but it is not intended to be used as one. EPPN is a shared standard that allows for global uniqueness of user identifiers within our wider community of research and educational institutions.
InCommon
The InCommon Federation provides a common framework to manage online resources, using Single Sign-On. Members of InCommon may choose to register with them instead of us. Since we are members of InCommon and federate with it, they will not have to register again with us in order for Duke community users to authenticate with our Identity Provider (IdP) when using their applications.
Identity Provider (IdP)
The Identity Provider (IdP) handles the authentication and provides information about the user.
Metadata
In this case, metadata refers to an XML file that specifies the communication between the Service Provider (SP) and the Identity Provider (IdP).
SAML (Security Assertion Mark-up Language)
Shibboleth is an implementation of SAML.
Service Provider (SP)
The Service Provider (SP) issues authentication requests to the Identity Provider (IdP) and handles the responses.
Single Sign-On (SSO)
Single Sign-On. A user should be able to authenticate once and then be authorized to access multiple applications.
OAuth
Helpful information for implementing OAuth.
Duke OAuth 2.0
Duke supports electronic authorization to resources via the OAuth 2.0 and OpenID Connect (OIDC) standards. This environment still uses Shibboleth for authentication so users continue to see the same authentication interface. However, clients only have to support OAuth/OIDC rather than Shibboleth (SAML). You may choose to use OAuth/OIDC instead of Shibboleth if your are working with a vendor that already has built-in functionality. Or you may be working on a platform where it is not ideal to install the Shibboleth SP and its dependencies. Note that OIDC is built on top of OAuth 2.0 and adds some standards (for example regarding how scopes are named, token format, and discovery).
Endpoints
The following are endpoints available in the system. Some vendor applications that support OIDC allow integration by supplying either the OIDC Issuer or OIDC Metadata URL.
- OIDC Issuer: https://oauth.oit.duke.edu/oidc/
- OIDC Metadata URL: https://oauth.oit.duke.edu/oidc/.well-known/openid-configuration
- Authorization URL: https://oauth.oit.duke.edu/oidc/authorize
- Token URL: https://oauth.oit.duke.edu/oidc/token
- Introspection URL: https://oauth.oit.duke.edu/oidc/introspect
- Userinfo URL: https://oauth.oit.duke.edu/oidc/userinfo
- Logout URL: https://oauth.oit.duke.edu/oidc/logout.jsp
Scopes
In OAuth/OIDC, scopes are used to authorize access to user data. The following built-in scopes provide access to the following data:
- openid - provides sub, dukeNetID, dukeUniqueID. sub is the user's eduPersonPrincipalName (or <netid>@duke.edu)
- profile - provides dukePrimaryAffiliation, name, given_name, family_name
- email - provides email
- groups - provides the user's group memberships (see below)
For more advanced use cases, clients can also use custom scopes to allow users to authorize access to backend resources.
Grant Types
Multiple grant types are supported. Grant types are the way the application integrates with the system and retrieves tokens. The most common grant type is "authorization_code".
With the authorization code grant type, the application should redirect the user to the Authorization URL with the following request parameters:
- response_type - The value must be "code".
- client_id - This is your client id.
- redirect_uri - This is where the user should be redirected back to in your application after authentication.
- state - An opaque value used by the client to maintain state between the request and callback. The authorization server includes this value when redirecting the user-agent back to the client. The parameter should be used for preventing cross-site request forgery.
- scope - This parameter is optionally used to specify the desired scopes (space-delimited).
- nonce - This parameter is optional and is a unique, one-time-use value sent with authentication requests to ensure the response is tied to that specific request, helping to prevent replay attacks and enhancing security. The value is passed through unmodified from the Authentication Request to the ID Token.
Clients may use the HTTP GET or POST methods to send the Authorization Request to the Authorization Server. If using the HTTP GET method, the request parameters are serialized using URI Query String Serialization. If using the HTTP POST method, the request parameters are serialized using Form Serialization.
The user will authenticate using the standard Shibboleth login screen. Then the user will be presented with a consent screen to approve the data that will be released by the OAuth server. If the user approves, the user will be redirected to the redirect_uri with the "state" and "code" request parameters. The "state" parameter should be used to prevent cross-site request forgery. The "code" parameter should be sent to the Token URL to retrieve an access token and id token for the user. Finally, those tokens can be sent to either the Introspection URL or the Userinfo URL to retrieve information about the user, such as their NetID and DukeID.
For additional guidance on how to securely integrate OAuth with native mobile applications, please see the OAuth Mobile Development Standard
Groups
The information that's released by the system can also include group memberships from Group Manager policy groups. These groups can be released as part of the JWT claim set of the id token, JWT claim set of the access token, or using the Introspection URL. For more help on integrating with groups, please send a Service Now ticket to Identity Management-OIT.
Examples
If you are building your own integration, here are some examples for interacting with the system.
Authorization Code Grant Type
- Redirect the user to: https://oauth.oit.duke.edu/oidc/authorize?response_type=code&client_id=your_client_id&state=your_opaque_state&redirect_uri=https://your_redirect_uri
- After authentication, the user will be redirected to your application: https://your_redirect_uri/?code=CODE&state=your_opaque_state
- Validate the "state" and call the Token URL. Here's a simple example using curl.
curl -u 'your_client_id:your_client_secret' https://oauth.oit.duke.edu/oidc/token -d 'grant_type=authorization_code&redirect_uri=https://your_redirect_uri&code=CODE'
{"access_token": "ACCESS_TOKEN", "token_type": "Bearer", "refresh_token": "REFRESH_TOKEN", "expires_in": 3599, "scope": "openid profile offline_access groups email", "id_token": "ID_TOKEN"}'
Note that the access token and id token are both signed JWTs that contain information about the token and user. However, unless the information is being used at the time of authentication, the tokens should be introspected to ensure that they have not been revoked.
Introspection
You can introspect the access token and id token. Or if you are passing the tokens to a backend resource, it can perform introspection as well. Here's a simple example using curl.
curl -u 'your_client_id:your_client_secret' https://oauth.oit.duke.edu/oidc/introspect -d 'token=TOKEN'
{"active": true, "scope": "openid profile offline_access groups email", "expires_at": "2021-04-01T13:44:08-0400", "exp": 1617299048, "sub": "hiro@duke.edu", "dukeNetID": "hiro", "dukeUniqueID": "0299309", "dukePrimaryAffiliation": "affiliate", "name": "Test User", "given_name": "Test", "family_name": "User", "email": "test.user@duke.edu", "user_id": "hiro@duke.edu", "client_id": "your_client_id", "token_type": "Bearer", "azp": "your_client_id", "groups": ["example-group-1", "example-group-2"]}
User Info
Some applications may have built-in support for the userinfo endpoint instead.
curl https://oauth.oit.duke.edu/oidc/userinfo -d 'access_token=TOKEN'
{"sub": "hiro@duke.edu", "dukeNetID": "hiro", "dukeUniqueID": "0299309", "dukePrimaryAffiliation": "affiliate", "name": "Test User", "given_name": "Test", "family_name": "User", "email": "hiro@duke.edu", "email_verified": false}
Refresh Tokens
If your access token or id token is expired and you have a refresh token, you can retrieve new tokens using this example.
curl -u 'your_client_id:your_client_secret' https://oauth.oit.duke.edu/oidc/token -d 'grant_type=refresh_token&refresh_token=REFRESH_TOKEN'
{"access_token": "ACCESS_TOKEN", "token_type": "Bearer", "refresh_token": "REFRESH_TOKEN", "expires_in": 3599, "scope": "openid profile offline_access groups email", "id_token": "ID_TOKEN"}
Token Revocation
You also have the ability to revoke tokens if needed.
curl -u 'your_client_id:your_client_secret' https://oauth.oit.duke.edu/oidc/revoke -d 'token=TOKEN'
Client Secrets Management
Long Lived Access Tokens
IdM has extended its existing OAuth implementation and will update self-service interfaces to allow users to manage client secrets.
A new OAuth client id (IdMClientSecretsManagement) has been created to allow users to have long-lived access tokens. The lifetime of the access tokens will be 1 year. These access tokens will have refresh tokens.
Until an IdM self-service interface is available please submit a ticket to Identity Management to request one or more of these access tokens. These tokens can either be associated with your own identity (DUID) or they can be associated with a service account that the you own (either directly or via a support group). These access tokens can be used by users to create short lived access tokens for other client ids to access their APIs. When requesting each long-lived access token, please specify one of the following:
- The long-lived access token can be used to create an access token for all endpoints of any client id.
- The long-lived access token can be used to create an access token for all endpoints of a specific client id.
- The long-lived access token can be used to create an access token for specific endpoints (based on regex) of a specific client id.
This information will be part of the JWT claim set of the long-lived access token.
Create client token example
All tokens all shortened for readability
curl -verbose -H "Content-type: application/json" -d '{ "longLivedToken" : "eyJraWQiOiJyc2ExIiwiYWxnIjoiUlMyNTYifQ.eyJzdWIiOiJzaGlsZW5AZ5Yzk3NWMifQ.CH9Oi6lLEKvGTSGATeGIM6xt7K1XCR_GQ", "clientId" : "ShilenTest", "endpoints" : ["endpoint:/url1", "endpoint:/url2"] }' https://idms-web-ws.oit.duke.edu/idm-ws/clientSecret/createClientToken
{"error": false, "mapQueryResult": {"attributes": {"accessToken": "eyJraWQiOiJyc2ExIiwiYWxnIjoiUlMyNTYifQ.eyJzdWIiOiJ0ZXN0xMjk1YiJ9.k4YhNHAnAAbj6ReDSz56c4YqG-qk-h53znVzr00Mg", "refreshToken": "eyJhbGciOiJub25lIn0.eyJjbGJjbGllbnRTZWNyZXR-Y2xpZW50SWRSZXN0cmljdGCJqdGkiOiJhMWExOGVlYy0wY2ZiLTRhYTQifQ."}}}
Refresh long lived token example
curl --verbose -H "Content-type: application/json" -d '{ "longLivedRefreshToken" : "eyJhbGciOiJub25lIn0.eyJjbGllbnRTZWmljdGlvblJlZ2V4IjoiLiMjQxNS03YThjLTQ4NWYtYjAw-C1jM2ZiMzI1NWJiM2MifQ."}' https://idms-web-ws.oit.duke.edu/idm-ws/clientSecret/refreshLongLivedToken
{"error": false, "mapQueryResult": {"attributes":{ "accessToken": "eyJraWQiOiJyc2ExIiwiYWxnIjoiUlMyNTYifQ.eyJzdWI-5kcG9pbnRSZXN0cmljdGlvblJlZ2V4IjoiLioiLCdlbWVudCIsImNsaW dFNlY3JldF9jbGllbnRJZFJlc3RyaWN0aW9uIjoiU2hpbxNTk3MTIyLCJqdGkiOiJiMGVmYmJjOS1lZTUwL RiNmMtYjBkZC1mNmVlYzVjNTI0MDYifQ.AUGYGPvkgWeWjvp_5LuSpUPsBqQ6chMUYFXlsemXVoEVfk99AgFfGUZyQtK6WS6KE6kPgPw", "refreshToken": "eyJhbGciOiJub25lIn0.eyJjbGllbnRTZWNyZXRRSZXN0cmljdGlvbiI6IlNoaWxlblRlc3Q3My03YjVjYTFkZTIwNDcifQ."}}}
Endpoints as Custom Scopes
Authentication Manager has been updated to allow users to configure endpoints for their client ids. The endpoints are stored as scopes in OAuth and prefixed with 'endpoint:'. Users will not have to add this prefix when entering endpoints in the Authentication Manager application form.
Once users have a long-lived access token for IdMClientSecretsManagement, they can pass that access token to a new OAuth API along with the API they want to access by passing the client id and endpoints (i.e. scopes). The API will validate the request (e.g. the long-lived access token is active and is allowed to request an access token for the given client id and endpoints). It will also verify that the user's NetID is currently active. It will then create and return a new access token for the requested client id and scopes. The expiration time of the new access token will be based on the configuration for that client id.
Usage
The new access token can be passed to the user info and introspection endpoints as normal. The response from the introspection endpoint will indicate that it was created using token authentication. Here's an example response:
{"active":true, "scope":"endpoint:/url1 endpoint:/url2", "expires_at":"2021-01-05T16:36:27-0500", "exp":1609882587, "sub":"shilen@duke.edu", "dukeNetID":"shilen", "dukeUniqueID":"0374183", "user_id":"shilen@duke.edu", "client_id":"ShilenTest2", "token_type":"Bearer", "azp":"ShilenTest2", "isTokenAuthentication":"true"}
Finally, the refresh tokens associated with the long-lived access tokens can be sent to a new API that will return a new 1 year access token, destroy the old access token, and issue a new refresh token as well.