Accessing nevisIDM over REST from nevisAuth ScriptState

The nevisIDM REST services can be accessed from within the nevisAuth AuthState ScriptState with an API included in the package nevisidmcl. To make the API available in the ScriptState, the classpath of the AuthEngine must be extended with the path/opt/nevisidmcl/nevisauth/lib. The API can be used to cover use-cases which are not supported out-of-the-box by the nevisIDM authentication plug-ins.

API

The API is located in the package ch.nevis.idm.client and supports the following elements:

IdmRestClient

nevisAuth 4.38.x HTTP client changes

The new HTTP client shipped with nevisAuth 4.38.0.12 will likely require changes in this auth state configuration, specifically in the area of certificate configuration and handling.

Visit Appendix H for additional information.

The IdmRestClient can be used to access nevisIDM as the nevisauth user. The supported methods are listed in the following table.

Method	Inputs	Output	Description
String get (String url)	String url: URL of the REST endpoint.	String containing the JSON response body.	Performs a GET request to the input URL. Throws an IdmRestClientException if the return code is greater than or equal to 400.
String patch (String url, String body)	String url: URL of the REST endpoint. String body: JSON request body to be used in the PATCH request.	String containing the JSON response body.	Performs a PATCH request to the input URL with the input request body. Throws an IdmRestClientException if the return code is greater than or equal to 400.
String post (String url, String body)	String url: URL of the REST endpoint. String body: JSON request body to be used in the POST request.	String containing the location header, if available.	Performs a POST request to the input URL with the input request body. Throws an IdmRestClientException if the return code is greater than or equal to 400.
void put (String url)	String url: URL of the REST endpoint.	-	Performs a PUT request to the input URL. Throws an IdmRestClientException if the return code is greater than or equal to 400.
void delete (String url)	String url: URL of the REST endpoint.	-	Performs a DELETE request to the input URL. Throws an IdmRestClientException if the return code is greater than or equal to 400.
HttpResponseWrapper getWithResponse (String url, HttpRequestWrapper request)	String url: URL of the REST endpoint. HttpRequestWrapper request: Request as HttpRequestWrapper.	Response in HttpResponseWrapper with headers and body.	Performs a GET request to the input URL. Payload in the Request not supported.
HttpResponseWrapper patchWithResponse (String url, HttpRequestWrapper request)	String url: URL of the REST endpoint. HttpRequestWrapper request: Request as HttpRequestWrapper.	Response in HttpResponseWrapper with headers and body.	Performs a PATCH request to the input URL.
HttpResponseWrapper postWithResponse (String url, HttpRequestWrapper request)	String url: URL of the REST endpoint. HttpRequestWrapper request: Request as HttpRequestWrapper.	Response in HttpResponseWrapper with headers and body.	Performs a POST request to the input URL.
HttpResponseWrapper putWithResponse (String url, HttpRequestWrapper request)	String url: URL of the REST endpoint. HttpRequestWrapper request: Request as HttpRequestWrapper.	Response in HttpResponseWrapper with headers and body.	Performs a PUT request to the input URL.
HttpResponseWrapper deleteWithResponse (String url, HttpRequestWrapper request)	String url: URL of the REST endpoint. HttpRequestWrapper request: Request as HttpRequestWrapper.	Response in HttpResponseWrapper with headers and body.	Performs a DELETE request to the input URL. Payload in the Request not supported.

IdmRestClientFactory

The IdmRestClientFactory is a factory to get an instance of an IdmRestClient.

Method	Input	Output	Description
IdmRestClient get(Map<Object, Object> scriptStateProperties)	Map<Object, Object> ScriptState configuration parameters to pass HttpClient configuration.	An IdmRestClient instance.	A factory to get an instance of an IdmRestClient.

HttpResponseWrapper

Method	Input	Output	Description
getHeaders()		Map<String, List<String>>	Retrieves headers.
getPayLoad()		byte[]
getLocation()		String	Null if no such header exists, otherwise returns first value stored in Location header.
getStatusCode()		int	HTTP Status code of the response.

HttpRequestWrapper

Method	Input	Output	Description
getHeaders()		Map<String, List<String>>	Retrieves headers set. Currently only Content-Type and Charset supported.
setHeaders()	Map<String, List<String>>		Set headers overwriting previous ones. Currently only Content-Type and Charset supported.
addToHeaders()	String headerName, List<String> header		Adds new header to the request. Currently only Content-Type and Charset supported.
setPayLoad(byte[])	byte[]
getPayLoad()		byte[]

