Overview

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

Service Integration Workflow

To integrate your service with NI4OS-Europe Login, you need to create a registration request using the NI4OS Federation Registry Portal. You can also use the Federation Registry portal to request the reconfiguration or deregistration of an existing deployed service. Service registration and reconfiguration requests typically require approval by an administrator. You can refer to the Federation Registry Documentation for more information.

General Information

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

OpenID Connect - an extension to OAuth 2.0
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:

Name of 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 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.
Acceptable Use Policy / Terms of Use URL: The Acceptable Use Policy should be based on the 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 Keycloak, 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-Europe Login OpenID Provider for user login, you need to obtain OAuth 2.0 credentials by submitting a service registration request using the Federation Registry Portal. The client configuration should include the general information about your service, as described in the #General Information) section.

The configuration of the NI4OS-Europe Login OpenID Provider (OP) is available at https://aai.ni4os.eu/auth/realms/ni4os/.well-known/openid-configuration.

OAuth 2.0 credentials

You need OAuth 2.0 credentials, which typically include a client ID and client secret, to authenticate users through the NI4OS-Europe Login OpenID Provider.

You can specify the client ID and secret when creating/editing your client or let the NI4OS Federation Registry automatically generate them during registration (recommended).

Redirection URIs

OpenID Connect services such as web portals that use the Authorization Code Flow, need to pre-register one or more Redirection URI(s) to which authentication responses from NI4OS-Europe Login will be sent. The NI4OS-Europe Login OpenID Provider utilises exact matching of the redirection URI specified in an authentication request against the URIs pre-registered through the Federation Registry. This is in accordance with OAuth 2.0 Security Best Current Practice, with the matching performed as described in RFC3986 (Simple String Comparison). Redirection URIs SHOULD use use the https scheme as described in Section 3.1.2.1 of the OpenID Connect Core specification. The redirection URI MAY use an alternate scheme, such as one that is intended to identify a callback into a native application.

Example OIDC Client Configurations

Keycloak

If you are using Keycloak as an OpenID Connect Relying Party, then you need to follow the steps below in order to configure NI4OS-Europe Login as an Identity Provider based on OpenID Connect:

Access the administrator console of your Keycloak instance and navigate to "Identity Providers" and then select "OpenID Connect v1.0"
In the next page, complete the following fields:
- Alias: ni4os-oidc
- Display name: NI4OS Login
Scroll down, and complete the rest options:
- Discovery endpoint: https://aai.ni4os.eu/auth/realms/ni4os/.well-known/openid-configuration
- Client ID: <YOUR_CLIENT_ID>
- Client Secret: <YOUR_CLIENT_SECRET>
And then click on the "Add" button.
After adding NI4OS Login as an Identity Provider, scroll down to the "OpenID Connect settings" section and expand the "Advanced" option and then add the scopes that the Service needs. For example:

Scopes: openid voperson_id email profile eduperson_entitlement
Then, scroll down to the "Advanced settings" section and enable the "Trust Email" option and click on "Save" button.
Next, you will need to add two mappers to store the voperson_id and the eduperson_entitlement claims because Keycloak can map only the standard claims. Go to the "Mappers" tab and then click on "Add Mapper".

For the voperson_id claim you will need to add the following options:
- Name: voPersonID
- Sync Mode Override: import
- Mapper Type: Username Template Importer
- Template: ${CLAIM.voperson_id}
- Target: LOCAL
And for the eduperson_entitlement claim:
- Name: eduPersonEntitlement
- Sync Mode Override: Inherit
- Mapper Type: Attribute Importer
- Claim: eduperson_entitlement
- User Attribute Name: eduPersonEntitlement
Note: For other attributes, create a mapper similar to the eduPersonEntitlement mapper.

mod_auth_openidc Apache HTTPD Module

mod_auth_openidc is an Apache HTTPD module for OpenID Connect. If your language/environment supports using Apache HTTPD as a proxy, then you can use the mod_auth_openidc module to secure your web application with OpenID Connect.

To configure mod_auth_openidc you’ll need:

