Internal Authentication

Internal authentication is used to protect internal applications (e.g. MyApps, OneTouch enrollment or FedSigning). It can also be used for signature flows, see more below.

To set up an internal authentication endpoint, you can either just follow the "Application" guides in the config GUI, or in the PAS configuration manager, if you click "Advanced", and then "Internal authentication endpoints" you can add authentication endpoints there, following this format:

{
  "id": "my_internal_endpoint_id",
  "authenticatorId": "my_authenticator_id",
  "successURL": "/selfservice",
  "addRoles":"auth:selfservice_enabled_user", //optional / legacy, see note below
  "includeQueryString": "true" //optional, default is false
}

So you simply configure an ID, an authenticator, a success URL, and optionally, roles that should be added after successful authentication. This internal authentication endpoint is available via the following path: "<base_url>/authentication/internal/<internal_endpoint_id>/login". Where "base_url" is the base URL of the module you want to authenticate for (this is important as the authentication cookie is unique for the base path). The base_url is often the same as the successURL. Once you have set up your internal authentication endpoint, simply add the id of the endpoint to your module configuration like such:

{
  "id": "my_prism_module",
  "name": "com.phenixidentity~phenix-prism",
  "enabled": "true",
  "config": {
    "base_url": "/selfservice",
    "internal_authentication_endpoint": "my_internal_endpoint_id",
    "module_refs": "selfservice_module_id"
  }
}

This will make your /selfservice path redirect to your new internal authentication endpoint (if you are not already authenticated at the module). If the authentication is successful, you are redirected to your successURL, which in this example is a PRISM module that opens SelfService.

{
    "name": "com.phenixidentity~phenix-prism-selfservice",
    "enabled": "false",
    "prism_enabled": "true",
    "config": {
      "display_name": "guides.selfservice.title",
      "base_uri": "selfservice",
      "http_configuration_ref": "6fd8f1a7-1f2e-41f0-b91f-24ebcecb53a1",
      "url_prefix": "http://192.168.0.117:8085/",
      "resource_ref": "c713cd42-dc6b-492a-9c4f-1c5f00d2b9e3",
      "use_push": "true",
      "requires_role": "auth:selfservice_enabled_user"
    },
    "guide_id": "guides.selfservice",
    "created": "2024-03-06T13:04:57.245Z",
    "id": "9bc6e399-cbe8-4f96-98ac-c93703ce0b5b"
}

We can see that the configuration of selfservice requires a specific role: "auth:selfservice_enabled_user" which allows us to access the selfservice module. When we configured our internal authentication endpoint we added a property "addRoles" that added this role so that we can access it. Roles can still be added in the authentication pipe as it has been before, this is simply an extra configuration option to make authenticators more reusable.

A note on 'roles'

Traditionally, the requires_role parameter seen above has been important to include, and this remains the case if your internal application is protected via either legacy authenticators or via an auth_redirect_uri in the PRISM module. If you have configured a internal_authentication_endpoint in the PRISM app, the roles are obsolete. If you are unsure on how to configure this, do not remove your old roles without knowing it is OK to do so.

The resulting UserID

After an internal authentication is complete, the UserID tied to the session is important in the subsequent application the user logged in to. It is displayed in the header of Prism-applications, and is used to tie e.g. enrolled authentication tokens to the user. A UserID is automatically injected into the session upon a completed authentication flow using an internal authentication endpoint, however the value of this UserID depends on what authenticator has been used. For example, BankID authenticator will return the user's userPersonalNumber. You may override this value by configuring userIdentifierAttribute in the internal authentication endpoint. Doing so will extract a new UserID from the resulting item attribute. The resulting UserID must be a singular non-empty value to be accepted. If no such value is found, the flow will fail hard and not allow the authentication. Example configuration:

{
    "id" : "my-endpoint",
    "authenticatorId" : "my-authenticator",
    "successURL" : "/pdf_sign",
    "userIdentifierAttribute": "uid"
}

Signature flows

Internal endpoints also define signature flows, available on "<base_url>/authentication/internal/<internal_endpoint_id>/sign". A signature flow means that authenticators will use sign transactions instead of auth transactions in e.g. BankIDAuthenticator. It will also display a SignMessage to the user, letting them know what they are signing. When the signature endpoint is used, it will look for additionally configured parameters in the internal authentication endpoint. See below:

{
    "id" : "my-endpoint",
    "authenticatorId" : "my-authenticator",
    "successURL" : "/pdf_sign/sign/api/sign",
    "prepareSignMessagePipeId" : "signmessagepipe1",
    "signMessage" : "{{item.signMessage}}",
    "additionalSignData" : "{{item.additionalSignData}}"
}

A signature flow requires a non-empty signMessage to run. This can either be configured directly, or via a preparation pipe as seen in the example above. Both signMessage and additionalSignData are expandable with the item and session scopes. The idea is that you run a preparation pipe defined via prepareSignMessagePipeId that prepares an item with your signMessage and additionalSignData so they may be expanded like above. This allows your messages and data to be completely dynamic depending on what you may want to sign in the flow you have set up.

Authenticators that support innate usage of signMessage will display it (e.g. BankIDAuthenticator, AnonymousAssignmentAgnostic, FrejaAuthenticator, and more...) in their execution, and authenticators that do not support innate usage will instead present an additional frontend view displaying the message so that the user may accept what they are signing.

Authenticators that support innate usage of additionalSignData (e.g. BankIDAuthenticator, FrejaAuthenticator, NiasAuthenticator) will also include this in their signature. For example, in a BankIDAuthenticator the signMessage maps to userVisibleData and additionalSignData maps to userNonVisibleData. Configured values of those attributes will be overridden in a signature flow.

An important note is that an internal authenticator using a signature flow will not produce a signature by itself -- it simply enables for it by setting authenticators in a sign mode, displays a sign message, and includes additional data like described above. Internal endpoints using signature flows are intended for usage combined with the FedSigning module. The flow is then:

• The FedSigning module displays a preview of a PDF to sign
• The user clicks "Sign", and is redirected to an authentication URL
• This authentication URL points to an internal authentication endpoint in sign mode, i.e. "<base_url>/authentication/internal/<internal_endpoint_id>/sign"
• The user completes the signature interaction by identifying themselves (signing)
• The internal authentication endpoint fills the session with attributes from the authentication and then redirects to the success url (FedSigning module)
• The FedSigning module runs its signature pipe producing the final PDF signature, using the attributes added to the session by the internal authentication endpoint

Tags

Authentication Signing