This guide provides step-by-step instructions for integrating with the CCC SSO Proxy service and should be used in conjunction with the /wiki/spaces/CSF/pages/137363670 to ensure all technical and operational requirements have been met. The process can also be visualized on the Proxy Integration Workflow diagram.
Overview
The CCC SSO Proxy service was created to accomplish several things:
- Provide a way to add the user's CCCID attribute to the SAML response to a service, even if the college was not able to provide one
- Provide a central management point where new services could be integrated without each college needing to make any changes to its local college IdP in order to access that new service
- Instead of the SAML response from the college/district IdP going directly to the service (e.g. Canvas, Assess), it goes first to the SSO Proxy (which has it own "internal" SP). The Proxy can add attribute(s) to it if needed (e.g. CCCID), filter the attributes received down to the specific attributes needed by the particular service, and send a SAML response back to the service.
This simple diagram illustrates what this looks like:
Once your college/district IdP is configured to release a "master bundle of attributes" to the CCC SSO Proxy, that IdP won't need to be changed to be used with a new service, because all the needed changes will be made within the proxy itself. The only exception would be if an entirely new attribute was needed for a service beyond the set documented below, in which case the college/district IdP would need to be updated to release that attribute to the proxy.
The CCC SSO Proxy is under the management of the CCC Technology Center. No attribute values will be stored, saved, or logged by the proxy, and only the needed attributes will be forwarded in the response to the service.
Configuring Your College/District IdP to Release Attributes to the Proxy
Integrating your college/district IdP with the proxy is essentially the same steps you would follow to integrate with CCCApply, only there is a wider set of attributes that are required and/or potentially useful (optional). Basically, the idea is that the set of attributes released to the proxy is the full set of any attributes that any federated service needs. The proxy will take care of filtering that set down to what is needed for any given service. And just like with CCCApply, there is both a Pilot and Production environment for the proxy. You will integrate first with the Pilot environment, and then with Production.
Note: if you are running Shibboleth IdP v3 software with the standard configuration that Unicon has been putting into the IdPv3 installs, you only need to perform Steps 3 and 6 below in order to integrate with the proxy. Your IdP has already been configured to consume both the metadata for the proxy – contained within the CCC central metadata file distribution (ccc-metdata.xml) – and the attribute release rules needed for the proxy, contained within the CCC central attribute filter file (attribute-filter.ccccentral.xml). Otherwise, you need to perform all of the following steps.
STEP 1: Understand and make sure you have the following attributes available
These attributes are described in more detail in the accompanying wiki page entitled "Attributes for CCC SSO Federated Access". In particular, the critically important eduPersonPrincipalName (EPPN) attribute is described more fully in that wiki page. A few sample definitions of creating, or "resolving", these attributes in a Shibboleth IdP v3 server can be found on the wiki page "Shibboleth IdP v3 Attribute Resolver Configuration".
Minimum Required Attributes
Simple Name and the SAMLv2 name when sent in the SAMLv2 response | Short description | Sample value(s) | Description |
---|---|---|---|
eduPersonPrincipalName (EPPN) urn:oid:1.3.6.1.4.1.5923.1.1.1.6 | The primary federated identifier of a given user from a college/district IdP. | EPPN has the syntax of an email address, but it should be considered a "globally unique federated identifier" rather than an email address. It is generally the most important attribute to be shared with federated services. Note that the value of EPPN does not have to match what the user fills in as their username when they login, and the user does not need to know what their EPPN is, as it is shared between the IdP and the service. It should be unique, rarely change, and not be reassigned to another person. | |
eduPersonAffiliation urn:oid:1.3.6.1.4.1.5923.1.1.1.1 | Role within the institution |
| All of the roles a given person has within the college. This is the only attribute listed here that is intended to have multiple values. All the rest are expected to have a single value. |
cccId | Unique id for a student within the CCC system | The CCCID is a critical attribute for students. If not specified, but required for a portal or service action, the CCCID will be looked up via the EPPN. If no match is found, the action cannot be performed until the user creates a CCCID via the OpenCCC portlet. | |
uid urn:oid:0.9.2342.19200300.100.1.1 | Username | jsmith | This is usually the value that the user fills in as their username when they login. If you are using AD, the usual attribute you want to use to populate uid is the sAMAccountName attribute. |
givenName ..... urn:oid:2.5.4.42 | First Name | Jane | |
sn (surname) .... urn:oid:2.5.4.4 | Last Name | Smith | |
displayName urn:oid:2.16.840.1.113730.3.1.241 | Full name to display | Jane Smith | Required for display |
mail (email) urn:oid:0.9.2342.19200300.100.1.3 | Email Address | jane.smith@college.edu |
Configure Optional Attributes
These are optional attributes that can be sent by the college. One example use is that these can be used to pre-populate values when the user is required to create a central CCCID account.
Simple Name and the SAMLv2 name when sent in the SAMLv2 response | Short description | Example | Notes |
---|---|---|---|
eduPersonPrimaryAffiliation urn:oid:1.3.6.1.4.1.5923.1.1.1.5 | Primary role at the institution |
| Must be one of the values specified in eduPersonAffilliation. If the eduPersonAffiliation attribute has many values, the primary affiliation should reflect primary the users primary affiliation. i.e. a teacher aid may be a student and staff, but their primary role is a student. |
street urn:oid:2.5.4.9 | Street address | 303 Mulberry St. | |
locality .... urn:oid:2.5.4.7 | City | Metropolis | |
st .... urn:oid:2.5.4.8 | State or Province name | CA | |
postalCode .... urn:oid:2.5.4.17 | Postal or zip code | 12345 | |
homePhone .... urn:oid:0.9.2342.19200300.100.1.20 | Home Phone Number | +1 212 555 1234 | |
mobile .... urn:oid:0.9.2342.19200300.100.1.41 | Mobile Phone Number | +1 775 555 6789 |
STEP 2: Schedule kick-off call with the Proxy Project Team
At this point, before you can do some of the following steps, you need to contact the CCC Proxy Project Team to tell them that you are ready to add your college/district IdP to the SSO Proxy. There are several steps that the team needs to take to configure the SSO Proxy to be "ready" for the college/district IdP, and those need to happen before you download the metadata in the next step. Integration will start with the Pilot Proxy, and once that integration is successfully verified, then integration will move on to the Production Proxy.
The Proxy Project Team will also ensure, as part of this step, that they have obtained a copy of your college or district IdP metadata. Just as with CCCApply, the Proxy will need that metadata to be able to interact with your IdP. If you have registered your college/district IdP with InCommon, the metadata can be obtained by the Proxy Team through InCommon. If not, and you are running the Shibboleth IdP, the right metadata may be available in the IdP's file metadata/idp-metadata.xml. Otherwise, you will need to work with the Proxy Team to get your metadata to them.
Contact Team
STEP 3: Configure your Identity Provider (IdP) to release the above attributes to the CCC SSO Proxy
Based on the IdP solution you are running, a few configuration changes need to be made to your IdP. (NOTE: The information in this section is geared towards Shibboleth V3 IdP users. If you are using a different Identity Provider (IdP) solution, please follow the links below for instructions specific to your IdP. Then return to this document to ensure you've completed the remaining integration and testing steps.
- Portal Guard IdP - instructions can be found at Attributes for the Proxy: Portal Guard
- Ellucian IdP - instructions can be found at Attributes for the Proxy: Ellucian
Shibboleth IdP - instructions can be found below:
For Shibboleth IdP
The new IdP v3 config that has been put in place includes consuming a CCC system-wide, centrally managed "attribute release file" (a central attribute-filter.xml file) from a HTTPS URL (with checking that the certificate matches for security.) The IdP automatically checks for updates for that file and if changes have been found will reload the file. That "CCC-wide central attribute-filter.xml file" already contains the following attribute release rules for the proxy. You can tell if your IdP has that file by checking in the IdP's conf/ directory for the file 'conf/attribute-filter.ccccentral.xml'. Otherwise, add the following to the IdP's conf/attribute-filter.xml file, or however you configure attribute release in whatever SAML IdP software that you are using.
<!-- Release all required and optional attributes, for any service, to the CCC IdP Proxy, so it in turn can release only the needed attributes to the services on the other side of the IdP Proxy. All attributes will not be sent to all services, just the needed ones for a given service. The attributes here should constitute a "union" of all possible attributes for any service. --> <AttributeFilterPolicy id="CCCWideReleaseForIdPProxy"> <PolicyRequirementRule xsi:type="OR"> <Rule xsi:type="Requester" value="https://sso.pilot.cccmypath.org/simplesaml/module.php/saml/sp/metadata.php"/> <Rule xsi:type="Requester" value="https://sso.cccmypath.org/simplesaml/module.php/saml/sp/metadata.php"/> </PolicyRequirementRule> <AttributeRule attributeID="eduPersonPrincipalName"> <PermitValueRule xsi:type="ANY"/> </AttributeRule> <AttributeRule attributeID="uid"> <PermitValueRule xsi:type="ANY"/> </AttributeRule> <AttributeRule attributeID="email"> <PermitValueRule xsi:type="ANY"/> </AttributeRule> <AttributeRule attributeID="givenName"> <PermitValueRule xsi:type="ANY"/> </AttributeRule> <AttributeRule attributeID="surname"> <PermitValueRule xsi:type="ANY"/> </AttributeRule> <AttributeRule attributeID="displayName"> <PermitValueRule xsi:type="ANY"/> </AttributeRule> <AttributeRule attributeID="eduPersonAffiliation"> <PermitValueRule xsi:type="OR"> <Rule xsi:type="Value" value="faculty" ignoreCase="true"/> <Rule xsi:type="Value" value="student" ignoreCase="true"/> <Rule xsi:type="Value" value="staff" ignoreCase="true"/> <Rule xsi:type="Value" value="alum" ignoreCase="true"/> <Rule xsi:type="Value" value="member" ignoreCase="true"/> <Rule xsi:type="Value" value="affiliate" ignoreCase="true"/> <Rule xsi:type="Value" value="employee" ignoreCase="true"/> <Rule xsi:type="Value" value="library-walk-in" ignoreCase="true"/> </PermitValueRule> </AttributeRule> <AttributeRule attributeID="eduPersonPrimaryAffiliation"> <PermitValueRule xsi:type="ANY"/> </AttributeRule> <!-- CCC specific attributes --> <AttributeRule attributeID="cccId"> <PermitValueRule xsi:type="ANY"/> </AttributeRule> <AttributeRule attributeID="cccMisCode"> <PermitValueRule xsi:type="ANY"/> </AttributeRule> <!-- Less likely attributes to be populated, but release if available --> <AttributeRule attributeID="mobileNumber"> <PermitValueRule xsi:type="ANY"/> </AttributeRule> <AttributeRule attributeID="homePhone"> <PermitValueRule xsi:type="ANY"/> </AttributeRule> <AttributeRule attributeID="telephoneNumber"> <PermitValueRule xsi:type="ANY"/> </AttributeRule> <AttributeRule attributeID="postalAddress"> <PermitValueRule xsi:type="ANY"/> </AttributeRule> <AttributeRule attributeID="street"> <PermitValueRule xsi:type="ANY"/> </AttributeRule> <AttributeRule attributeID="locality"> <PermitValueRule xsi:type="ANY"/> </AttributeRule> <AttributeRule attributeID="stateProvince"> <PermitValueRule xsi:type="ANY"/> </AttributeRule> <AttributeRule attributeID="postalCode"> <PermitValueRule xsi:type="ANY"/> </AttributeRule> </AttributeFilterPolicy>
STEP 4: Configure your Identity Provider to consume the metadata for the CCC SSO Proxy
Optional Step
If you are running a Shibboleth IdP v3 server, with the configuration changes made by Unicon, or if your Identity Provider is configured to consume metadata from InCommon, your IDP will already have access to the SSO Proxy SAML metadata and you can skip this step.
The new IdP v3 config that has been put in place includes consuming a CCC system-wide, centrally managed digitally-signed metadata file from a URL (with verification of the signature for security.) The IdP automatically checks for updates for that file, and reloads it if such have been made.
The "CCC-wide central metadata file" contains the metadata for a number of CCC system-wide services, including the Proxy. You can tell if your IdP has that file by checking for the file in the IdP's metadata/ directory, the file 'metadata/ccc-central-metadata.xml'. Otherwise, you need to download the metadata for the CCC SSO Proxy from the following URLs (one for Pilot, one for Production). But do not try to download that metadata until completing Step 3 above.
Each college/district IdP will have its own Proxy endpoint for metadata, and to which to send its response to, and those endpoints get created and added to the Proxy metadata distribution only once your IdP has itself been "added to" the Proxy's own configuration.
Just as with the CCCApply service, you will start with Pilot, and once that is working and you are given the "go-ahead", then download the metadata for Production. Note: you need to replace the 'nnn' at the end of each URL with the MIS code that applies to your district (if a district-wide IdP) or to the college (if a single college IdP). The CCC IdP Proxy Service Team will confirm with you what that code will be for your IdP.
Pilot | https://sso.pilot.cccmypath.org/simplesaml/module.php/saml/sp/metadata.php/MISnnn |
Production | https://sso.cccmypath.org/simplesaml/module.php/saml/sp/metadata.php/MISnnn |
STEP 5: Add the Proxy metadata to your college/district IdP
Again, if you are running a Shibboleth IdP v3 server with the configuration changes made by Unicon, you won't need to perform the following step as automated consumption of that central CCC system-wide metadata file mentioned above is already in place. If you are not sure if these changes have already been made by Unicon, please contact the Proxy Project Team for confirmation.
Otherwise, if you are running Shibboleth IdP v3 without assistance from Unicon, you need to save the metadata file you obtained from the above URL as the file:
IdP's home directory/metadata/ccc-idp-proxy-pilot-metadata.xml
IdP's home directory/metadata/ccc-idp-proxy-production-metadata.xml
and then add the following configuration into the IdP's conf/metadata-providers.xml file:
<!-- Pilot CCC IdP Proxy Metadata, locally maintained --> <MetadataProvider id="CCCIdPProxyPilot" xsi:type="FilesystemMetadataProvider" metadataFile="%{idp.home}/metadata/ccc-idp-proxy-pilot-metadata.xml"/> <!-- Production CCC IdP Proxy Metadata, locally maintained --> <MetadataProvider id="CCCIdPProxyProduction" xsi:type="FilesystemMetadataProvider" metadataFile="%{idp.home}/metadata/ccc-idp-proxy-production-metadata.xml"/>
STEP 6: Coordinate with Unicon to add your IdP metadata to the CCC SSO Proxy
Just as you are adding the CCC SSO Proxy metadata to your IdP, the metadata for your college's IdP will need to be added to the Proxy. Unicon will add your college's metadata to the Proxy in the Pilot environment and will confirm with you once this process has been completed. You will not be able to successfully move forward with testing until this step has been completed.
Please forward a copy of your IdP metadata to: Geneva Paliwodzinski, gpaliwodzinski@unicon.net; cc: Patty Donohue, pdonohue@ccctechcenter.org
STEP 7: Test Your PILOT Implementation
Once all the above steps have been completed in Pilot, you can test by using the following URLs. Once the college/district and the Proxy Project Team agree that all is working as it should with the Pilot integration, then the college/district and the Proxy Project Team can move on to Production.
Step A - Navigate to the Proxy Testing Web Application
To start the test, click on the following link:
https://sso.pilot.cccmypath.org/simplesaml/module.php/core/authenticate.php?as=MISnnn
IMPORTANT: Replace the 'nnn' at the end of each URL with the MIS code that applies to your district (if a district-wide IdP) or to the college (if a single college IdP). The CCC SSO Proxy Team will confirm with you what that code will be for your IdP.
If you receive an error page, either there is an issue with the IDP configuration, the MISnnn value is incorrect, or the district/college code for your Identity Provider has not yet been configured in the SSO Proxy.
Step B - IDP Login
The SSO Proxy will redirect you to your IDP. Log in with a known userid/password.
Step C - Proxy Verification Page
If an error page is displayed, check your IDP configuration to ensure you are configured correctly.
If your IDP is configured correctly, you will see the following page displaying the SAML attributes that were release by your Identity Provider
Step D - Report Testing Feedback to CCC SSO Proxy Team
After testing the Pilot Proxy URL, forward feedback to the CCC SSO Proxy team
If testing the Pilot Proxy was successful, testing the Production Proxy URL is the final step.
STEP 8: Make appropriate metadata changes in Production
Once all the above steps have been completed in Pilot and testing is completed, you will need to make any metadata or configuration changes to the Production IdP environment in order to enable the changes. You will need to download the metadata for the CCC SSO Proxy, similar to the steps taken in Step 4 for Pilot, from the following URL:
Note: you need to replace the 'nnn' at the end of each URL with the MIS code that applies to your district (if a district-wide IdP) or to the college (if a single college IdP).
The CCC IdP Proxy Service Team will confirm with you what that code will be for your IdP.Additional confirmation testing should occur once the changes have been made in Production to verify that the integration is still working as expected. Once this has been done, the integration with the Proxy is complete.