Configure Local JWT Token Provider (Optional)#

Configure OAuth2 OpenID Connect (OIDC) is the preferred method to obtain and validate tokens. If you do not have the capability to use or run an OpenID Connect provider and wish to enable the REST API, built-in user name plus password and local token creation is a substitute option. The Colectica Portal REST API and MCP server can use locally obtained JWT tokens for bearer authentication when this provider is configured. The local JWT provider can only be used if OpenID Connect is disabled. Follow these instructions to enable the local JWT Token Provider.

  1. In PortalDir\appsettings.json, find the LocalJwtProvider section.

    "LocalJwtProvider":
{
  "Enabled": "false",
  "SymmetricSecurityKey": "A secret string that must be at least 32 characters long"
}

  2. Set the Enabled property to true.

  3. Set the SymmetricSecurityKey property to a secret string that is at least 32 characters long. Requests for tokens are refused if the key is shorter.

  4. Users obtain tokens using their portal accounts, so their roles are the roles assigned in Users.

Usage#

To obtain an access token from the local provider, POST a JSON request to https://example.org/token/createtoken containing:

{
  "username" : "user@example.org",
  "password" : "examplePassword"
}

When you authenticate correctly, you will receive an access token and its expiration date. Tokens are valid for 30 days.

{
  "access_token": "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJ1bmlxdWVfbmFtZSI6InVzZXJAZXhhbXBsZS5vcmciLCJuYW1laWQiOiI3YWNiOGJkZi00NjVlLTQ4ZmItOTIyYS0yODVkMWIzYjVlNWQiLCJqdGkiOiI0OTA4OTNkNi0yMGJjLTQ4MWUtYTEyMy1jODMyMTAzMWI2YzMiLCJlbWFpbCI6InVzZXJAZXhhbXBsZS5vcmciLCJyb2xlIjoiQ29sZWN0aWNhR3Vlc3QiLCJuYmYiOjE1OTA0NDYxMzYsImV4cCI6MTU5MzAzODEzNiwiaWF0IjoxNTkwNDQ2MTM3fQ.iCzQsJ_B5g_MgLJ4uLPBrsMOyhTOMlkrE_gA4aUB8x0",
  "expires": "2026-10-17T12:00:00Z"
}

When making requests to the Colectica Portal REST API, use the access token with bearer authentication in the request header.

Authorization: Bearer eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9...

Windows Authentication#

When the portal uses Windows authentication, a token can be obtained by sending a GET request to https://example.org/token/createwindowstoken with Windows credentials. The response has the same form as above, and the token carries the Colectica roles assigned to the Windows user.