/
Miscellaneous standard service tasks in Identity Manager

Nexus Documentation

Miscellaneous standard service tasks in Identity Manager

This article includes updates for Identity Manager 6.0.

OIDC: Authorization request service task

This BPMN service task initiates an OpenID Connect Authorization Code flow.

That task is responsible for generating an OpenID Connect (OIDC) Authorization Request URL and preparing the redirection to the Identity Provider (IdP).

It acts as the entry point by:

  • building the authorization request object

  • generating the redirect URI

  • store the authorization request info into the process map

Configuration

Most OIDC providers expose a discovery document.

That document usually contains the endpoints required by this feature:

  • authorization URI

  • token URI

  • JWKS URI

The clientId and clientSecret needs to be created on the IdP side.

Parameter

Mandatory

Value

Description

Parameter

Mandatory

Value

Description

authorizationUri

 

OIDC provider authorization endpoint.

tokenUri

 

OIDC token endpoint.

jwksUri

 

JWKS endpoint.

clientId

 

Identifier of the application requesting access.

clientSecret

 

Client credential.

scope

 

Requested OIDC scopes separated by a space.

initiationMode

DIRECT, ASYNC

The authorization request mode.

DIRECT: the authorization will be made opening the authorization request URI into a new browser tab.

ASYNC: the user will have to open a link validating the authorization request status before being redirected to the the authorization request URI.

callbackMessageName

oidcCallback

Name of the BPMN message event triggered after the OIDC callback has been processed. Use this to match the waiting message event in the process. 

plugoutUrl

plugoutUrl

Process variable to put the plugout URL.

titleMessage

 

<h1>Remote ID Verification</h1>

Plain text shown as title of the authentication page.

successMessage

 

<p style=”color: green”>User identification successful!<br>You can now close this window.</p>

Plain text shown to the user after successful authentication.

errorMessage

 

<p style=”color: red”>An error occurred during authentication.</p>

Plain text shown to the user if authentication fails.

Additional OIDC parameters

Additional parameters can be added to the authorization using the key value pairs such as:

Parameter

Value

Description

Parameter

Value

Description

login_hint

${Person_PersonnelNumber}

Attach the Person Personal number to the login_hint parameter.

acr_values

urn:eident:acrp:level:high

Sets the level of assurance for the identification.

Result variables

Depending on configuration, the service task may add the following variables to the process map:

Variable

Description

Variable

Description

oidcAuthRequestStatus

Set to PENDING.

The authorization request status (oidcAuthRequestStatus) can have the following values:

  • PENDING

  • TIMEOUT

  • SUCCESS

  • ERROR

Errors

In case of an error, the task will throw an exception with the code: AUTH_REQUEST_ERROR

OIDC: Verify JWT claims service task

This service task is responsible for verifying that specific claims inside a previously validated ID Token are present and match expected values.

The task allows you to:

  • Define required claims

  • Define a claim and the internal attribute that should be compared with

  • Choose whether to store a detailed verification report

  • Decide whether mismatches should trigger a business error

Configuration

Parameter

Mandatory

Value

Description

Parameter

Mandatory

Value

Description

requiredClaims

 

Space-separated list of claims that must be present in the verified JWT. Example: "sub,preferred_username,email

jwtClaimsVerified

oidcJwtClaimsVerified

Variable name to store the JWT claims verification boolean value.

storeJwtClaimsVerificationReport

false

If true, a verification report will be stored in the process map. The variable name is "oidcJwtClaimsVerificationReport". The report contains the claims verification status and their values.

throwErrorOnJwtClaimsMismatch

false

If true, the task will throw an error if any of the required claims is missing in the JWT or if the claims values cannot be matched with internal values.

Example of claims verification

In addition of the required claims, you can add key value pairs to configure the claims verification:

Parameter

Value

Description

Parameter

Value

Description

given_name

${Person_FirstName}

Compare the claim "given_name" with the internal value of the Person first name.

birthDate

${Person_BirthDate}

Compare the claim "given_name" with the internal value of the Person first name.

birthDate.dateFormat

dd.MM.YYYY

That .dateFormat is a suffix to define the pattern used to format the claim value.

acr

urn:eident:cert:eidas:high

Verify that the Authentication Context Class Reference matchess the requirement.

Result variables

Depending on configuration, the service task may add the following variables to the process map:

Variable

Description

Variable

Description

oidcJwtClaimsVerified

Final boolean verification result.

oidcJwtClaimsVerificationReport

Optional textual verification report.

Verification semantic

The verification result is considered successful only if:

  • all required claims are present

  • all configured claim/value pairs match

  • no configured comparison is marked as not verifiable

If throwErrorOnJwtClaimsMismatch = true, the task throws a BPMN error whenever the final result is not fully successful.

Errors

In case of a verification error, the task will throw an exception with the code: OIDC_JWT_CLAIMS_VERIFICATION_ERROR

Get personal info from SPAR service task and SPAR connector

Description

Use this task to send a new request to SPAR server and receive information about a person.

Prerequisites

The environment variables below must be set. If some of them are missing, there will be an error logged with the names of the missing variables (comma-separated list) and also a BPMN error with the names of the variables as the message.

Setting the com.nexus.prime.spar.SparEnvironmentVariables logger in log4j to DEBUG level will log all the variables and values when loaded. The variables will be loaded only the first time.

Environment variables

smartid_spar_url smartid_spar_certificate_location smartid_spar_certificate_pin smartid_spar_truststore_location smartid_spar_truststore_password smartid_spar_iden_KundNrLeveransMottagare smartid_spar_iden_KundNrSlutkund smartid_spar_iden_UppdragId smartid_spar_iden_SlutAnvandarId

Configuration

To use this task, configure the following delegate expression in your service task:

${sparPersonsokTask}

The name of the task in the Identity Manager Admin is "SPAR: get Person info from SPAR".

The following parameters can be configured in Identity Manager Admin:

Parameter

Mandatory

Value

Description

Parameter

Mandatory

Value

Description

ssnFieldName

-

The name of the process variable where the SSN for the searched person is stored.

personFoundFieldName

Default value:

  • SPAR_PersonFound

The name of the result variable where to put info if person was found or not. 

resultsPrefix

Default value:

  • SPAR

The prefix for all the result variable names.

isVisibleNamn

Default value:

  • false

Boolean value. If true, the info from "namn" will be returned. See Result below for more info.

isVisiblePersondetaljer

Default value:

  • false

Boolean value. If true, the info from "persondetaljer" will be returned. See Result below for more info.

isVisibleFolkbokforing

Default value:

  • false

Boolean value. If true, the info from "folkbokforing" will be returned. See Result below for more info.

isVisibleUtlandsadress

Default value:

  • false

Boolean value. If true, the info from "utlandsadress" will be returned. See Result below for more info.

Result

The following variables may be returned to the process data. Please note that some variables may be missing even if the condition is affirmative, if there is no result from the server for them.

For understanding what each result represents, please see the SPAR documentation here: https://www.statenspersonadressregister.se/master/start/teknisk-info/xml-scheman/20211/aviseringpost/

In the table below, all the variables are set with the default prefix (SPAR) and default names (SPAR_PersonFound):

Variable

Condition

Description

Variable

Condition

Description

SPAR_PersonFound

always

If the person was found or not. Boolean value.

If the SSN is invalid, instead of this result, a BMPN error will be thrown (SPAR_VALIDATION). See "BPMN errors" below.

 

SPAR_Namn_Aviseringsnamn

isVisibleNamn = true

String value.

For more information, see https://www.statenspersonadressregister.se/master/start/teknisk-info/xml-scheman/20211/namn/

SPAR_Namn_Fornamn

isVisibleNamn = true

String value.

For more information, see https://www.statenspersonadressregister.se/master/start/teknisk-info/xml-scheman/20211/namn/

SPAR_Namn_Tilltalsnamn

isVisibleNamn = true

Integer value.

For more information, see https://www.statenspersonadressregister.se/master/start/teknisk-info/xml-scheman/20211/namn/

SPAR_Namn_Mellannamn

isVisibleNamn = true

String value.

For more information, see https://www.statenspersonadressregister.se/master/start/teknisk-info/xml-scheman/20211/namn/

SPAR_Namn_Efternamn

isVisibleNamn = true

String value.

For more information, see https://www.statenspersonadressregister.se/master/start/teknisk-info/xml-scheman/20211/namn/

SPAR_Persondetaljer_Sekretessmarkering

isVisiblePersondetaljer = true