IdmRestClientException

The IdmRestClientException is a runtime exception that is thrown in case of failures in the IdmRestClient.

AuthTokenProvider

The AuthTokenProvider creates a signed token with the provided lifetime for the nevisauth user in nevisIDM.

Method	Input	Output	Description
String getAuthTokenString(long timeToLive)	long timeToLive: The lifetime of the signed token in seconds.	String containing a signed token for the nevisauth user in nevisIDM.	Creates a signed token for the nevisauth user in nevisIDM. The lifetime of the token corresponds with the value provided in timeToLive. Throws an AuthTokenProviderException in case of failure.

AuthTokenProviderFactory

The AuthTokenProviderFactory is a factory to get an instance of an AuthTokenProvider.

Method	Output	Description
AuthTokenProvider getInstance()	An AuthTokenProvider instance.	A factory to get an instance of an AuthTokenProvider.

AuthTokenProviderException

The AuthTokenProviderException is a runtime exception that is thrown in case of failures in the AuthTokenProvider.

IdmRestClient HTTP configuration

The IdmRestClient uses the HttpClient from nevisAuth, and it offers all the configuration options of that in the ScriptState properties parameter. With a notable difference in the prefix, it must contain the idm keyword before the httpclient. This is required to distinguish the IdmRestClient configuration from potential other HttpClient instance configurations. (The parameter prefix is telling the ScriptState that this should be available in the parameters variable.)

• parameter.idm.httpclient.* (String)

  Configure the outgoing HTTP communication towards nevisIdm. For a list of valid HTTP properties, see HTTP Client.

  info

  As the IdmRestClient is a singleton, therefore the configuration will be initialized only on the first usage, therefore only one configuration is possible. To not rely on the order of ScriptState definitions in the esauth4.xml the parameters variable should be always passed.

Example

The following code block shows a simple GET REST request example to retrieve all pending terms of a user.

NevisAuth ScriptState Configuration

 <AuthState name="IdmLoginRestGetTerms" class="ch.nevis.idm.authstate.IdmPasswordVerifyState" authLevel="auth.weak">
 <ResultCond name="ok" next="IdmRestGetTerms"/>
 <ResultCond name="default" next="IdmLoginRestGetTerms"/>
 <Response value="AUTH_CONTINUE">
 <Gui name="AuthUidPwDialog" label="login.uidpw.label">
 <GuiElem name="lasterror" type="error" label="${notes.lasterrorinfo}" value="${notes.lasterror}"/>
 <GuiElem name="client" type="text" label="client.label" value="${notes.client}"/>
 <GuiElem name="isiwebuserid" type="text" label="userid.label" value="${notes.loginid}"/>
 <GuiElem name="isiwebpasswd" type="pw-text" label="password.label"/>
 <GuiElem name="submit" type="button" label="submit.button.label" value="Login"/>
 </Gui>
 </Response>
 </AuthState>

 <AuthState name="IdmRestGetTerms" class="ch.nevis.esauth.auth.states.scripting.ScriptState" final="false">
 <ResultCond name="ok" next="AuthDone"/>
 <ResultCond name="failed" next="AuthError"/>
 <property name="script" value="file:///var/opt/nevisauth/default/conf/get-terms.groovy"/>
 <property name="parameter.baseUrl" value="https://<your-host>:8989/nevisidm/api" />
 <property name="parameter.idm.httpclient.tls.keyObjectRef" value="DefaultKeyStore"/>
 <property name="parameter.idm.httpclient.tls.trustStoreRef" value="DefaultTrustStore"/>
 </AuthState>

Script get-terms.groovy

import ch.nevis.idm.client.IdmRestClient
import ch.nevis.idm.client.IdmRestClientFactory
import groovy.json.JsonSlurper

IdmRestClient idmRestClient = IdmRestClientFactory.get(parameters)

String baseUrl = parameters.get('baseUrl')
String clientExtId = session.get('ch.adnovum.nevisidm.user.clientExtId')
String userExtId = session.get('ch.adnovum.nevisidm.user.extId')
String endPoint = "$baseUrl/core/v1/$clientExtId/users/$userExtId/terms-pending"

String result
try {
 result = idmRestClient.get(endPoint)
} catch(Exception e) {
 LOG.error(e)
 response.setResult('failed')
 return
}
def json = new JsonSlurper().parseText(result)
String pendingTermsExtIds = json['items'].extId.join(',')
session.put('ch.adnovum.nevisidm.user.pendingTermsExtIds', pendingTermsExtIds)
response.setResult('ok')