Skip to content

Commit

Permalink
Update Check-in service integration guide for SAML SPs
Browse files Browse the repository at this point in the history
  • Loading branch information
@NicolasLiampotis
NicolasLiampotis committed Oct 11, 2023
1 parent 884381e commit 5042aeb
Show file tree
Hide file tree
Showing 2 changed files with 62 additions and 34 deletions.
96 changes: 62 additions & 34 deletions content/en/providers/check-in/sp/_index.md
View file
Original file line number Diff line number Diff line change
Expand Up @@ -149,7 +149,7 @@ more information can be found in the protocol-specific sections that follow.

| Protocol | Production environment |
| -------------- | --------------------------------------------------------------------- |
| SAML | <https://aai.egi.eu/proxy/saml2/idp/metadata.php> |
| SAML | <https://aai.egi.eu/auth/realms/egi/protocol/saml/descriptor> |
| OpenID Connect | <https://aai.egi.eu/auth/realms/egi/.well-known/openid-configuration> |

{{< /tabx >}}
Expand All @@ -158,7 +158,7 @@ more information can be found in the protocol-specific sections that follow.

| Protocol | Demo environment |
| -------------- | -------------------------------------------------------------------------- |
| SAML | <https://aai-demo.egi.eu/proxy/saml2/idp/metadata.php> |
| SAML | <https://aai-demo.egi.eu/auth/realms/egi/protocol/saml/descriptor> |
| OpenID Connect | <https://aai-demo.egi.eu/auth/realms/egi/.well-known/openid-configuration> |

{{< /tabx >}}
Expand All @@ -167,7 +167,7 @@ more information can be found in the protocol-specific sections that follow.

| Protocol | Development environment |
| -------------- | ------------------------------------------------------------------------- |
| SAML | <https://aai-dev.egi.eu/proxy/saml2/idp/metadata.php> |
| SAML | <https://aai-dev.egi.eu/auth/realms/egi/protocol/saml/descriptor> |
| OpenID Connect | <https://aai-dev.egi.eu/auth/realms/egi/.well-known/openid-configuration> |

{{< /tabx >}}
Expand Down Expand Up @@ -202,41 +202,46 @@ certificate, i.e. issued by a trusted certificate authority.
You can get the metadata of the EGI Check-in IdP Proxy on a dedicated URL that
depends on the integration environment being used:

<!-- markdownlint-disable no-inline-html -->

{{< tabpanex >}}

{{< tabx header="Production" >}}

| Production environment |
| ------------------------------------------------- |
| <https://aai.egi.eu/proxy/saml2/idp/metadata.php> |
| Instance | Production environment |
| ------------------------------- | ------------------------------------------------------------------ |
| Keycloak-based EGI Check-in IdP | <ul><li>SAML Metadata URL: <https://aai.egi.eu/auth/realms/egi/protocol/saml/descriptor></li><li>SAML entity ID: `https://aai.egi.eu/auth/realms/egi`</li></ul> |
| Legacy EGI Check-in IdP | <ul><li>SAML Metadata URL: <https://aai.egi.eu/proxy/saml2/idp/metadata.php></li><li>SAML entity ID: `https://aai.egi.eu/proxy/saml2/idp/metadata.php`</li></ul> |

{{< /tabx >}}

{{< tabx header="Demo" >}}

| Instance | Demo environment |
| ------------------------------- | ------------------------------------------------------------------ |
| Legacy EGI Check-in IdP | <https://aai-demo.egi.eu/proxy/saml2/idp/metadata.php> |
| Keycloak-based EGI Check-in IdP | <https://aai-demo.egi.eu/auth/realms/egi/protocol/saml/descriptor> |
| Keycloak-based EGI Check-in IdP | <ul><li>SAML Metadata URL: <https://aai-demo.egi.eu/auth/realms/egi/protocol/saml/descriptor></li><li>SAML entity ID: `https://aai-demo.egi.eu/auth/realms/egi`</li></ul> |
| Legacy EGI Check-in IdP | <ul><li>SAML Metadata URL: <https://aai-demo.egi.eu/proxy/saml2/idp/metadata.php></li><li>SAML entity ID: `https://aai-demo.egi.eu/proxy/saml2/idp/metadata.php`</li></ul> |

{{< /tabx >}}

{{< tabx header="Development" >}}

| Instance | Development environment |
| ------------------------------- | ----------------------------------------------------------------- |
| Legacy EGI Check-in IdP | <https://aai-dev.egi.eu/proxy/saml2/idp/metadata.php> |
| Keycloak-based EGI Check-in IdP | <https://aai-dev.egi.eu/auth/realms/egi/protocol/saml/descriptor> |
| Keycloak-based EGI Check-in IdP | <ul><li>SAML Metadata URL: <https://aai-dev.egi.eu/auth/realms/egi/protocol/saml/descriptor></li><li>SAML entity ID: `https://aai-dev.egi.eu/auth/realms/egi`</li></ul> |
| Legacy EGI Check-in IdP | <ul><li>SAML Metadata URL: <https://aai-dev.egi.eu/proxy/saml2/idp/metadata.php></li><li>SAML entity ID: `https://aai-dev.egi.eu/proxy/saml2/idp/metadata.php`</li></ul> |

{{< /tabx >}}

{{< /tabpanex >}}

