Ctrlk
GXC Main Website
For the complete documentation index, see llms.txt. This page is also available as Markdown.

4G & 5G Onyx Portal Integration with Customer IdP

Introduction

There are two approaches to integrating a Customer IdP with the Onyx Portal:

  1. Direct Integration — In this approach, the customer IdP is configured and integrated directly with Onyx Portal. All IdP-related configuration like entity ID, IdP metadata, Single Sign-On/Single Logout URLs, and certificates are configured directly in the Onyx Portal.

    1. Login

      1. Single Sign-On and Single Logout requests are directly redirected from Onyx Portal to the customer IdP.

      2. User is authenticated by customer IdP and SAML response is sent from the customer IdP to Onyx Portal.

    2. Logout

      1. Single Logout requests are directly redirected from Onyx Portal to the customer IdP.

      2. The logout request is validated by the customer IdP and the SAML response (if any) is sent from the customer IdP to Onyx Portal.

  2. IdP-to-IdP SAML Proxying Integration — In this approach, the customer IdP is configured and integrated with the Onyx IdP. All IdP-related configurations such as entity ID, IdP metadata, Single Sign-On/Single Logout URLs, and certificates are configured in the Onyx IdP. The Single Sign-On and Single Logout requests are redirected from Onyx Portal to the Onyx IdP. Onyx IdP does target IdP discovery based on the RequestedAuthnContext in the SAML authentication request and redirects the Single Sign-On/Logout request to the target IdP.

NOTE: We have chosen to integrate with customer IdPs in IdP Proxy configuration.

IdP-to-IdP Integration Using SAML Proxying

We can use SAML Proxying mechanism to integrate the authentication flows with other SAML2-compliant identity providers.

If a customer has a SAML2-compliant Identity Provider, the process of authenticating users will be delegated to the customer's IdP, instead of relying on Onyx IdP. The resulting assertion is used to generate the user's local username, which is then used in the standard Attribute Resolution process.

The Onyx IdP will become a Service Provider (SP) to the customer's IdP.

Login Flow

Login via Customer IdP (Using SAML Proxying)

1

If the user is from a partner organization having its own IdP integrated with the Onyx Solution, the user should click the Sign In to an Organization link.

2

The user enters his/her organization's name and clicks Login.

3

The Onyx Portal backend generates an authentication request and sends it to the Onyx IdP's SSO URL. The authentication request passes the customer IdP's entityID in RequestedAuthnContext. This helps the Onyx IdP in doing an IdP discovery and proxy the request to the customer's IdP.

4

The Onyx IdP receives the SAML authentication request. Based on the attributes (Tenant ID), it does IdP discovery. Onyx IdP maintains the tenant and target IdP mapping. Based on this mapping, the IdP discovery process identifies the entityID of the target IdP. The authentication request is proxied to the target IdP's SSO URL for SSO authentication.

5

The Customer IdP's login page is displayed, where the user enters his/her user ID/password and proceeds to login.

6

The Customer IdP authenticates the user.

7

On successful authentication, the Customer IdP does attribute resolution to generate the SAML authentication response. Onyx Portal expects the following attributes to be present in the SAML assertion to allow the user access to Onyx Portal.

8

SAML response is generated and sent back to the Onyx IdP.

9

The Onyx IdP receives the SAML response. After attribute resolution and based on the attribute release policy it passes the required attributes in the SAML assertion to the Onyx Portal.

10

The Onyx Portal receives the SAML response from the Onyx IdP. It validates the SAML response and extracts the SAML attributes. The SAML attributes are validated and after all the validations have passed, it allows the user to access the Onyx Portal. The user is redirected to the Onyx Portal's Dashboard page.

User Profile

The Identity Provider shall configure the following user attributes in their user information directory/repository and release the same attributes in SAML assertion.

Attribute Name
Description
Example
Mandatory

mail / urn:oid:0.9.2342.19200300.100.1.3

Email ID of the subject. Not used as primary identifier; honored as long as Subject ID or IDM ID is present in the SAML assertion.

abc@example.com

Y

firstName / givenName

The user's first name.

Roger

N

lastName / sn

The user's last name.

Smith

N

onyxPortalTenantId

Tenant ID of the customer account in Onyx Portal. Communicated to the customer by GXC when the account is created.

CNH

C

onyxPortalRole

Role assigned to the user in Onyx Portal. One of: SUPER ADMIN, ADMIN, VIEWER.

ADMIN

C

C - Conditional. These attributes are required for us to support dynamic User Profile creation in the portal. If they cannot be supplied for some reason, then we have to create an upstream IdP user profile in the Onyx Portal and map it with the customer's tenant and a role (SUPER ADMIN, ADMIN or VIEWER). For information on adding an upstream IdP user, refer to Add Upstream IDP User.

