Configure Active Directory JWT Authentication

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

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. 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.

Prerequisites

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
    Function:
    Specifies the audience for the JSON Web Token (JWT).

    The audience must be your AgilePoint NX Portal instance.

    Accepted 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
      Function:
      Specifies the secret key to sign the JSON Web Token (JWT).
      Accepted 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
        Function:
        Specifies the subject line of the certificate used to sign the JSON Web Token (JWT).
        Accepted 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 Windows service.

Configure AgilePoint Portal

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

Prerequisites

How to Start

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

Procedure

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

    EnableJWTAuthentication
    Function:
    Specifies whether to use JSON Web Token (JWT) for Active Directory authentication as an alternative to the basic authentication.
    Accepted 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
    Function:
    Specifies the AgilePoint Portal Instance URL.
    Accepted Values:
    An appSettings key in the following format:

    <add key="PortalUrl" value="[AgilePoint Portal Instance URL]" />

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

    Default Value:
    None
    Example:
    <add key="PortalUrl" value="https://mynxportal:443" />
    Limitations:
    • When AgilePoint NX is installed, this value is not required. Therefore, it is not configured by default. However, some configuration changes require this value to be configured.
    • If you are configuring JWT authentication, the value of this field should match the value of ADAuthToJwt_AllowedAudiences key in the file (AgilePoint Server installation folder) C:\Program Files\AgilePoint\AgilePoint Server\bin\Ascentn.AgilePoint.WCFService.exe.config
  2. Reset IIS.