Using an external identity provider

Applies to NAM 2018

Successful integration of NAM with a third-party service for SSO is dependent on familiarity with the third-party software and procedures. The activities specific to third-party products listed below are only general pointers to the activities that your administrator would need to carry out in detail in the third-party product. Where the third-party documentation differs from these instructions, follow the third-party documentation.

For more about SSO, see Single sign-on (SSO) in NAM.

Deciding whether to use an external identity provider

See SSO terminology for help with terms.

Why you might want to use an external identity provider (IdP):

  • If you already use a supported external IdP to manage authentication for other applications, you may also want to use that same provider to manage authentication for NAM. You would then be signed on to NAM automatically after signing on to one of those other applications.
  • If you want to consolidate user credentials management in your organization, this option may be appropriate for you.

Why you might not want to use an external IdP:

  • When you use an external IdP, SSO traffic has to be passed to and from the external IdP.
    If your work environment does not permit such external links, you simply cannot use an external IdP.
  • Using an external IdP may require significant additional configuration effort up front.
    • If all you want is an easy option to configure and use, you want to use the default, with no external IdP.
    • If you don't mind the additional configuration effort (maybe you already use an external IdP), the additional configuration effort may be worth your time.

Authentication with external IdP

Console sign-on with external IdP:
NAM Console authentication: external

Server sign-on with external IdP:
NAM Server authentication: external

Authentication details with external IdP:
NAM 2018 with external IdP

Before you switch to an external IdP

  1. Make sure local user accounts will still have access to their content:
    To maintain access to your content (such as custom reports and alerts) after switching to an external IdP, it is important that the user names on the external IdP match the user names you used locally before switching. If the user names match, you will continue to see your content.

    Important

    After you switch to an external IdP and verify that users have access to their reports, you may want to delete unneeded local accounts. However, you must keep a local administrator account so you can revert to local NAM Console login temporarily. If your external provider becomes unavailable for any reason, you will need to log in using a local account so you can conduct maintenance or troubleshooting activities.

    For example, a one-time metadata update is planned for NAM 2018 Service Pack 1 that will require you to temporarily revert to your local admin account as part of applying the service pack.

  2. Make sure users maintain group membership:

    Users assigned to groups you created on the NAM Console will continue to be members of those groups regardless of group membership in the external IdP.

    Users assigned to groups on the external IdP will continue to be members of those groups as long as you create (or already have) groups with the same names on the NAM Console.

    • If you assign user A to group G1 in the NAM Console, and to groups G1 and G2 on the external IdP, user A is assigned to groups G1 and G2 at login (assuming G1 and G2 exist on the NAM Console).
    • If you subsequently remove user A from groups G1 and G2 on the external IdP, user A is still assigned to group G1 at login because you made that assignment locally in the NAM Console.

Using OpenAM as an external IdP

Starting with NAM 2018, NAM supports integration with OpenAM as a SAML 2.0 SSO IdP (Single Sign-On Identity Provider) for the management of users and groups. No other provider has been tested up to this point.

Important

This procedure applies only if you are integrating NAM with OpenAM as a third-party service for SSO, so all NAM sign-in activity goes through your OpenAM account. In this case:

  • NAM Console is the SP
  • OpenAM is the IdP

To successfully integrate NAM with an external IdP (OpenAM in this example), you need:

  • Working knowledge of OpenAM.
  • An OpenAM realm for NAM users.
  • The ability to enable communication (HTTPS or HTTP) between your OpenAM realm and your NAM Console machine.
  • A console public URL that is active and set correctly. This URL is used by the NAM Console to create the metadata that is imported to SSO (for example, OpenAM). See SSO network configuration requirements for network configuration requirements.
  • Review the information in Before you switch to an external IdP

If your organization already uses OpenAM to manage SSO for other applications, you may already have OpenAM expertise in your group. Otherwise, you need to consult the OpenAM provider's site for their documentation.

Section 1. In NAM Console, get the NAM Console metadata

  1. In the NAM Console, open Authentication ► SSO and federation.
  2. In the XML metadata of Service Provider section, click Download metadata.
  3. Save the file for use in the next section.

Section 2. In OpenAM, configure a realm and add NAM Console as a Remote Service Provider.

  1. Log in as an administrator to your OpenAM account.
  2. Create a new OpenAM realm.
  3. Integrate the new realm with LDAP.
  4. Create a new Circle of Trust.
  5. Create and configure a Hosted Identity Provider (OpenAM), and assign it to the newly created Circle of Trust.
  6. Create and configure a Remote Service Provider (in this case, your NAM Console) and import the NAM Console metadata file into OpenAM. You downloaded this file in section 1 above. Assign it to the same Circle of Trust.
  7. Use the following URI:
    https://<IdP_FQDN>:<port>/openam/saml2/jsp/exportmetadata.jsp?entityid=https://<IdP_FQDN>:<port>/openam&realm=/<realmname>
    to get and save the OpenAM metadata to the file. You will provide this to the NAM Console in the next section.
  8. Download the OpenAM metadata file for use in the next section.

Section 3. In NAM Console, import the OpenAM metadata file

  1. In the NAM Console, open Authentication ► SSO and federation.
  2. In the XML metadata of Identity Provider section, click Upload.
  3. Select and upload the metadata file you downloaded from OpenAM in section 2.
  4. In the User attribute mappings and User group attribute mappings sections, set up user- and group-related attributes. These are necessary to correctly identify users and groups from, for example, integrated LDAP or directly from the SSO. If they differ from your attributes, you may need to map them within OpenAM after configuring your Hosted Identity Provider.
  5. Set the Active switch in the External Identity Provider section to On.

Reverting to local NAM Console login

If you lose access to your external IdP, you can switch back to your local NAM Console login for troubleshooting. To do so, add ?local to the full NAM Console login URL. For example:

https://address:port/console/login.xhtml?local

where address and port are the address and port of your NAM Console installation. When you open that URL in your browser, you are presented with the local login screen.

Heads up for NAM 2018 Service Pack 1

Applies to NAM 2018 Service Pack 1

As part of configuring an external IdP, you need to export the SSO metadata from the NAM Console and import it into the external IdP configuration. For example, in Using OpenAM as an external IdP , you export the NAM Console metadata in section 1 and import it into OpenAM in section 2.

Be aware that NAM 2018 Service Pack 1 requires you to export and import that metadata once more after you apply the service pack. Without doing so, you will be unable to sign in to the NAM Console through the external IdP.

This procedure is a one-time necessity. It will not be required in subsequent service packs.

  1. Follow the service pack instructions to apply it to your NAM 2018 installation.

    At this point, you will be temporarily unable to sign in to the NAM Console using your external SSO account.

  2. Sign in to the NAM Console using the local admin account. To do so, add ?local to the full NAM Console login URL. For example:

    https://address:port/console/login.xhtml?local

    where address and port are the address and port of your NAM Console installation. You can then enter the credentials for your local account using the local log-in screen.

  3. In the NAM Console, open Authentication ► SSO and federation.

  4. In the XML metadata of Service Provider section, click Download metadata and save the file. You will need this new metadata in the next step.

  5. In the configuration screens of your external SSO provider, open the configuration for NAM and import the metadata you have exported from the NAM Console.

After you complete this procedure, you should be able to sign on to the NAM Console through the external SSO provider.