Boolean value (not "JA", "NEJ" as in the SOAP response)

For more information, see https://www.statenspersonadressregister.se/master/start/teknisk-info/xml-scheman/20211/persondetaljer/

SPAR_Persondetaljer_SekretessmarkeringSattAvSPAR

isVisiblePersondetaljer = true

Boolean value (not "JA", "NEJ"  as in the SOAP response)

For more information, see https://www.statenspersonadressregister.se/master/start/teknisk-info/xml-scheman/20211/persondetaljer/

SPAR_Persondetaljer_SkyddadFolkbokforing

isVisiblePersondetaljer = true

Boolean value (not "JA", "NEJ"  as in the SOAP response)

For more information, see https://www.statenspersonadressregister.se/master/start/teknisk-info/xml-scheman/20211/persondetaljer/

SPAR_Persondetaljer_AvregistreringsorsakKod

isVisiblePersondetaljer = true

String value.

If the person is deceased, this variable will tell by a special code.

For more information, see https://www.statenspersonadressregister.se/master/start/teknisk-info/xml-scheman/20211/persondetaljer/

SPAR_Persondetaljer_Fodelsedatum

isVisiblePersondetaljer = true

XMLGregorianCalendar value.

For more information, see https://www.statenspersonadressregister.se/master/start/teknisk-info/xml-scheman/20211/persondetaljer/

SPAR_Persondetaljer_FodelselanKod

isVisiblePersondetaljer = true

String value.

For more information, see https://www.statenspersonadressregister.se/master/start/teknisk-info/xml-scheman/20211/persondetaljer/

SPAR_Persondetaljer_Fodelseforsamling

isVisiblePersondetaljer = true

String value.

For more information, see https://www.statenspersonadressregister.se/master/start/teknisk-info/xml-scheman/20211/persondetaljer/

SPAR_Persondetaljer_Kon

isVisiblePersondetaljer = true

String value.

see documentation at https://www.statenspersonadressregister.se/master/start/teknisk-info/xml-scheman/20211/persondetaljer/

SPAR_Persondetaljer_SvenskMedborgare

isVisiblePersondetaljer = true

Boolean value (not "JA", "NEJ"  as in the SOAP response)

For more information, see https://www.statenspersonadressregister.se/master/start/teknisk-info/xml-scheman/20211/persondetaljer/

SPAR_Folkbokforing_DatumFrom

isVisibleFolkbokforing = true

XMLGregorianCalendar value.

For more information, see https://www.statenspersonadressregister.se/master/start/teknisk-info/xml-scheman/20211/folkbokfoering/

SPAR_Folkbokforing_FolkbokfordLanKod

isVisibleFolkbokforing = true

String value.

For more information, see https://www.statenspersonadressregister.se/master/start/teknisk-info/xml-scheman/20211/folkbokfoering/

SPAR_Folkbokforing_FolkbokfordKommunKod

isVisibleFolkbokforing = true

String value.

For more information, see https://www.statenspersonadressregister.se/master/start/teknisk-info/xml-scheman/20211/folkbokfoering/

SPAR_Folkbokforing_Hemvist

isVisibleFolkbokforing = true

String value.

For more information, see https://www.statenspersonadressregister.se/master/start/teknisk-info/xml-scheman/20211/folkbokfoering/

SPAR_Folkbokforing_Folkbokforingsdatum

isVisibleFolkbokforing = true

XMLGregorianCalendar value.

For more information, see https://www.statenspersonadressregister.se/master/start/teknisk-info/xml-scheman/20211/folkbokfoering/

SPAR_Folkbokforing_DistriktKod

isVisibleFolkbokforing = true

String value.

For more information, see https://www.statenspersonadressregister.se/master/start/teknisk-info/xml-scheman/20211/folkbokfoering/

SPAR_Utlandsadress_Utdelningsadress1

isVisibleUtlandsadress = true

String value.

For more information, see https://www.statenspersonadressregister.se/master/start/teknisk-info/xml-scheman/20211/internationell-adress/

SPAR_Utlandsadress_Utdelningsadress2

isVisibleUtlandsadress = true

String value.

For more information, see https://www.statenspersonadressregister.se/master/start/teknisk-info/xml-scheman/20211/internationell-adress/

SPAR_Utlandsadress_Utdelningsadress3

isVisibleUtlandsadress = true