|
| 1 | +# Connecting to the Open Science Framework (OSF) via our Shibboleth/SAML Service Provider |
| 2 | + |
| 3 | +This article provides general information about the COS's Shibboleth/SAML SSO integration for organizations who have signed the *OSF for Institutions Offer of Services* letter. |
| 4 | + |
| 5 | +## What is Single Sign-On? |
| 6 | + |
| 7 | +In general, Single Sign-On, or SSO, allows users authenticated with one trusted system (e.g. university network) to also authenticate using those same “home” credentials with another trusted network (e.g. OSF). In the case of the second authentication, users are not asked to log in again, but instead the authenticated credentials are shared between systems. |
| 8 | + |
| 9 | +## Who can use Single Sign-On with OSF? |
| 10 | + |
| 11 | +Organizations that have implemented a SAML 2.0 Identity Provider (IdP) and signed the *OSF for Institutions Offer of Services* are eligible to use this feature. |
| 12 | + |
| 13 | +### A few notes: |
| 14 | + |
| 15 | +* Current OSF users who have already set up accounts with a different login, will be able to retain those credentials and choose to login with personal or institutional credentials. |
| 16 | + |
| 17 | +* Users’ authentication to the OSF service using SSO cannot also use the “forgot Password” link on the OSF website to remind them of their credentials, as their user credentials are specific to and managed by their organization. |
| 18 | + |
| 19 | +* OSF also provides extra features such as Shared SSO, Selective SSO and Institutional Dashboard, which all require extra configurations. This guide does not include technical guide for them since they are institution and/or SSO specific. |
| 20 | + |
| 21 | +## Technical Implementation |
| 22 | + |
| 23 | +### Institutions registered with the InCommon Federation |
| 24 | + |
| 25 | +The InCommon Federation provides secure single sign-on access to cloud and local services, and global collaboration tools. COS is a [Research & Scholarship Entity Category (R&S)](https://refeds.org/category/research-and-scholarship) Service Provider (SP) registered with the [InCommon Federation](https://www.incommon.org/federation/). |
| 26 | + |
| 27 | +> * SP Entity ID: `https://accounts.osf.io/shibboleth` |
| 28 | +> * Required Attributes: |
| 29 | +> * `eduPersonPrincipalName` for user's institutional identity |
| 30 | +> * `mail` for user's email |
| 31 | +> * `displayName` for user's full name (or a pair of `givenName` **AND** `sn` for user's first and last name) |
| 32 | +
|
| 33 | +* Note that only COS's production SP server is registered with the InCommon Federation. Both IdP and SP being registered with InCommon makes it no longer necessary to configure a test server before going production. If you need to connect to COS's test SP server, follow the notes mentioned in **Other Institutions** below. |
| 34 | + |
| 35 | + |
| 36 | +### Institutions registered with eduGAIN Participants |
| 37 | + |
| 38 | +[eduGAIN](https://edugain.org/) is a global service that provides an efficient, flexible way for participating federations, and their affiliated users and services, to interconnect. The InCommon Federation is the U.S. participant. If your institution is registered with your local participant, you can use the above guide. Note that you may need to enable **interfederation** if it is an option and if it is disabled by default. Learn more about eduGAIN from [what is eduGAIN](https://edugain.org/about-edugain/what-is-edugain/), [key concepts](https://edugain.org/about-edugain/key-concepts/), [participants](https://technical.edugain.org/status) and [usage guide](https://edugain.org/participants/how-to-use-edugain/); learn more about interfederation from [InCommon's perspective](https://spaces.at.internet2.edu/display/federation/Interfederation+and+eduGAIN). |
| 39 | + |
| 40 | +### Other Institutions |
| 41 | + |
| 42 | +For institutions that are not registered with any participant of eduGAIN, COS offers a [SAML 2.0](https://docs.oasis-open.org/security/saml/Post2.0/sstc-saml-tech-overview-2.0.html) Service Provider (SP) using [Shibboleth 2.0](https://wiki.shibboleth.net/confluence/display/SHIB2/Home). Follow the following guide to manually configure your IdP server. |
| 43 | + |
| 44 | +* Ensure that your IT administrators have loaded COS's SP metadata into your IdP. |
| 45 | + * Production: https://accounts.osf.io/Shibboleth.sso/Metadata |
| 46 | + * Entity ID: `https://accounts.osf.io/shibboleth` |
| 47 | + |
| 48 | + * Test and/or staging: https://accounts.test.osf.io/Shibboleth.sso/Metadata |
| 49 | + * Entity ID: `https://accounts.test.osf.io/shibboleth` |
| 50 | + |
| 51 | +* Ensure that your IT administrators are releasing the three required pieces of information listed below. Inform COS of the attribute name you use for each of them. |
| 52 | + * Required Attribute |
| 53 | + * Unique identifier for the user |
| 54 | + * User's institutional email |
| 55 | + * Either of the follwoing two |
| 56 | + * User's full name |
| 57 | + * User's first **AND** last name |
| 58 | + * Attribute name and format |
| 59 | + * We strongly recommend using URNs that are already configured and mapped in our SP server. Athough we support many format, `eduPerson`(https://wiki.refeds.org/display/STAN/eduPerson) is the preferred one. Here are the URNs for aformentioned required attributes. |
| 60 | + * For identity, there are two options, please let us know which one you choose. |
| 61 | + * `urn:oid:1.3.6.1.4.1.5923.1.1.1.6`: this is the `eppn` which needs to be scoped with the default delimiter `@`. |
| 62 | + * This attribute looks like an email; it may or may not be an actual email; but it **SHOULD NOT** be used for the email attribute. |
| 63 | + * `urn:oid:0.9.2342.19200300.100.1.1`: this is the `uid` which doesn't need to be scoped |
| 64 | + * For the email, use `urn:oid:0.9.2342.19200300.100.1.3`, which is the `mail` |
| 65 | + * For the full name, use `urn:oid:2.16.840.1.113730.3.1.241`, which is the `displayName` |
| 66 | + * For the first name, use `urn:oid:2.5.4.42`, which is the `givenName` |
| 67 | + * For the last name, use `urn:oid:2.5.4.4`, which is the `sn` |
| 68 | + |
| 69 | +* Provide COS with the metadata URL for your IdP server. |
| 70 | + |
| 71 | +* Provide COS with the entiry ID for your IdP server, which should be the same as the one defined in your metadata. |
| 72 | + |
| 73 | +* It is recommended that a temporary institution test account is created for COS engineers if possible, which will significantly aid and accelerate the process. |
| 74 | + |
| 75 | +### For All Institutions |
| 76 | + |
| 77 | +Inform COS of the user you would like to test with; your COS contact will ensure your account is ready to go and will send you a link to test the SSO configuration setup for your institution. |
| 78 | + |
| 79 | +## Alternative SSO Options |
| 80 | + |
| 81 | +COS strongly recommends using SAML SSO when connecting to the OSF. However, if this is not available at your institution, inform COS of alternative SSO options you have. |
0 commit comments