Updated to add additional optional attribute mappings 3/23/17.

These instructions provide the basics to integrate your IdP with Kuali Ready. Please share them with the campus IT professional with access and knowledge to configure your Shibboleth IdP.

Step 1: Email IdP info to Ready Help

In order to set up your Kuali Ready account with Shibboleth integration, you will need to email ready-help@kuali.co with your:

    • IdP entity ID

    • Attribute that you use as the unique user ID

Note: It is required that your IdP’s metadata be listed in InCommon’s feed.

Step 2: Configure your Shibboleth server to use our metadata

We are listed in the InCommon metadata feed with the Entity ID of “https://ready.kuali.co”. This is the preferred way to get Kuali Ready’s metadata. Information about InCommon’s metadata can be found here: https://spaces.internet2.edu/display/InCFederation/Metadata+Aggregates

Our metadata is also available at https://saml1.kuali.co/ready/saml/meta. It is highly recommended that you configure your server to periodically refresh the metadata (at least once a day, but no more than hourly) as it may change from time to time.

Note: Kuali Ready currently requires the HTTP-REDIRECT method to be accepted by the IdP for the AuthNRequest and we currently only accept the HTTP-POST method for the Response. If you require any other methods to be supported, please contact ready-help@kuali.co for assistance.

Signature: If you are having trouble with a signature not being present and/or not valid, please consult the Shibboleth document here: https://wiki.shibboleth.net/confluence/display/SHIB2/IdPXMLSigEnc. You can find this page by searching for “Configuring XML Signature and Encryption”. In particular, you will want to set the `signResponses` configuration option to “always” and the `signAssertions` to “never” to ensure that your Shibboleth IDP sends the right one. If your server signs both the assertions and the response sometimes it sends an invalid signature for the response.

Step 3: Release appropriate attributes

You will need to release the following user attributes with the friendly names listed with the Response.

    Required fields

        Unique ID - the attribute that you specified as the unique ID in step 1
        mail / officialMail - the official email address of the user. Using the `mail` attribute is                     preferred, but if that is already in use for something other than the user’s official email address 
        then you can assign the official email address to `officialMail` and the system will use that 
        before `mail.`
        givenName - The first name of the user.
        sn - The surname or last name of the user.


    Optional fields

        telephoneNumber - Phone number of the user.
        title - Title of the user.
        department - Department of the user.

By default, the optional fields will attempt to be brought in from your system of record. If you are providing those attributes and they are not appearing in Kuali Ready after a user authenticates, please create a help desk ticket at ready-help@kuali.co to configure those fields. In that ticket provide the attribute names you are currently passing. 

For example: <saml:Attribute Name='urn:oid:' NameFormat='urn:oasis:names:tc:SAML:2.0:attrname-format:uri' FriendlyName='Department'>

If you would like certain fields optional fields to NOT be pulled in from your system of record, we can also turn those off and allow you to key-in those fields manually. 

Step 4: Test the integration

Once you have emailed the IdP entity ID and the unique user ID attribute to ready-help@kuali.co and we have entered these into our system, we will respond that the system is ready to test. 

You can test out the Shibboleth integration by going to: http://yourschool.kuali.co/ready/saml/init?test. (replace 'yourschool' with the info we're using for your domain, ie. stanford, csulb, psu.) This will redirect you to your IdP where you can sign in with user credentials and it will redirect back to Kuali Ready with debugging information. You can use this to correct any problems with your Shibboleth setup.

Note: Follow the guidance on the debugging screen to understand whether you've had a successful test. You should receive a 'Yes' response for Signed and Signature Valid.

Step 5: Email Ready Help that you’re ready to switch

When you’ve completed successful testing, please notify ready-help@kuali.co and we will switch on Shibboleth authentication for your account. We will likely do this after business hours when users with existing Direct authentication accounts are logged out of the system.

Step 6: Merge any Direct user accounts

Once we've switched you to Shibboleth authentication, your Ready URL will redirect to your SSO login screen. Users with accounts created prior to Shibboleth integration will receive an email notice the first time they log in, asking them to confirm this is the same user account. They must select the link in the email to merge the accounts. The user will not be able to use the system until they select the link in the email. 

Note: For the merge functionality to work, users must not be authenticated in another application in the browser. Log out of SSO before visiting your Ready URL.