Difference between revisions of "AAI guide for SPs"

From NI4OS wiki
Jump to navigation Jump to search
(Added link to privacy policy template)
(Update list of required policies in general requirements)
(8 intermediate revisions by the same user not shown)
Line 1: Line 1:
{{TOC_right}}
 
 
 
= Overview  =
 
= Overview  =
  
This wiki page contains information about connecting services to the NI4OS AAI service in order to enable federated authentication and authorisation.
+
This wiki page contains information about connecting services to the NI4OS-Europe Login service in order to enable federated authentication and authorisation.
  
 
= General Information =  
 
= General Information =  
The NI4OS-Europe AAI supports both OpenID Connect (an extension to OAuth 2.0) and SAML 2.0. Regardless of which of the two protocols you are going to use, you need to provide the following information to connect your service to the NI4OS-Europe AAI:
 
  
# Name of the service
+
NI4OS-Europe Login supports two authentication and authorisation protocols that you can choose from:
# Short description
+
# [https://openid.net/specs/openid-connect-core-1_0.html OpenID Connect] - an extension to [https://tools.ietf.org/html/rfc6749 OAuth 2.0]
# Privacy statement URL: The privacy policy is used to document the data collected and processed by the service. You can use the [https://docs.google.com/document/d/1ZU7VjH3g7qcfWcz0Z8TTv-vQiVoRA_wOsuMyJaz28Og/edit Privacy Policy template].
+
# [http://docs.oasis-open.org/security/saml/Post2.0/sstc-saml-tech-overview-2.0.html Security Assertion Markup Language (SAML) 2.0]
# Technical contact address(es)
+
 
# Security contact address(es)
+
Regardless of which of the two protocols you are going to use, you need to provide the following information to connect your service to NI4OS-Europe Login:
# Logo URL (if available)
+
 
 +
# Name of the service (in English and optionally in other languages supported by the service)
 +
# Short description of the service
 +
# Website (URL) for localised information about the service; the content found at the URL SHOULD provide more complete information than what provided by the description
 +
# Contact information of the following types:
 +
#* Helpdesk/Support contact information - for generic support questions from end-users about the service
 +
#* Administrative
 +
#* Technical - for technical interoperability problems; the technical contact must be responsible for the technical operation of the service
 +
#* Security/incident response
 +
# Privacy statement URL: The privacy policy is used to document the data collected and processed by the service. It should be compliant with the [https://wiki.refeds.org/display/CODE/Data+Protection+Code+of+Conduct+Home GÉANT Code of Conduct version 1] or any other code of conduct compatible with legislation and guidelines on data protection and privacy including GDPR. You can use the [https://docs.google.com/document/d/1ZU7VjH3g7qcfWcz0Z8TTv-vQiVoRA_wOsuMyJaz28Og/edit Privacy Policy template].
 +
# Acceptable Use Policy / Terms of Use URL: The Acceptable Use Policy should be based on the [https://wise-community.org/wise-baseline-aup/ WISE AUP Baseline template].
 +
# Logo URL (optional for showing in catalogues); if provided, logos SHOULD:
 +
#* use a transparent background where appropriate to facilitate the usage of logos within a user interface
 +
#* use PNG, or GIF (less preferred), images
 +
#* use HTTPS URLs in order to avoid mixed-content warnings within browsers
 +
#* have a size larger than 40000 and smaller than 50000 characters when encoded in base64
 +
 
 +
= OpenID Connect Relying Party =
 +
 
 +
