How Do I Configure Active Directory JWT Authentication for AgilePoint NX v8.x?

To enable Active Directory JWT authentication to sign in to AgilePoint NX Portal in AgilePoint NX v8.x and lower, do the procedure in this topic.

Background and Setup

Prerequisites

Good to Know

  • JWT authentication uses a bearer token instead of basic authentication for Active Directory.
  • Basic authentication is the default method for Active Directory authentication to AgilePoint NX v8.x and lower. Basic authentication uses a header in the format Authorization: Basic <credentials>.

Configure AgilePoint Server

To configure AgilePoint Server to support Active Directory JWT authentication, do the procedure in this topic.

How to Start

  1. On the AgilePoint Server machine, open the file (AgilePoint Server instance installation folder) C:\Program Files\AgilePoint\AgilePointServerInstance\bin\Ascentn.AgilePoint.WCFService.exe.config.

Procedure

  1. In the file Ascentn.AgilePoint.WCFService.exe.config, add or change this key.
    Field NameDefinition

    ADAuthToJwt_AllowedAudiences
    Description:
    Specifies the audience for the JSON Web Token (JWT).

    The audience must be your AgilePoint NX Portal instance.

    Allowed Values:
    An appSettings key in the following format:

    <add key="ADAuthToJwt_AllowedAudiences" value="[your AgilePoint NX Portal instance URL]" />

    For more information, refer to Find your Portal Instance URL.

    Default Value:
    None
    Example:
    <add key="ADAuthToJwt_AllowedAudiences" value="https://mynxportal:443" />
  2. Do one of these:
    • In the file Ascentn.AgilePoint.WCFService.exe.config, add or change this key.
      Field NameDefinition

      ADAuthToJwt_SigningSecretKey
      Description:
      Specifies the secret key to sign the JSON Web Token (JWT).
      Allowed Values:
      An appSettings key in the following format:

      <add key="ADAuthToJwt_SigningSecretKey" value="[a string to sign the token]" />

      The string value must be greater than or equal to 16 characters.

      Default Value:
      None
      Example:
      <add key="ADAuthToJwt_SigningSecretKey" value="mysigningsecretkey" />
    • If you do not want to use ADAuthToJwt_SigningSecretKey token signing secret key in the Ascentn.AgilePoint.WCFService.exe.config file, do this.
      1. Create a certificate.

        You can get a certificate from the authority or you can create a self-signed certification, and use it.

        Use makecert.exe to create a self-signed certificate.

      2. On the AgilePoint Server machine, install the certificate.
      3. In the file Ascentn.AgilePoint.WCFService.exe.config, add or change this key.
        Field NameDefinition

        ADAuthToJwt_SigningCertificateSubject
        Description:
        Specifies the subject line of the certificate used to sign the JSON Web Token (JWT).
        Allowed Values:
        An appSettings key in the following format:

        <add key="ADAuthToJwt_SigningCertificateSubject" value="[subject line of the certificate - can have spaces]" />

        Default Value:
        None
        Example:
        <add key="ADAuthToJwt_SigningCertificateSubject" value="My Token Signing Certificate" />
  3. Restart the AgilePoint Server instance.

    For more information, refer to Restarting AgilePoint Server and AgilePoint Portal.

Configure AgilePoint Portal

To configure AgilePoint Portal to support Active Directory JWT authentication, do the procedure in this topic.

How to Start

  1. On your AgilePoint Server machine, open the file (NX Portal installation folder - v8.0 and lower) C:\Program Files\AgilePoint\AgilePointWebApplication\AgilePointPortal\web.config

Procedure

  1. In the file web.config, add or change these keys.
    Field NameDefinition

    EnableJWTAuthentication
    Description:
    Specifies whether to use JSON Web Token (JWT) for Active Directory authentication as an alternative to the basic authentication.
    Allowed Values:
    An appSettings key in the following format:

    <add key="EnableJWTAuthentication" value="[true/false]" />

    • true - Specifies JWT authentication for Active Directory.
    • false - Specifies basic authentication for Active Directory.
    Default Value:
    false
    Example:
    <add key="EnableJWTAuthentication" value="true" />

    portalurl
    Description:
    Specifies the AgilePoint Portal Instance URL.
    Allowed Values:
    A globalVariables key in this format:

    "portalurl": "[AgilePoint Portal Instance URL]"

    For more information, refer to Find your Portal Instance URL.

    Default Value:
    None
    Example:
    "portalurl": "https://mynxportal:443"
  2. Reset IIS.