This site requires JavaScript to be enabled

Notifications

External Customer KB > General > Trusted IdP (Relying Party Trust)
Trusted IdP (Relying Party Trust)
Article: KB0010318 Published: 04/22/2021 Last modified: 04/21/2021

The Trusted IdP (identity provider) feature in OneLogin enables you to configure multiple identity providers to securely sign users into OneLogin and OneLogin-protected applications. Trusted IdP supports 3 protocols: SAML, OIDC and OAuth.

This allows OneLogin to support the following scenarios:

  1. Users authenticate into OneLogin and it’s portal using a SAML assertion (or OIDC/OAuth flow) from 1 or more 3rd party identity providers. This can be thought of as the “Standard” mode.

  2. Users authenticate into OneLogin using a SAML assertion (or OIDC/OAuth flow) from 1 or more 3rd party identity providers but instead of loading the OneLogin Portal can access and gain SSO  to any application integrated with OneLogin (SAML, OIDC, WS-Federation, Forms-based or via OneLogin Access. This also utilizes Standard mode.

  3. Authenticate users from one or more 3rd party identity providers into SAML apps integrated with  OneLogin via a proxy mode. This allows several identity providers to securely authenticate users into shared applications, such as Salesforce and Google Apps, even though these apps only support one identity provider. OneLogin accounts, or individual OneLogin licenses, aren't required to authenticate. Note; this approach has numerous limitations compared to the standard mode.

  4. Create new users with just-in-time provisioning (JIT), with information specified by trusted identity providers.

Note: You must enable Multi-Step Login Flow.

Using an analogy of a hub and spoke model, the identity provider, of which there can be many, can be thought of as Spokes while the OneLogin tenant, where the Trusted IdP feature is implemented, can be considered the Hub. The Spokes can be any identity provider from any vendor (including other OneLogin tenants) provided they support one of SAML, OIDC or OAuth.

The Trusted IdP feature is an extremely powerful capability to combine with OneLogin’s MSP Reseller model (). With the Reseller model (https://www.onelogin.com/partners/msp), partners can create and manage all their customer accounts from a single OneLogin MSP account and provide isolated tenants for end customers. Trusted IdP can link those accounts for SSO, provisioning and seamless access to shared services.

Standard Mode 

Standard mode can be used to both gain access to your OneLogin tenant’s portal as well as gain access to downstream applications integrated with your tenant. 

When a user completes authentication with an IdP and returns to OneLogin as the hub in their identity ecosystem, the user's policy settings apply to authentication and indicate if an MFA challenge appears. The expected behavior of the MFA policy is enforced, and items such as device trust, MFA IP suppression, MFA risk suppression, etc. can be used.

When a user signs into OneLogin with Trusted IdP, the user experience doesn't differ from other authentication methods. To configure Trusted IdPs in OneLogin, complete the following steps. 

  1. Go to Authentication > Trusted IdPs and select New Trust.

  2. Provide a name for the Trusted IdP configuration

  3. In the Trusted IdP Settings tab, check Enable Trusted IDP in the Enable/Disable field.

  4. In the Login Options section, if you wish to represent this Trusted IdP as an authentication option on the tenant’s login page via an icon, then check Show in Login panel and provide a url to a suitable icon. (Note; websites typically host a “favicon.ico” file that could be used e.g. https://www.onelogin.com/favicon.ico

  5. In the Configurations section, enter the Issuer URL or issuer name for the third-party identity provider in the Issuer field. Note: This field only applies to SAML and OIDC (not OAuth).

  6. The Email Domains field is used to automatically invoke this Trusted IdP when a user enters their email address at login time - if the email address is unrecognized, but belongs to one of the domains listed, then this TIdP will be invoked via an authentication request (SAML, OIDC or OAuth as appropriate).

  7. To enable Standard mode, check Sign users into OneLogin. This allows inbound identities from the Identity Provider to be matched to local user accounts within the tenant, via responses to the /access/idp endpoint.  

  8. Deselect Sign users into additional applications: this option enables proxy mode, which is discussed later.

  9. To send the user identity within the authentication request sent to the Trusted Identity Provider, check Send Subject Name ID or Login Hint in Auth Request: if the Trusted IdP is configured to use SAML, then the authentication request is sent as a Subject NameID parameter whilst if OIDC or OAuth is used, the same information is sent as a query string parameter called login_hint. This feature is to provide an improved user experience by avoiding the need for the user to provide an identifier to both OneLogin and the Trusted IdP.

    Note: Not all Identity Providers support this setting and may even return an error (for example, Azure returns an error when using this option with SAML).

  10. In the User Attribute section, follow the steps below.


    • Enter the Trusted IdP response attribute which is used for User Attribute Mapping in the User Attribute Value field.

      Behavior varies depending upon the chosen protocol:


      • SAML - hard-coded to extract the SAML Subject NameID. It can't be changed.
      • OIDC - if left blank, defaults to {tidp.email}, but alternate value can be specified.
      • OAUTH - there is no default. It is necessary to specify a value in the form {tidp.xxxx}
    • In the User Attribute Mapping dropdown, assign the local attribute which will be used to match the inbound User Attribute Value from the Trusted IdP. Default setting is Email.

    • (Optional) Allowed Email Domains is a whitelist. This allows the administrator to restrict the acceptable email domains for inbound identities. If empty, there is no restriction.

  11. (Optional) In Third-Party Initiated Login Settings specify any desired Allowed Redirect URIs which are part of a URL format that can be used to invoke both a specific Trusted IdP as well as a specific target.

    Note: More information about this feature can be found in the Trusted IdP Discovery & Application Access document.

Select Protocol

  1. In the Protocol section, select your preferred protocol type: SAML, OIDC, or OAUTH. Once selected and configuration saved, the protocol becomes fixed for this Trusted IdP. Depending upon the selected protocol, provide relevant information as below:

    SAML


    • IdP Login URL (optional) - this is the endpoint where OneLogin will send the authentication request if an SP-initiated flow is used. Note: If you want your Trusted IdP to know what the user was trying to do before getting redirected by OneLogin to the Trusted IdP, you can include the origin URL in the IdP Login URL, using the {origin} macro. For example: https://mytrustedidp.company.com/saml?url={origin}

    • SP Entity ID - this is a dynamically-generated, read-only value that must be registered at the Trusted IdP for use as the Audience element of SAML responses.

    • Trusted IdP Certificate - this is provided by the Identity Provider and is used to validate the signature on the inbound SAML responses.

    • Encryption (optional) - when enabled, the desired certificate must be selected. The certificate must be registered with the Identity Provider so that it can issue encrypted SAML responses that only your OneLogin tenant can decrypt.

    • Single Logout - SLO is only available for SAML based IDP configurations. If a user logs in with an IdP that supports SLO, then we provide a hub that logs the user out of the configured IdP. For the initial session termination, OneLogin gives precedence to the configured Trusted IdP used to log in, then proceeds to the subsequent apps that support single logout.

      Note: The SLO chain terminates if any app or IdP fails to respond. SLO isn't a 100% reliable strategy to terminate user sessions across all services. Since there are potential failures, we recommend this as part of an overall solution to manage user sessions.

      We offer support and validations for: 


      • OneLogin
      • Ping
      • HTTP-redirect, but not post bindings.

    OIDC (using the authorization code flow)


    • Authentication Endpoint - this is the endpoint at the Trusted IdP where OneLogin will send the authentication request.

    • Token Endpoint Auth. Method - this determines how the OneLogin tenant authenticates to the Trusted IdP’s token endpoint. Options are GET, POST or BASIC

    • Token Endpoint - this is the endpoint at the Trusted IdP where OneLogin will obtain the identity/access tokens on presentation of the authorization code. 

    • User Information Endpoint - this is the endpoint at the Trusted IdP from where OneLogin retrieves the required identity information on presentation of the access token.

    • Scopes - these are the scopes required by the Trusted IdP in order to return the desired information. This is generally in openid profile email    (note space separators).

    • Client Id - provided by the Trusted IdP during registration of the client that represents this OneLogin tenant.

    • Client Secret - provided by the Trusted IdP during registration of the client that represents this OneLogin tenant.

    OAUTH (using the authorization code flow)


    • Authentication Endpoint - this is the endpoint at the Trusted IdP where OneLogin will send the authentication request.

    • Token Endpoint Auth. Method - this determines how the OneLogin tenant authenticates to the Trusted IdP’s token endpoint. Options are GET, POST or BASIC

    • Token Endpoint - this is the endpoint at the Trusted IdP where OneLogin will obtain the identity/access tokens on presentation of the authorization code. 

    • User Information Endpoint - this is the endpoint at the Trusted IdP from where OneLogin retrieves the required identity information on presentation of the access token. Multiple endpoints can be defined, separated by pipe symbols (“|”).

    • Scopes - these are the scopes required by the Trusted IdP in order to return the desired information. The Trusted IdP will provide this information    (use space separators between multiple values).

    • Client ID - provided by the Trusted IdP during registration of the client that represents this OneLogin tenant.

    • Client Secret - provided by the Trusted IdP during registration of the client that represents this OneLogin tenant.

  2. Go to the administrative interface for the Trusted IdP (such as ADFS) and provide the IdP with your OneLogin tenant’s return URL endpoint: https://{your_subdomain}.onelogin.com/access/idp

    The fields in which you enter this value differ by IdP provider. Consult the documentation for your IdP but in general, for SAML Trusted IdPs, this is the Assertion Consumer Service URL (ACS URL) whereas for OIDC/OAuth it's referred to as the Redirect URI.

    For ADFS, you enter this value on the Configure URL and Configure Identifiers pages of the Add Relying Party Trust wizard, and the Endpoints tab on the Properties dialog for the relying party trust. For more information, see OneLogin Trusted IdP with ADFS.

    Sign Users into OneLogin with Specific TIDP Examples

    This section provides brief example OneLogin configurations for LinkedIn and Facebook.

LinkedIn

Use the steps & screenshot below to sign users into OneLogin with LinkedIn. 

  1. Select OAUTH from the Protocol Type dropdown.

  2. In the OAuth Configurations section, enter the Authentication Endpoint, Token Endpoint Auth Method, and the Token Endpoint.

  3. In the User Information Endpoint, enter https://api.linkedin.com/v2/me | https://api.linkedin.com/v2/emailAddress?q=members&projection=(elements*(handle~))

    Enter Scopes, Client ID, and Client Secret in the fields below.

    company apps


Facebook
Use the steps & screenshot below to sign users in to OneLogin with Facebook.

  1. The User Attribute Value is the source attribute from the response that should be mapped to the User Attribute Mapping.

  2. Select OAUTH from the Protocol Type dropdown.

  3. In the OAuth Configurations section, enter the Authentication Endpoint, Token Endpoint Auth Method, and the Token Endpoint.

  4. In the User Information Endpoint, enter https://graph.facebook.com/v3.3/me?fields=email,first_name,last_name

    Enter Scopes, Client ID, and Client Secret in the fields below.

    company apps

Access Applications with Standard Mode

Once the user gains access to your OneLogin tenant’s portal, courtesy of the Trusted IdP authentication, applications can be selected in the same way as for locally-authenticated users.

However, the Trusted IdP relationship can also be used to directly launch target applications without the need to interact with your OneLogin tenant’s portal. This can be achieved in many different ways and is discussed in the Trusted IdP Discovery & Application Access.

Proxy Mode

This feature can be thought of as a “pass-through” authentication. It is useful if you want to enable multiple organizations or departments not managed by you to have access to SAML applications connected to your OneLogin account, since most SAML-capable applications support only one SAML IdP per tenant. In this scenario, OneLogin acts as a SAML proxy and builds a new SAML assertion based on the data in the assertion from the Trusted IdP, but with the correct recipient, audience, and signature.

The SAML assertion sent to the target application will be based upon the SAML connector configuration, but the NameID and attribute values within the Attribute Statement from the original assertion will be used. It is important to double-check your Attribute Names before proceeding with a proxy mode setup. 

Note: Proxy mode does not utilize a local OneLogin user account and as a result has several limitations compared to the Standard mode:

    • User and App security policies are not applied (hence, no support for step-up authentication).

    • SP-initiated flows are not supported. 

    • Only Trusted IdP connections based on SAML can be used. OIDC/OAuth are not supported.

    • Only target applications integrated with OneLogin via SAML are supported. OIDC/WS-Federation/Forms-based/OneLogin Access applications are not supported.

    • OneLogin cannot enforce restrictions to prevent  access to the applications.

    • As there is no user account at your OneLogin tenant, provisioning to downstream applications is not supported.

Only a subset of the available settings are applicable to the Proxy mode.

  1. Go to Authentication > Trusted IdPs.

  2. Click the New Trust button.

  3. Provide a name for the Trusted IdP configuration

  4. On the Trusted IdP Settings tab, check Enable Trusted IDP in the Enable/Disable field.

  5. In the Configurations section, enter the Issuer URL or issuer name for the third-party identity provider in the Issuer field.

  6. To enable Proxy mode, check Sign users into additional applications. This enables the proxy endpoints of the form /saml/proxy/<app_id> to be established. SAML responses received at these endpoints will result in proxying to the application indicated by app_id.

  7. In the Protocol section, select SAML. (OIDC and OAUTH are not applicable to Proxy mode.)


    • SP Entity ID - this is a dynamically-generated, read-only value that must be registered at the Trusted IdP for use as the Audience element of SAML responses

    • Trusted IdP Certificate - this is provided by the Identity Provider and is used to validate the signature on the inbound SAML responses.

    • Encryption (optional) - when enabled, the desired certificate must be selected. The certificate must be registered with the Identity Provider so that it can issue encrypted SAML responses that only your OneLogin tenant can decrypt.

  8. On the Apps page, select the app you want users to access using the Trusted IdP.

    company apps

  9. Click the app row to open a dialog where you can view and copy the SAML Sign-on URL.

    company apps

  10. Cancel out of the dialog and click Save on the Apps or Settings tab.

  11. Go to the administrative interface for the Trusted IdP (such as ADFS) and provide the IdP with the application's SAML Sign-on URL that you copied in step 9.

    The fields in which you enter this value differ by IdP provider. Consult the documentation for your IdP for guidance.
    For ADFS, you enter this value on the Configure URL and Configure Identifiers pages of the Add Relying Party Trust wizard, and the Endpoints tab on the Properties dialog for the relying party trust. For more information, see OneLogin Trusted IdP with ADFS.

Encrypt SAML assertions in Trusted IdP responses

Your third-party IdP may require encrypted SAML assertions or attributes in the SAML response. OneLogin supports encrypted SAML assertions, whether signed or not, but only if the entire SAML response message is signed. 

To enable encrypted assertions, you provide a public OneLogin X.509 certificate when you configure your Trusted IdP in OneLogin. That certificate will be used to encrypt SAML assertions sent by your third-party IdP to OneLogin. OneLogin will detect the encryption and decrypt the assertion automatically.

In order to support encrypted SAML assertions or attributes, you must:

  1. Select the Enable encrypted assertions option when you configure your Trusted IdP in OneLogin.
    The X.509 Certificate field appears after you select the option.

    company apps

  2. Select a OneLogin X.509 certificate. We recommend that you create a new certificate for each Trusted IdP that requires encrypted SAML assertions. You can click the Generate a new certificate link to go to the Creating and Applying Certificates page and create a new certificate, but you should save your changes on the Trusted IdP edit page first. You'll leave this page when you click the link and will have to navigate back to it to complete your Trusted IdP setup.

Compare Standard and Proxy Trusted IdP Modes

The diagram illustrates the two modes and their primary capabilities. Both modes can be enabled concurrently, but the mode in use is driven by the location that the IdP sends the SAML response to. Fundamentally, with Standard mode, the identity passed to the downstream application is based upon the identity as defined by the OneLogin account, whilst with Proxy mode, the identity is directly based on the user information held at the IdP. Combining both modes concurrently is more likely to cause confusion and so is best avoided.


company apps





Expand/Collapse Comments
: