Enabling Feide-users to log into an eduGAIN service provider#

Feide operates a centralized login service for the Norwegian research and education organizations. Feide is connected to eduGAIN, but due to the architecture in Feide there are some additional requirements for service providers. This page documents the process for enabling Feide-users to log into your eduGAIN service provider.

Support for the Feide architecture#

Feide is connected to eduGAIN and uses the same protocol as other organizations connected to eduGAIN (SAML 2.0), but has a different architecture. Specifically, Feide operates a single SAML 2.0 identity provider that represents all organizations.

(The Feide identity provider has the SAML 2.0 entity identifier https://idp.feide.no.)

Organization selection#

When users log into your service they must select their organization. This allows your service to direct the login request to the correct identity provider.

Generally, there are two ways that service providers handle organization selection.

  1. Many service providers simply use the eduGAIN metadata feed for organization selection. In this case users will be able to choose “Feide” on your organization selection page, and the login request will be sent to Feide.

  2. Some service providers manually configure organizations in their systems. In this case, you will have to manually direct login requests for the Norwegian organizations to the Feide identity provider.

Identifying the organization after login#

Some service providers rely on the entity identifier of the SAML 2.0 identity provider to map users to organizations. Since Feide is a single identity provider representing multiple organizations, this will not work. Instead you will need to look at the user attributes in order to identify the organization.

For example, you can look at the eduPersonPrincipalName attribute (username@example.org) or the schacHomeOrganization attribute (example.org). From these attributes you service can see that the user comes from the organization with the domain example.org.

There is also the eduPersonScopedAffiliation attribute (student@example.org), but be aware that this attribute is not mandatory to register in Feide, and many organizations do not have it available.

Attributes in SAML 2.0 metadata#

In order to receive user attributes from Feide, you service needs to list its required attributes in its SAML 2.0 metadata.

Each attribute must be added as a <md:RequestedAttribute>-element. For example:

<md:RequestedAttribute
  NameFormat="urn:oasis:names:tc:SAML:2.0:attrname-format:uri"
  Name="urn:oid:1.3.6.1.4.1.5923.1.1.1.6"
  FriendlyName="eduPersonPrincipalName"
  isRequired="true"
  />

The Name field must contain a urn:oid:-value identifying the attribute. The NameFormat field must be set to urn:oasis:names:tc:SAML:2.0:attrname-format:uri. The FriendlyName and isRequired fields are ignored.

If your service requests an attribute that is not supported by Feide, that attribute is ignored.

(See the example metadata for a more complete example.)

Make the service discoverable#

Feide lists all available eduGAIN services in our self-service portal. In order to be discoverable on that page, it is important that your service has a name and description.

Feide retrieves the name and description of the service from its SAML 2.0 metadata. It looks for the name and description in two locations:

  1. The <mdui:UIInfo> extension.

  2. The <md:AttributeConsumingService> element.

(See the example metadata for details.)

Organizations must activate the service#

Feide is a opt-in federation, where each organization must activate a service before users from that organization can log into the service using Feide. If an organization has not activated your service, that organization will not be available on the Feide login page when logging into your service.

It is up to each organization to decide on a process for activating services in Feide. Normally the best way is to have a user at the organization contact their IT support. IT support can then direct the request to the organizations Feide administrators, who can activate the service.

Note: If no organizations have activated your service, your service will not be added to the Feide login system. In that case, users will receive a “Metadata not found” error:

"Metadata not found" error message

Example SAML 2.0 metadata#

Here we have an example of SAML 2.0 metadata for a service provider. It shows where attribute requirements, name and description can be added to the metadata. Note that your federation operator may have additional requirements for the metadata they publish to eduGAIN.

<md:EntityDescriptor
  entityID="https://sp.example.org/saml"
  xmlns:md="urn:oasis:names:tc:SAML:2.0:metadata"
  xmlns:ds="http://www.w3.org/2000/09/xmldsig#"
  xmlns:mdui="urn:oasis:names:tc:SAML:metadata:ui"
  >
  <md:SPSSODescriptor protocolSupportEnumeration="urn:oasis:names:tc:SAML:2.0:protocol">
    <md:Extensions>
      <mdui:UIInfo>
        <mdui:Description xml:lang="en">This service is just an example.</mdui:Description>
        <mdui:DisplayName xml:lang="en">ExampleService</mdui:DisplayName>
      </mdui:UIInfo>
    </md:Extensions>
    <md:KeyDescriptor use="signing">
      <ds:KeyInfo>
        <ds:X509Data>
          <ds:X509Certificate>
            <!-- [signing certificate] -->
          </ds:X509Certificate>
        </ds:X509Data>
      </ds:KeyInfo>
    </md:KeyDescriptor>
    <md:SingleLogoutService
      Binding="urn:oasis:names:tc:SAML:2.0:bindings:HTTP-Redirect"
      Location="https://sp.example.org/saml2/logout"
      />
    <md:AssertionConsumerService
      Binding="urn:oasis:names:tc:SAML:2.0:bindings:HTTP-POST"
      Location="https://sp.example.org/saml2/acs"
      index="1"
      />
    <md:AttributeConsumingService index="0">
      <md:ServiceName xml:lang="en">ExampleService</md:ServiceName>
      <md:ServiceDescription xml:lang="en">This service is just an example.</md:ServiceDescription>
      <md:RequestedAttribute
        NameFormat="urn:oasis:names:tc:SAML:2.0:attrname-format:uri"
        Name="urn:oid:1.3.6.1.4.1.5923.1.1.1.6"
        FriendlyName="eduPersonPrincipalName"
        isRequired="true"
        />
      <md:RequestedAttribute
        NameFormat="urn:oasis:names:tc:SAML:2.0:attrname-format:uri"
        Name="urn:oid:1.3.6.1.4.1.25178.1.2.9"
        FriendlyName="schacHomeOrganization"
        isRequired="true"
        />
      <md:RequestedAttribute
        NameFormat="urn:oasis:names:tc:SAML:2.0:attrname-format:uri"
        Name="urn:oid:0.9.2342.19200300.100.1.3"
        FriendlyName="mail"
        isRequired="true"
        />
    </md:AttributeConsumingService>
  </md:SPSSODescriptor>
  <md:Organization>
    <md:OrganizationName xml:lang="en">ExampleServiceProvider</md:OrganizationName>
    <md:OrganizationDisplayName xml:lang="en">ExampleServiceProvider</md:OrganizationDisplayName>
    <md:OrganizationURL xml:lang="en">https://www.example.org/</md:OrganizationURL>
  </md:Organization>
</md:EntityDescriptor>