This document describes how to authenticate automatically within the various DigDash Enterprise modules (dashboards, configuration pages) without using the ‘pass’ parameter.

The principle is that, once authenticated, a token is requested which, when used, allows a new session to be created based on the one requested by the current session.
This token allows an automatic session to be created without having to specify the user’s password.
This token is single-use; the same token cannot be used to create more than one session. To create multiple sessions, multiple tokens are required.

Requesting an AuthToken

There are three different ways to authenticate when requesting a token.

• Logged in with username and password: 
  The token request is made via a web service with a URL in the following format:
  http://localhost:8080/ddenterpriseapi/DDEnterpriseServlet?user=admin&pass=admin&method=newAuthToken

• Using basic authentication:

  Using curl with the -u option: you will be prompted for the password after the request is executed.

  curl -u <user> http://localhost:8080/ddenterpriseapi/DDEnterpriseServlet?method=newAuthToken

  By specifying the header yourself: the request takes the following form:

  curl -H 'Authorization: Basic <base64(user:pass)>' http://localhost:8080/ddenterpriseapi/DDEnterpriseServlet?method=newAuthToken

• Using a JWT token:

  The token is requested via a request. The JWT (JSON Web Token) is specified in the HTTP header for authentication.
  This JWT is generated via the DigDash REST API without a defined target user (targetUser). See the section Creating a JWT token for further details.
  The request takes the following form (example using a curl request):

  curl -H "Authorization: Bearer <JWT>" "http://localhost:8080/ddenterpriseapi/DDEnterpriseServlet?method=newAuthToken"

  where <JWT> should be replaced with the JWT token obtained previously.

• Using an API key:
  The API key is requested via a request. The API key is specified in the HTTP header for authentication.
  This API key is generated via the DigDash REST API without a defined target user (targetUser). See the section Creating an API key for further details.
  The request takes the following form (example using a curl request):

  curl -H "X-API-KEY: <apikey>" "http://localhost:8080/ddenterpriseapi/DDEnterpriseServlet?method=newAuthToken"

  where <apikey> should be replaced with the API key obtained previously.

Themethod=newAuthToken parameterallows the URL or request response to retrieve the new AuthToken generated in this way.

Using the AuthToken in a URL

Once you have retrieved the AuthToken, you can use it in a URL to create an automatic session without entering any authentication details.

For example, for a dashboard, it would be used as follows:
http://localhost:8080/digdash_dashboard/index.html?user=admin&authToken=token
The authToken parameter must be set to the token retrieved in the previous step.

Advanced: Identity borrowing

The API’s newAuthToken method returns a token for the current session and the current user. You must therefore have a session for that user in order to call this method and use its result in a URL.

In some cases, this is a constraint, and it is useful to be able to open a session for another (target) user, using a source user. There is a ` newAuthTokenAs ` method which takes an additional `userId` parameter.

The following prerequisites are required to use this method:

• The system must have the property PROP_NEWAUTHTOKENAS = true in system.xml
• The source user must have the Admin > Allow impersonate authorisation.

Once these prerequisites have been met, proceed as follows depending on the authentication method used:

• Logged in with username and password: 
  The target user must be specified in the URL when requesting the token in the following format:
  http://localhost:8080/ddenterpriseapi/DDEnterpriseServlet?user=admin&pass=admin&method=newAuthTokenAs&userId=utilisateurCible

• Via basic authorisation:

  Using curl with the -u option: you will be prompted for the password after the request has been executed.

  curl -u <user> http://localhost:8080/ddenterpriseapi/DDEnterpriseServlet?method=newAuthTokenAs&userId=utilisateurCible
  

  By specifying the header yourself: the request takes the following form (example using a curl request):

  curl -H "Authorization: Bearer <JWT>" "http://localhost:8080/ddenterpriseapi/DDEnterpriseServlet?method=newAuthTokenAs&userId=utilisateurCible"
  
• Via a JWT token:
  This JWT token is generated via the DigDash REST API without a defined target user (targetUser). See the section Creating a JWT token for further details.

  The request takes the following form (example using a curl request):

  curl -H "Authorization: Bearer <JWT>" "http://localhost:8080/ddenterpriseapi/DDEnterpriseServlet?method=newAuthTokenAs&userId=utilisateurCible"

  where<JWT>should be replaced with the JWT token obtained previously.

• Using an API key:
  This API key is generated via the DigDash REST API without a defined target user (targetUser). See the section Create an API key for further details.
  The request takes the following form (example using a curl request):

  curl -H "X-API-KEY: <apikey>" "http://localhost:8080/ddenterpriseapi/DDEnterpriseServlet?method=newAuthTokenAs&userId=utilisateurCible"
  

  where<apikey>should be replaced with the API key obtained previously. 

Themethod=newAuthTokenAs parameterallows the URL or request response to retrieve the new AuthToken generated in this way.

You can then use the token in a URL to create an automatic session without authentication details.
For example, for a dashboard, in the following format:
http://localhost:8080/digdash_dashboard/index.html?user=utilisateurCible&authToken=token
The ` authToken ` parameter must be set to the token retrieved in the previous step.