Services can be connected to NI4OS-Europe Login using OpenID Connect (OIDC). NI4OS-Europe Login provides an OpenID Connect (OAuth2) API based on [https://github.com/mitreid-connect/OpenID-Connect-Java-Spring-Server MITREid Connect], which has been [http://openid.net/certification/ certified by the  OpenID Foundation]. You need to install an OpenID Connect Relying Party (OIDC RP) software and integrate it into your application. If you are connecting a web application, then you should choose the '''Authorization Code flow'''. Please refer to https://openid.net/certification/ for a list of certified relying party library implementations.
 +
 
 +
Interconnection with the NI4OS-Europe Login OpenID Provider allows users to sign in using any of the supported backend authentication mechanisms, such as institutional identity providers registered with eduGAIN or Social Providers. Once the user has signed in, NI4OS Login can return OIDC Claims containing information about the authenticated user.
 +
 
 +
== Client registration ==
 +
 
 +
Before your service can use the NI4OS OIDC Provider for user login, you must register a client in order to obtain OAuth 2.0 credentials and register one or more redirect URIs.
 +
 
 +
To register your client, please contact [mailto:aai-support@ni4os.eu aai-support@ni4os.eu]. Your request should include the general information about your service (see [[#General Information]]) and the protocol-specific details below:
 +
 
 +
# One or more '''redirection URIs''' where the NI4OS OIDC Provider will send responses to your authentication requests. Note that redirection URIs MUST use the <code>https</code> scheme
 +
# Token endpoint authentication type - One of the following options:
 +
#* Client Secret over HTTP Basic
 +
#* Client Secret over HTTP POST
 +
# List of '''scopes''' allowed to be requested by your client. The following scopes are available:
 +
#* <code>openid</code> - required for all OpenID Connect clients
 +
#* <code>voperson_id</code> - allows retrieving the user's unique Community User Identifier (CUID) through the <code>voperson_id</code> claim
 +
#* <code>profile</code> - allows retrieving the user's name information through the <code>given_name</code>, <code>family_name</code>, and <code>name</code> claims
 +
#* <code>email</code> - allows retrieving the user's email information through the <code>email</code> and <code>email_verified</code> claims
 +
#* <code>eduperson_entitlement</code> - allows retrieving the user's entitlements (group membership & role information) through the <code>eduperson_entitlement</code> claim
 +
# Contact for receiving PIN to access client credentials - To ensure the security of your client credentials we will send you a PIN (personal identification number) that you need to use in order to access your client credentials. The PIN must be sent through a different means than the email address used to contact us. Please supply a different email address or a keybase, Skype handle.
 +
 
 +
The configuration of the NI4OS-Europe Login OpenID Provider is available at https://aai.ni4os.eu/oidc/.well-known/openid-configuration.
 +
 
  
 
= SAML Service Provider =
 
= SAML Service Provider =
  
To enable federated access to a web-based application, you can connect to the NI4OS AAI IdP as a SAML Service Provider (SP). Users of the application will be redirected to the NI4OS AAI in order to log in, and the NI4OS AAI can authenticate them using any of the supported backend authentication mechanisms, such as institutional IdPs registered with eduGAIN or Social Providers. Once the user is authenticated, the NI4OS AAI will return a SAML assertion to the application containing information about the authenticated user.
+
To enable federated access to a web-based application, you can connect to the SAML Identity Provider (IdP) interface of NI4OS-Europe Login as a SAML Service Provider (SP). Users of the application will be redirected to NI4OS-Europe Login in order to log in, and the NI4OS AAI can authenticate them using any of the supported backend authentication mechanisms, such as institutional IdPs registered with eduGAIN or Social Providers. Once the user is authenticated, the NI4OS AAI will return a SAML assertion to the application containing information about the authenticated user.
  
 
== Metadata registration ==
 
== Metadata registration ==
Line 27: Line 66:
 
== Metadata ==
 
== Metadata ==
  
Metadata provided by your SP should contain a descriptive name of the service that your SP represents in at least English. It is recommended to also provide the name in other languages which are commonly used in the geographic scope of the deployment. The name should be placed in the <tt><md:ServiceName></tt> in the <tt><md:AttributeConsumingService></tt> container.
+
Metadata provided by your SP should contain a descriptive name of the service that your SP represents in at least English. It is recommended to also provide the name in other languages which are commonly used in the geographic scope of the deployment. The name should be placed in the <tt><md:ServiceName></tt> in the <tt><md:AttributeConsumingService></tt> container.  
 
 
It is recommended that the <tt><md:IDPSSODescriptor></tt> element included in your SP metadata contains both an <tt>AuthnRequestsSigned</tt> and an <tt>WantAssertionsSigned</tt> attribute set to <tt>true</tt>.
 
 
 
Your SP metadata should also contain contact information for support and for a technical contact. The <tt><md:EntityDescriptor></tt> element should contain both a <tt><md:ContactPerson></tt> element with a <tt>contactType</tt> of "<tt>support</tt>" and a <tt><md:ContactPerson></tt> element with a <tt>contactType</tt> of "<tt>technical</tt>". The <tt><md:ContactPerson></tt> elements should contain at least one <tt><md:EmailAddress></tt>. The support address may be used for generic support questions about the service, while the technical contact may be contacted regarding technical interoperability problems. The technical contact must be responsible for the technical operation of the service represented by your SP.
 
 
 
  
 
== Attributes ==
 
== Attributes ==
  
The NI4OS AAI IdP is guaranteed to release a minimal subset of the [https://refeds.org/category/research-and-scholarship REFEDS R&S] attribute bundle to connected Service Providers without administrative involvement, subject to user consent. The following attributes constitute a minimal subset of the R&S attribute bundle:
+
The NI4OS-Europe Login IdP is guaranteed to release the following attributes:
  
* Persistent, non-reassignable, non-targeted, opaque, globally unique NI4OS user ID (<tt>subject-id</tt>); this is always scoped <tt>@ni4os.eu</tt>
+
* Community User Identifier (CUID) which is a globally unique, opaque, persistent and non-reassignable identifier identifying the user (<tt>voPersonID</tt>). For users whose community identity is managed by NI4OS-Europe Login, this identifier is of the form <tt><uniqueID>@ni4os.eu</tt>. The <tt><uniqueID></tt> portion is an opaque identifier issued by NI4OS-Europe Login
 
* Email address (<tt>mail</tt>)
 
* Email address (<tt>mail</tt>)
* Display name (<tt>displayName</tt>) OR (<tt>givenName</tt> AND <tt>sn</tt>)
+
* Display name (<tt>displayName</tt>)
 +
* Given name (<tt>givenName</tt>
 +
* Family name (<tt>sn</tt>)
  
 
A more extensive list of all the attributes that may be made available to Service Providers is included in the following table:
 
A more extensive list of all the attributes that may be made available to Service Providers is included in the following table:
Line 50: Line 86:
 
! Example value
 
! Example value
 
|-
 
|-
|<tt>subject-id</tt>
+
|<tt>voPersonID</tt>
 +
|<tt>urn:oid:1.3.6.1.4.1.25178.4.1.6</tt>
 +
|<tt>n472285@ni4os.eu</tt>
 +
|-
 +
|-
 +
|<tt>subject-id</tt> (<i>deprecated</i> - see <tt>voPersonID</tt>)
 
|<tt>urn:oasis:names:tc:SAML:attribute:subject-id</tt>
 
|<tt>urn:oasis:names:tc:SAML:attribute:subject-id</tt>
 
|<tt>n472285@ni4os.eu</tt>
 
|<tt>n472285@ni4os.eu</tt>
Line 73: Line 114:
 
|<tt>urn:oid:1.3.6.1.4.1.5923.1.1.1.11</tt>
 
|<tt>urn:oid:1.3.6.1.4.1.5923.1.1.1.11</tt>
 
|TBD
 
|TBD
|-
 
|<tt>distinguishedName</tt>
 
|<tt>urn:oid:2.5.4.49</tt>
 
|<tt>/C=NL/O=Example.org/CN=John Doe</tt>
 
 
|-
 
|-
 
|<tt>eduPersonScopedAffiliation</tt>
 
|<tt>eduPersonScopedAffiliation</tt>
Line 89: Line 126:
 
== Attribute-based authorisation ==
 
== Attribute-based authorisation ==
  
The NI4OS AAI provides information about the authenticated user that may be used by Service Providers in order to control user access to resources. This information is provided by the NI4OS AAI IdP in the [[#Attributes|SAML attribute assertion]]. The table below lists the SAML attributes that are relevant for user authorisation:
+
The NI4OS-Europe Login service provides information about the authenticated user that may be used by Service Providers in order to control user access to resources. This information is provided by the NI4OS-Europe Login IdP in the [[#Attributes|SAML attribute assertion]]. The table below lists the SAML attributes that are relevant for user authorisation:
  
 
{| class="wikitable"
 
{| class="wikitable"
Line 104: Line 141:
  
 
== References ==
 
== References ==
* [https://wiki.shibboleth.net/confluence/display/SHIB2/NativeSPConfiguration Shibboleth SP Configuration]
+
* [https://shibboleth.atlassian.net/wiki/spaces/SP3/pages/2063695920/Configuration Shibboleth SP Configuration]
 
* [https://simplesamlphp.org/docs/stable/simplesamlphp-sp SimpleSAMLphp Service Provider QuickStart]
 
* [https://simplesamlphp.org/docs/stable/simplesamlphp-sp SimpleSAMLphp Service Provider QuickStart]
 
* [https://github.com/UNINETT/mod_auth_mellon Simple SAML 2.0 service provider with mod_auth_mellon Apache module]
 
* [https://github.com/UNINETT/mod_auth_mellon Simple SAML 2.0 service provider with mod_auth_mellon Apache module]
 
= OpenID Connect Service Provider =
 
 
Service Providers can be integrated with the NI4OS AAI using OpenID Connect (OIDC) as an alternative to the SAML2 protocol. To allow this, the NI4OS AAI IdP provides an OpenID Connect (OAuth2) API based on [https://github.com/mitreid-connect/OpenID-Connect-Java-Spring-Server MITREid Connect], which has been [http://openid.net/certification/ certified by the  OpenID Foundation]. Interconnection with the NI4OS AAI OIDC Provider allows users to sign in using any of the supported backend authentication mechanisms, such as institutional IdPs registered with eduGAIN or Social Providers. Once the user has signed in, the NI4OS AAI can return OIDC Claims containing information about the authenticated user.
 
 
== Client registration ==
 
 
Before your service can use the NI4OS OIDC Provider for user login, you must register a client in order to obtain OAuth 2.0 credentials and register one or more redirect URIs.
 
 
=== Obtaining OAuth 2.0 credentials ===
 
 
You need OAuth 2.0 credentials, including a client ID and client secret, to authenticate users through the NI4OS AAI OIDC Provider.
 

Revision as of 12:48, 17 January 2022

Overview

This wiki page contains information about connecting services to the NI4OS-Europe Login service in order to enable federated authentication and authorisation.

General Information

NI4OS-Europe Login supports two authentication and authorisation protocols that you can choose from:

  1. OpenID Connect - an extension to OAuth 2.0
  2. Security Assertion Markup Language (SAML) 2.0

Regardless of which of the two protocols you are going to use, you need to provide the following information to connect your service to NI4OS-Europe Login:

  1. Name of the service (in English and optionally in other languages supported by the service)
  2. Short description of the service
  3. Website (URL) for localised information about the service; the content found at the URL SHOULD provide more complete information than what provided by the description
  4. Contact information of the following types:
    • Helpdesk/Support contact information - for generic support questions from end-users about the service
    • Administrative
    • Technical - for technical interoperability problems; the technical contact must be responsible for the technical operation of the service
    • Security/incident response
  5. Privacy statement URL: The privacy policy is used to document the data collected and processed by the service. It should be compliant with the GÉANT Code of Conduct version 1 or any other code of conduct compatible with legislation and guidelines on data protection and privacy including GDPR. You can use the Privacy Policy template.
  6. Acceptable Use Policy / Terms of Use URL: The Acceptable Use Policy should be based on the WISE AUP Baseline template.
  7. Logo URL (optional for showing in catalogues); if provided, logos SHOULD:
    • use a transparent background where appropriate to facilitate the usage of logos within a user interface
    • use PNG, or GIF (less preferred), images
    • use HTTPS URLs in order to avoid mixed-content warnings within browsers
    • have a size larger than 40000 and smaller than 50000 characters when encoded in base64

OpenID Connect Relying Party

Services can be connected to NI4OS-Europe Login using OpenID Connect (OIDC). NI4OS-Europe Login provides an OpenID Connect (OAuth2) API based on MITREid Connect, which has been certified by the OpenID Foundation. You need to install an OpenID Connect Relying Party (OIDC RP) software and integrate it into your application. If you are connecting a web application, then you should choose the Authorization Code flow. Please refer to https://openid.net/certification/ for a list of certified relying party library implementations.

Interconnection with the NI4OS-Europe Login OpenID Provider allows users to sign in using any of the supported backend authentication mechanisms, such as institutional identity providers registered with eduGAIN or Social Providers. Once the user has signed in, NI4OS Login can return OIDC Claims containing information about the authenticated user.

Client registration

Before your service can use the NI4OS OIDC Provider for user login, you must register a client in order to obtain OAuth 2.0 credentials and register one or more redirect URIs.

To register your client, please contact aai-support@ni4os.eu. Your request should include the general information about your service (see #General Information) and the protocol-specific details below:

  1. One or more redirection URIs where the NI4OS OIDC Provider will send responses to your authentication requests. Note that redirection URIs MUST use the https scheme
  2. Token endpoint authentication type - One of the following options:
    • Client Secret over HTTP Basic
    • Client Secret over HTTP POST
  3. List of scopes allowed to be requested by your client. The following scopes are available:
    • openid - required for all OpenID Connect clients
    • voperson_id - allows retrieving the user's unique Community User Identifier (CUID) through the voperson_id claim
    • profile - allows retrieving the user's name information through the given_name, family_name, and name claims
    • email - allows retrieving the user's email information through the email and email_verified claims
    • eduperson_entitlement - allows retrieving the user's entitlements (group membership & role information) through the eduperson_entitlement claim
  4. Contact for receiving PIN to access client credentials - To ensure the security of your client credentials we will send you a PIN (personal identification number) that you need to use in order to access your client credentials. The PIN must be sent through a different means than the email address used to contact us. Please supply a different email address or a keybase, Skype handle.

The configuration of the NI4OS-Europe Login OpenID Provider is available at https://aai.ni4os.eu/oidc/.well-known/openid-configuration.


SAML Service Provider

To enable federated access to a web-based application, you can connect to the SAML Identity Provider (IdP) interface of NI4OS-Europe Login as a SAML Service Provider (SP). Users of the application will be redirected to NI4OS-Europe Login in order to log in, and the NI4OS AAI can authenticate them using any of the supported backend authentication mechanisms, such as institutional IdPs registered with eduGAIN or Social Providers. Once the user is authenticated, the NI4OS AAI will return a SAML assertion to the application containing information about the authenticated user.

Metadata registration

SAML authentication relies on the use of metadata. Both parties (you as a SP and the NI4OS AAI IdP) need to exchange metadata in order to know and trust each other. The metadata include information such as the location of the service endpoints that need to be invoked, as well as the certificates that will be used to sign SAML messages. The format of the exchanged metadata should be based on the XML-based SAML 2.0 specification. Usually, you will not need to manually create such an XML document, as this is automatically generated by all major SAML 2.0 SP software solutions (e.g., Shibboleth, SimpleSAMLphp, and mod_auth_mellon). It is important that you serve your metadata over HTTPS using a browser-friendly SSL certificate, i.e. issued by a trusted certificate authority.

You can get the metadata of the NI4OS AAI IdP Proxy on a dedicated URL: https://aai.ni4os.eu/proxy/saml2/idp/metadata.php

Metadata

Metadata provided by your SP should contain a descriptive name of the service that your SP represents in at least English. It is recommended to also provide the name in other languages which are commonly used in the geographic scope of the deployment. The name should be placed in the <md:ServiceName> in the <md:AttributeConsumingService> container.

Attributes

The NI4OS-Europe Login IdP is guaranteed to release the following attributes:

  • Community User Identifier (CUID) which is a globally unique, opaque, persistent and non-reassignable identifier identifying the user (voPersonID). For users whose community identity is managed by NI4OS-Europe Login, this identifier is of the form <uniqueID>@ni4os.eu. The <uniqueID> portion is an opaque identifier issued by NI4OS-Europe Login
  • Email address (mail)
  • Display name (displayName)
  • Given name (givenName
  • Family name (sn)

A more extensive list of all the attributes that may be made available to Service Providers is included in the following table:

Attribute friendly name Attribute OID Example value
voPersonID urn:oid:1.3.6.1.4.1.25178.4.1.6 n472285@ni4os.eu
subject-id (deprecated - see voPersonID) urn:oasis:names:tc:SAML:attribute:subject-id n472285@ni4os.eu
mail urn:oid:0.9.2342.19200300.100.1.3 john.doe@example.org
displayName urn:oid:2.16.840.1.113730.3.1.241 John Doe
givenName urn:oid:2.5.4.42 John
sn urn:oid:2.5.4.4 Doe
eduPersonAssurance urn:oid:1.3.6.1.4.1.5923.1.1.1.11 TBD
eduPersonScopedAffiliation urn:oid:1.3.6.1.4.1.5923.1.1.1.9 faculty@example.org
eduPersonEntitlement urn:oid:1.3.6.1.4.1.5923.1.1.1.7 urn:mace:geant:ni4os.eu:group:test-group:role=member#aai.ni4os.eu

Attribute-based authorisation

The NI4OS-Europe Login service provides information about the authenticated user that may be used by Service Providers in order to control user access to resources. This information is provided by the NI4OS-Europe Login IdP in the SAML attribute assertion. The table below lists the SAML attributes that are relevant for user authorisation:

Description SAML Attribute
Group membership/roles of the authenticated user eduPersonEntitlement
Level of Assurance (LoA) eduPersonAssurance

References