To register your SAML SP, you must submit a service registration request at
[Federation Registry](https://aai.egi.eu/federation). Your request should
include the general information about your service (see
[General Information](#general-information)) and the SP's metadata and entity
ID.
<!-- markdownlint-enable no-inline-html -->

To register your SAML SP, you must submit a service registration request
through the [Federation Registry](https://aai.egi.eu/federation). Your request
should include essential information about your service, as outlined in the
[General Information](#general-information) section, along with your SP's
metadata URL and entity ID.

### Metadata

Expand Down Expand Up @@ -318,16 +323,28 @@ attributes that are relevant for user authorisation:
### Service Provider Migration to Keycloak

The migration guide below applies to SAML Service Providers (SPs) registered in
the **Development** and **Demo** environments of Check-in.
the **Development**, **Demo** and **Production** environments of Check-in.

**Development and Demo**: Beginning March 9, 2023, clients using the legacy
**Development and Demo**: Beginning March 9, 2023, SAML SPs using the legacy
Check-in IdP metadata will no longer be supported.

**Production**: Beginning December 12, 2023, SAML SPs using the legacy
Check-in IdP metadata will no longer be supported.

#### How to Migrate your Service to Keycloak

All the SPs that were registered to the legacy EGI Check-in IdP in the **Demo**
environment have been moved to Keycloak, so you do not need to re-register your
Service.
If your SAML SP is not yet registered in the
[Federation Registry](https://aai.egi.eu/federation), you will need to submit
a service registration request. This request should include essential
information about your service, as described in the
[General Information](#general-information) section, in addition to your SAML
SP's metadata URL and entity ID.

If your SAML SP is already registered, please ensure the accuracy of the
information under the **General** tab, particularly the policy and contact
details, as well as the **Protocol Specific** tab.
Pay special attention to the new **Requested Attributes** section, which
allows you to manage the user attributes available through Check-in.

{{% alert title="Important" color="warning" %}} If your SAML SP relies on
experimental features of Check-in which are only available in the
Expand All @@ -343,9 +360,9 @@ section.

##### New Attributes

Some attributes will not be supported when moving your SP to the Keycloak-based
EGI Check-in IdP. These attributes will be replaced by new ones, as described in
the table below:
When migrating your SP to the Keycloak-based EGI Check-in IdP, please be aware
that some attributes will no longer be supported. These deprecated attributes
will be replaced by new ones, as detailed in the table below:

| Deprecated Attributes | New Attributes |
| ---------------------------- | ----------------------------- |
Expand All @@ -354,23 +371,29 @@ the table below:
| `eduPersonUniqueId` | `voPersonID` |

{{% alert title="Note" color="info" %}} The values of the deprecated attributes
will remain the same. Only the name of the attributes is changed.{{% /alert %}}
will remain unchanged; only the attribute names will be different.{{% /alert %}}

You need to update the SP configuration to map the values the new attribute
names.
Ensure that you update the attribute mapping in your SP configuration to align
with the new attribute names.

##### NameID

NameID formats control how the users at IdPs are mapped to users at SPs during
single sign-on. The SPs need to advertise in their metadata which of the
following formats they support, otherwise Keycloak will assign the unspecified
(`urn:oasis:names:tc:SAML:1.1:nameid-format:unspecified`) NameID to the SP.
Use of `<saml:NameID>` elements is intended for the Single Logout profile and
is not suitable for long-term identification of users.
For user identification, you should use the `voPersonID` SAML attribute, as
detailed in the [User attributes](#user-attributes) section.
Your SAML SP should explicitly specify in its metadata the NameID formats it
supports from the following options:

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

Otherwise, Keycloak will assign the unspecified
(`urn:oasis:names:tc:SAML:1.1:nameid-format:unspecified`) NameID format to
your SP.

### References

- [Keycloak Service Provider Documentation](https://www.keycloak.org/docs/latest/server_admin/#saml-v2-0-identity-providers)
Expand Down Expand Up @@ -399,7 +422,7 @@ the steps below in order to register EGI Check-in as an Identity Provider:

Scroll down, and complete the rest options:

- SAML entity descriptor: `https://aai.egi.eu/proxy/saml2/idp/metadata.php`
- SAML entity descriptor: `https://aai.egi.eu/auth/realms/egi/protocol/saml/descriptor`

![Add SAML IdP](saml-examples-keycloak-add-saml-idp-2.png)

Expand All @@ -411,10 +434,15 @@ the steps below in order to register EGI Check-in as an Identity Provider:
- 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`
- HTTP-POST binding for AuthnRequest: `Off`
- HTTP-POST binding logout: `Off`
- Want AuthnRequests signed: `Off`
- Want Assertions signed: `Off`
- Want Assertions encrypted: `On`
- Validate Signatures: `On`

{{% alert title="Note" color="info" %}} `urn:oid:1.3.6.1.4.1.25178.4.1.6` is
the OID presentation of voPersonID attribute.{{% /alert %}}
the OID presentation of the `voPersonID` attribute.{{% /alert %}}

![SAML Settings](saml-examples-keycloak-saml-idp-saml-setting.png)

Expand Down
Binary file modified content/en/providers/check-in/sp/saml-examples-keycloak-saml-idp-saml-setting.png
View file
Loading
Sorry, something went wrong. Reload?
Sorry, we cannot display this file.
Sorry, this file is invalid so it cannot be displayed.

0 comments on commit 5042aeb

Please sign in to comment.