Integration Procedure

Configure Onyx Portal as Service Provider

Get Onyx IdP Metadata to Configure Onyx Portal as a Service Provider in the Customer IdP

The latest Onyx IdP metadata is available at https://idp.gxc.io/idp/shibboleth. This metadata or the URL will be shared with the customer to integrate Onyx Portal as a service provider in their IdP. The necessary service provider specific details are available in the "SPSSODescriptor" block in the Onyx IdP metadata. The configuration procedure is specific to the IdP solution used by the customer and outside the scope of this document. A sample metadata is provided below for reference.

Key information in this IdP metadata:

  • entity ID: https://idp.gxc.io/idp/shibboleth

  • ACS URL: https://idp-svt.gxc.io/idp/profile/Authn/SAML2/POST/SSO

  • Signing Key in SPSSODescriptor block

  • Encryption Key in SPSSODescriptor block

Configure Customer IdP as Upstream IdP in Onyx IdP

Accessing Onyx Portal Before the Customer IdP is Integrated

The first Super Admin user of a customer account (created when the customer account was created) will have an Onyx Portal localized account. This user can log in to the Onyx Portal to configure the customer's own IdP's details.

User Interface to Register Customer IdP Details in Onyx Portal

The Onyx Portal provides a UI screen to register IdP metadata and endpoint details. The customer account's Super Admin user can configure their IdP's metadata (or metadata URL), SSO URL, SLO URL, and entity ID in this screen.

To register the customer IdP's details, click Administration > Add/Edit SSO Config.

Add Upstream IDP User

In case the IdP is not releasing the onyxPortalTenantId and onyxPortalRole attributes, the upstream IdP SSO users can be created in the Onyx Portal.

To create upstream IdP user accounts, click Administration > Add User. The Upstream IdP User option must be enabled for the Onyx Portal to treat the user as an upstream IdP user. The details are used only for mapping the tenant ID and user's role.

Register Customer IdP Metadata in Onyx IdP

After the customer IdP's details are registered, the details are configured in the Onyx IdP (currently, this is a manual procedure as documented below; however, it is planned to be automated in an upcoming release).

  1. Copy the customer IdP's metadata at /opt/shibboleth-idp/metadata/upstream--idp.xml and do the following configuration in metadata-providers.xml.

NOTE: For information on OSU-specific steps to configure OSU IdP, see OSU IdP Integration.

  1. Configure attribute-resolver, attribute-filter, or attribute proxy-pass-through to proxy pass the assertion attributes received from the customer IdP to the Onyx Portal.

  2. Restart the Jetty service.

NOTE: Service restart is required when we configure and integrate a customer IdP with the Onyx IdP. The downtime is less than a minute. Any new login attempts during this downtime will fail. Existing user sessions will not be impacted during this downtime, and the user will continue to use the Onyx Portal without any service interruption.

OSU IdP Integration

How to Get OSU IdP Metadata

OSU's suggestion for federating with them is to define an InCommon metadata source to the Onyx IdP. It is the most secure way to do it, and will automate getting updated information if it changes. It is "set and forget".

  1. Configure a DynamicHTTPMetataProvider to consume per-entity metadata with a minimum cache duration of 10 minutes, and a maximum cache duration of one day.

  1. Create a file %{idp.home}/credentials/inc-md-cert-mdq.pem with the following content.

  1. To "harden" it to only allow OSU's metadata to be loaded, the following metadata filter can be added.

  1. Configure proxy-pass-through to proxy pass the attributes released by the OSU IdP.

Sharing Onyx IdP's Metadata with OSU

To integrate with the Onyx Portal, OSU must register the Onyx IdP as a service provider. Onyx IdP's metadata is available at https://idp.gxc.io/idp/shibboleth. The metadata also contains signing and encryption certificates.

Finalize the Foreign IdP Integration with Onyx IdP

Shibboleth IdP requires a service restart to apply the configuration changes.

To restart Shibboleth IdP, run the following command.

NOTE: Service restart is required when configuring and integrating a customer IdP with the Onyx IdP. The downtime is less than a minute. Any new login attempt during this downtime will fail. Existing user sessions will not be impacted during this downtime, and the user will continue to use the Onyx Portal without any service interruption.

Appendix

Sample SAML Request

Sample SAML Response

Related Documentation

  • 4G & 5G Onyx Portal Multi-Factor Authentication Application Note

  • GXC Glossary

Contact GXC

To get in touch with GXC, please visit https://gxc.io/contact-us/.

Previous4G & 5G Onyx Portal MFA
Next4G AP Deployment Modes

Last updated

Was this helpful?