The client_id
The client_secret
The redirect_uri to your application
The NI4OS-Europe Login OpenID Provider configuration URL
mod_auth_openidc specific Apache HTTPD module config

An example configuration would look like the following:

LoadModule auth_openidc_module modules/mod_auth_openidc.so

ServerName ${HOSTIP}

<VirtualHost *:443>

    ServerAdmin webmaster@localhost
    DocumentRoot /var/www/html

    OIDCProviderMetadataURL https://aai.ni4os.eu/auth/realms/ni4os/.well-known/openid-configuration
    OIDCClientID <your-client-id-administered-through-the-federation-registry>
    OIDCClientSecret <your-client-secret-administered-through-the-federation-registry>

    # OIDCRedirectURI is a vanity URL that must point to a path protected by this module but must NOT point to any content
    OIDCRedirectURI https://www.example.com/example/redirect_uri
    OIDCCryptoPassphrase <password>

    # maps the voperson_id claim to the REMOTE_USER environment variable
    OIDCRemoteUserClaim voperson_id

    <Location /protected/>
        AuthType openid-connect
        Require valid-user
    </Location>

</VirtualHost>

Further information on how to configure mod_auth_openidc can be found on the mod_auth_openidc wiki page.

Client Migration to Keycloak

All the clients that were registered in MITREid Connect have been moved to Keycloak preserving all the options (Client ID, Client Secret, Redirect URIs etc.), so you do not need to re-register your Service.

Endpoints

The first thing you need to do is to update the OIDC endpoints according to the OP Metadata. If the Application/Library supports Dynamic Discovery, then you need to update on the issuer. Otherwise, you need to update all the Endpoints separately.

Size of the Tokens

The size of the Access/Refresh Tokens that are issued by Keycloak is larger of the respective Tokens created by MITREid Connect. For example, the size of an Access Token is around 1400 characters, depending on the information that are included in the payload of the JWT. So make sure that your OIDC implementation can handle larger Tokens.

Logout

The Redirect URI query parameter in the logout request has been changed from redirect to post_logout_redirect_uri and must be URL encoded. Also, the value of the post_logout_redirect_uri must be defined in the **Valid Redirect URIs** of the Service configuration in the NI4OS Federation Registry.

Token Introspection

The Token Introspection is available to all the clients that are using any authentication method (client_secret_basic, client_secret_post, client_secret_jwt or private_key_jwt) (Confidential Clients) to the Token Endpoint. Public Clients (clients that do not use any authentication method) will not be able to get a successful response from the Introspection Endpoint.

Common issues

Error messages referring to missing `code_challenge`, `code_challenge_method` or `code_verifier` HTTP parameter

If you get error messages containing the PKCE HTTP parameters, probably the PKCE mode is enabled in your Service Configuration but the Application is not performing the PKCE mode.

To solve this, you need to contact aai-support@ni4os.eu and ask to disable the PKCE mode for your client.

Error messages referring to `invalid_code`

If you try to perform the Authorization Code flow and you get an invalid_code error message, probably the Application sends the authorization request to the Authorization Endpoint of the Keycloak based NI4OS OP and then sends the code to the Token Endpoint of the MITREid Connect based NI4OS OP or vice versa.

To fix this you need to verify that you have updated all the OIDC Endpoints with the Keycloak ones. You can find all the OIDC Endpoints of Keycloak in the OP Metadata.

Error messages referring to the `redirect_uri`

If you try to perform the Authorization Code flow and you get an invalid_redirect_uri error, probably the redirect_uri in the Authorization Request mismatches with the Allowed Redirect URIs in the Service Configuration.

To solve this, you need to update the configuration of your OIDC client through the NI4OS Federation Registry and add the redirect_uri to the list of allowed redirect URIs for your client.

UserInfo `invalid_token` or `401 Unauthorized` error response

If you are trying to make a request to the UserInfo Endpoint and the response contains the invalid_token error message, probably you are using an invalid Token or the UserInfo endpoint is wrong.

To solve this, please make sure the that:

You have obtained an Keycloak issued Access Token and you make a request to the Keycloak based UserInfo Endpoint
You have added the Access Token to the Authorization header of the request

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., Keycloak, 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:

Instance	Production environment
Legacy NI4OS-Europe Login SAML IdP	https://aai.ni4os.eu/proxy/saml2/idp/metadata.php
Keycloak-based NI4OS-Europe Login SAML IdP	https://aai.ni4os.eu/auth/realms/ni4os/protocol/saml/descriptor

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`

Example SAML Service Provider Configurations

Keycloak

If you are using Keycloak as an SAML Service Provider, then you need to follow the steps below in order to register NI4OS Login as an Identity Provider:

Access the administrator console of your Keycloak instance and navigate to "Identity Providers" and then select "SAML v2.0"
In the next page, complete the following fields:
- Alias: ni4os-saml
- Display name: NI4OS Login
Scroll down, and complete the rest options:
- SAML entity descriptor: https://aai.ni4os.eu/proxy/saml2/idp/metadata.php
And then click on the "Add" button.
After adding NI4OS Login as a SAML Identity Provider, scroll down to the "SAML settings" section and edit the following options:
- Principal type: Attribute [Name]
- Principal attribute: urn:oid:1.3.6.1.4.1.25178.4.1.6
- HTTP-POST binding response: On
- Want AuthnRequests signed: On
Note: urn:oid:1.3.6.1.4.1.25178.4.1.6 is the OID presentation of voPersonID attribute.
Then, scroll down to the "Advanced settings" section and enable the "Trust Email" option and click on "Save".
Next, you will need to create a mapper for each attribute that your Service Provider will request from NI4OS Login. Go to the "Mappers" tab and then click on "Add Mapper".

For the voPersonID attribute you will need to add the following options:
- Name: voPersonID
- Sync Mode Override: import
- Mapper Type: Attribute Importer
- Attribute Name: urn:oid:1.3.6.1.4.1.25178.4.1.6
- Friendly Name: voPersonID
- Name Format: ATTRIBUTE_FORMAT_URI
- User Attribute Name: voPersonID
And for the eduperson_entitlement claim:
- Name: eduPersonEntitlement
- Sync Mode Override: Inherit
- Mapper Type: Attribute Importer
- Attribute Name: urn:oid:1.3.6.1.4.1.5923.1.1.1.7
- Friendly Name: eduPersonEntitlement
- Name Format: ATTRIBUTE_FORMAT_URI
- User Attribute Name: eduPersonEntitlement
Note: For other attributes, create a mapper similar to the eduPersonEntitlement mapper.

References

Service Provider Migration to Keycloak

How to Migrate your Service to Keycloak

All the SPs connected to the legacy NI4OS-Europe Login SAML IdP have been moved to Keycloak, so you do not need to re-register your SAML Service.

New Identity Provider Metadata

The first thing you need to do is to update the IdP metadata URL in the SP configuration, according to the Metadata registration section.

New Attributes

Some attributes will not be supported when moving your SP to the Keycloak-based NI4OS-Europe Login SAML IdP. These attributes will be replaced by new ones, as described in the table below:

Deprecated Attributes	New Attributes
`eduPersonScopedAffiliation`	`voPersonExternalAffiliation`
`eduPersonUniqueId`	`voPersonID`

Note: The values of the deprecated attributes will remain the same. Only the name of the attributes is changed.

You need to update the SP configuration to map the values to the new attribute names.

NameID

NameID formats control how the users at IdPs are mapped to users at SPs during single sign-on. The following NameID formats are supported:

Transient (urn:oasis:names:tc:SAML:2.0:nameid-format:transient)
Persistent (urn:oasis:names:tc:SAML:2.0:nameid-format:persistent)
Email address (urn:oasis:names:tc:SAML:1.1:nameid-format:emailAddress)
Unspecified (urn:oasis:names:tc:SAML:1.1:nameid-format:unspecified)

The SPs need to advertise in their metadata which formats they support, otherwise Keycloak will assign the unspecified (urn:oasis:names:tc:SAML:1.1:nameid-format:unspecified) NameID to the SP.

AAI guide for SPs

Contents

Overview

Service Integration Workflow

General Information

OpenID Connect Relying Party