Configuration

In development, the authentication configuration is used by the development server launched by the "neos run" command. The configuration has to be done in a YAML configuration file of the cluster. When the authentication configuration changes, there is no need to regenerate.

In production, the authentication configuration is used by the gateway. The configuration must be done in the gateway configuration file.

Configuring authentication can be complex, so the framework provides presets to make it easy and to fit the most common scenarios. It is also possible to provide a complete configuration without preset to address more specific cases.

Presets

The standard development server (default)

By default, when a cluster is created via the neos init command, an authentication configuration is defined in the configuration.auth.yml file:

Authentication:
  Preset: NeosDevAuth

We provide a standard authentication server that can be used by clusters under development.

This authentication server offers a connection via a unique identifier and password, but also a connection via the Groupe Isagri Active Directory.

During development, you can log in with your Groupe Isagri Active Directory account or delete the authentication configuration file.

The registration of new users is not yet publicly available because it will be managed by the "Users" transversal module. This development is in progress.

It is important to note that the authentication server is not yet ready to be used in production. It will be improved as we go along as we plan to make it the standard solution we offer to all collaborators.

The source code of the project is available on Azure DevOps.

External providers

It is also possible to set up an authentication through an external provider.

This scenario is ideal to avoid having the responsibility of the authentication server.

Here you will find guides for several external provider (the list will grow as time goes on):

Microsoft Entra External ID
Azure AD B2C (No longer recommended and replaced by Microsoft Entra External ID. Will be retired in May 2030.)
Azure Active Directory
Auth0

If you need an authentication with several providers at the same time (for example a Google connection, a Microsoft connection and a classic login/password connection), you will have to use a custom authentication server (like Auth0, Okta or an homemade authentication server).

Manual configuration

If the framework does not provide a preset for the desired authentication server, you can specify a complete configuration using this template :

Authentication:
  Authority: # (required) The URL of the authentication server.
  ClientId: # (required) The resource identifier of the cluster.
  ClientSecret: # (optional) The resource secret of the cluster.
  Scopes: # (optional) The list of scopes so that the cluster must have access.
  McpScopes: # (optional) The list of scopes advertised to MCP clients (defaults to Scopes when not set).
  UserPropertiesMap: # (optional)
    Identifier: # (optional) The name of the token claim used to retrieve the user's identifier to populate the `Identifier` property of the Neos user.
    Email: # (optional) The name of the token claim used to retrieve the user's email to populate the `Email` property of the Neos user.
    FirstName: # (optional) The name of the token claim used to retrieve the user's first name to populate the `FirstName` property of the Neos user.
    LastName: # (optional) The name of the token claim used to retrieve the user's last name to populate the `LastName` property of the Neos user.
    CustomProperty1: # (optional) The name of the token claim used to populate the user's additional properties of the Neos user.
    # ...
  ServiceAccountClaimNames: # (optional) For client credentials flow, the claim names to use for service account identifier, in order of preference. Default values are: "azp", "appid", "sub".
    - azp
    - appid
    - sub
  AdditionalJwtAuthorities: # (optional) Additional JWT authorities for validating tokens from other identity providers. Useful when using Azure AD B2C for user authentication while also accepting client credentials tokens from Azure AD.
    - Name: # (required) A unique name for this authority (will be used as the authentication scheme name).
      Authority: # (required) The authority URL (e.g., https://login.microsoftonline.com/{tenant}/v2.0).
      ValidAudiences: # (required) The valid audiences for tokens from this authority.
        - audience1
        - audience2
      ValidIssuers: # (optional) The valid issuers for tokens from this authority. If not specified, the issuer will be validated against the authority's metadata.
        - issuer1
        - issuer2
      IssuerPattern: # (optional) A pattern to match against the token issuer for routing purposes. Example: "login.microsoftonline.com" to match all Azure AD issuers.
  CookieLifetimeInHours: # (optional) The cookie lifetime in hours. 48 hours by default.

Example with a custom authentication server :

Authentication:
  Authority: https://localhost:5001
  ClientId: b68c22cc-6e48-4ff8-bf3f-49f70e388376
  Scopes:
    - custom_scope
  UserPropertiesMap:
    Name: username
    Email: principal_email
  CookieLifetimeInHours: 72

McpScopes

An MCP client does not always request the same scope as the cluster's own web login: the web login can use the bare identity provider App ID URI as its scope, while an MCP client may need the full API scope URI to be granted an access token for the protected resource it exposes. Setting the MCP scope directly in Scopes would then break the web login (for example, an Azure AD B2C custom policy can then fail to return an id_token, since the requested scope combination differs from what the login flow expects).

McpScopes lets you configure the scope advertised to MCP clients independently of Scopes. When it is not set (or set to an empty list), it defaults to Scopes, preserving the previous behavior.

Authentication:
  # ...
  Scopes:
    - b68c22cc-6e48-4ff8-bf3f-49f70e388376 # used by the web login
  McpScopes:
    - https://xxx.onmicrosoft.com/b68c22cc-6e48-4ff8-bf3f-49f70e388376/API.DefaultAccount # used by MCP clients

ServiceAccountClaimNames

When using client credentials flow (service-to-service authentication), the framework needs to identify the calling service. The ServiceAccountClaimNames property defines which JWT claims to check for the service account identifier, in order of preference.

Default values are: azp (authorized party), appid (Azure AD application ID), and sub (subject). These are standard JWT claims used by different identity providers to identify service principals.

Example with Azure AD:

Authentication:
  # ...
  ServiceAccountClaimNames:
    - appid          # Azure AD uses 'appid' for service principals
    - sub

AdditionalJwtAuthorities

In scenarios where you need to accept tokens from multiple identity providers, you can configure additional JWT authorities. This is useful when your application uses one identity provider for user authentication (e.g., Azure AD B2C) but also needs to accept service-to-service tokens from another provider (e.g., Azure AD).

Each additional authority requires:

Name : The name of the additional authority
Authority: The URL of the identity provider
ValidAudiences: The list of valid audiences (resource identifiers) that this authority issues tokens for
ValidIssuers (optional): Specific valid issuers. If not specified, the issuer is validated against the authority's metadata
IssuerPattern (optional): A pattern to match against the token issuer for routing purposes

Example with Azure AD B2C for users and Azure AD for service accounts:

Authentication:
  Preset: AzureAdB2C
  # ... (Azure AD B2C configuration for users)
  AdditionalJwtAuthorities:
    - Name: AzureADServicePrincipal
      Authority: https://login.microsoftonline.com/{tenant}/v2.0
      ValidAudiences:
        - api://your-app-id
      ValidIssuers:
        - https://sts.windows.net/{tenant}/
      IssuerPattern: login.microsoftonline.com

If you want to use a custom authentication server, the authentication server must comply with the OpenID Connect standard and allow the "Authorization Code Flow + PKCE" flow.

If you want to use the standard development authentication server that we offer in production and/or you want to adapt a behavior, you must fork the project, adjust it and deploy it by yourself.

User synchronization with authentication provider

To be able to synchronize a user from your cluster to the authentication provider, you'll need to set the AuthenticationMode configuration property with one of the following value :

AzureB2C for synchronization with Azure AD B2C provider.
Neos for synchronization with Neos dev auth provider.

Production

In production, authentication is configured at the Gateway level.

It must be put in the gateway secret, please see this article for more information.

Table of Contents