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

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.

IdmRestClientFactory

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

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

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.

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" />
 </AuthState>

Script get-terms.groovy

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

IdmRestClient idmRestClient = new IdmRestClientFactory().getInstance()

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')